frostwire-jlibtorrent

jlibtorrent is composed of platform-independent Java wrapper classes and platform-specific native JNI libraries (.dll, .so, .dylib).

Successful builds generate two types of artifacts:

1. Core wrapper library: jlibtorrent-w.x.y.z.jar (required for all platforms).
2. Platform-specific binaries: JAR files containing the native libraries for specific architectures (e.g., jlibtorrent-windows-w.x.y.z.jar, jlibtorrent-linux-arm64-w.x.y.z.jar).

Artifact locations:

• JAR files: ./build/libs/
• Raw native libraries: ./swig/bin/release/

The SWIG wrapping process relies on two primary files:

• libtorrent.i: Contains the SWIG extensions, ignores, and directives required to wrap the libtorrent library.
• libtorrent.h: Included by the .i file, containing manually defined C++ functions.

The jlibtorrent project uses a split artifact structure.

• Main Artifact (jlibtorrent): Contains the platform-independent Java class files, source code (-sources.jar), and Javadoc (-javadoc.jar). This is the only artifact that includes sources and documentation.
• Native Artifacts: Platform-specific artifacts (e.g., jlibtorrent-windows, jlibtorrent-linux, jlibtorrent-macosx-arm64) contain only the binary native libraries (.dll, .so, or .dylib). These do not include sources or Javadoc because the Java API documentation is already provided in the main artifact.

To regenerate the SWIG bindings, you must use a macOS environment with local dependencies (libtorrent, boost, and openssl) checked out at the required versions. Ensure the local libtorrent repository is at the target commit before running the script.

Prerequisites for SWIG

• macOS with Xcode / command-line tools
• SWIG 4.3.1 installed locally
• JDK 17
• Local libtorrent checkout at ~/src/libtorrent
• Local boost at ~/src/boost_1_88_0
• Local openssl at ~/src/openssl

# 1. Prepare libtorrent
cd ~/src/libtorrent
git fetch origin <commit>
git checkout RC_2_0
git reset --hard <commit>
git submodule update --init

# 2. Run SWIG
cd swig
export SRC="${HOME}/src"
export BOOST_MAJOR="1"
export BOOST_VERSION="88"
export BOOST_MINOR="0"
export LIBTORRENT_ROOT="${SRC}/libtorrent"
export OPENSSL_VERSION="3.5.2"
./run-swig.sh

To build the project on macOS, use the provided build-macos.sh script. This script automatically selects the correct architecture build scripts.

If you are making changes to the SWIG wrapping layer, you can use the --swig-only flag to skip other build steps. If you have already completed SWIG work and are only working on the Java Abstraction Layer, use the --build-only flag to skip the SWIG step and only build binaries and jars.

# Full build on macOS
./build-macos.sh 

# Build only SWIG related steps
./build-macos.sh --swig-only

# Skip SWIG and build only binaries and jars
./build-macos.sh --build-only

To ensure your build is compatible with Android's 16 KB page size requirement, you can verify the configuration using three methods:

1. During Build

Check your build logs for the presence of the linker flag --max-page-size=16384. This flag ensures native shared libraries (.so files) are aligned to 16 KB page boundaries.

2. On Device Testing

Connect an Android device and use adb to check the current page size:

3. APK Analysis

Use Android Studio to analyze the generated APK for any warnings related to page size compatibility.

# Check the page size on a device
adb shell getconf PAGE_SIZE

To reduce build times and manage system resources during the binary build process, follow these optimizations:

Reducing Build Time

• Use fast storage: Use an NVMe or SSD for Docker volumes instead of spinning drives.
• Preserve cache: Do not delete the build/libs directory between builds to allow reuse of cached artifacts.
• Limit parallel jobs: If you are running low on memory, reduce the number of CPU cores used by setting the CORES environment variable.

Recommended System Specifications

For full builds, the following specs are recommended:

• CPU: 8+ cores (16+ cores recommended)
• RAM: 16 GB minimum (32 GB recommended)
• Disk: 50 GB SSD minimum (100 GB for comfortable cache)
• Network: 100 Mbps+

# Reduce parallel jobs to manage low memory
export CORES=4
./docker_build_binaries.sh

You can build the project for different platforms using the provided scripts in the swig directory.

Build macOS binaries

Requirement: A macOS computer with Xcode Command Line Tools and Homebrew (including wget, pcre2, automake, autoconf, and bison).

cd swig
./prepare-macos.sh   # One-time setup
./build-macos.sh     # Build for current architecture

Build Windows, Linux, and Android

Requirement: Docker installed and running, with 8+ GB RAM (16+ GB recommended) and 20-30 GB free disk space.

cd swig
./docker_build_binaries.sh   # Builds Windows, Linux, Android

All Android native libraries are built with 16 KB page size compatibility for Google Play requirements.

To build the project binaries using Docker (this works on any OS and excludes macOS-specific libraries):

1. Navigate to the swig directory.
2. Run docker_build_binaries.sh.

cd swig && ./docker_build_binaries.sh