BinaryBuilder.jl

BinaryBuilder.jl automatically manages several low-level compatibility issues to ensure binaries are portable across different machines and operating systems. These include:

• Uniform Compiler Interface: Provides a consistent environment where gcc, g++, and gfortran are available via standard names or triplet-prefixed names (e.g., x86_64-linux-gnu-gcc).
• glibc Versioning: Compiles against older glibc versions to ensure maximum compatibility with newer Linux distributions.
• gfortran ABI Compatibility: Handles the broken ABI transitions in gfortran (6.X $\rightarrow$ 7.X and 7.X $\rightarrow$ 8.X) by building against multiple versions and selecting the correct one at runtime.
• Library Dependencies: Automatically fixes improper library linkage (especially on macOS) by using RPATH/RUNPATH semantics.
• Embedded Absolute Paths: Automatically converts symlinks within the build prefix to relative paths and warns if files contain absolute paths to the build prefix.
• Instruction Set Architecture (ISA): Disassembles binaries to ensure they do not use instructions that exceed the target architecture's minimum supported instruction set. It also detects cpuid instructions, which indicate the binary is handling instruction set detection internally.

Because BinaryBuilder uses cross-compilation, you must categorize dependencies based on whether they are for the target (where the code runs) or the host (where the code is built):

1. Dependency (Target): Binary libraries the final product needs to link to. These are built for the target platform and will be included in the final JLL package.
2. BuildDependency (Target): Binary libraries or executables (like shell scripts) needed only during the build process for the target platform. These are not included in the final JLL package.
3. HostBuildDependency (Host): Binary executables needed during the build that cannot run on the target platform (e.g., a build tool like cmake or ninja).
   • These are installed under ${host_prefix}.
   • Executables are located in ${host_bindir}, which is automatically added to the ${PATH}.
   • Use this for tools available in a JLL package for the x86_64-linux-musl platform.

Note: If your target library requires another library to link against, you must use a Dependency (Target), not a HostBuildDependency.

The workflow for distributing a binary dependency via BinaryBuilder follows these steps:

1. Local Development: Compile your library (C, C++, Rust, etc.) locally and write Julia bindings using Libdl.dlopen() and ccall().
2. Create a Build Recipe: Create a build_tarballs.jl file. This file defines the name, version, source locations, build steps (as a bash script), and the resulting products. You can use the Wizard interface to generate this or manually edit/copy existing recipes from the Yggdrasil repository.
3. Build Tarballs: Run the build process to generate compiled binaries for various platforms.
4. Generate JLL Package: A successful build results in an autogenerated JLL (Julia Library) package. These are typically uploaded to the JuliaBinaryWrappers GitHub organization.
5. Registration: A registration request is opened against the General Julia registry. This allows end-users to simply run pkg> add libfoo_jll to install your binary dependency.

When building numerical libraries, you must choose an integer model for array indexing: LP64 (32-bit integers) or ILP64 (64-bit integers).

Recommended Strategy: Use libblastrampoline

For 64-bit systems, it is recommended to use the ILP64 interface via libblastrampoline_jll. This matches Julia's default behavior and allows switching backends at runtime.

Implementation details:

• Dependency: Use Dependency("libblastrampoline_jll"; compat="5.4.0") and pass julia_compat="1.9" to build_tarballs.
• Linking (Unix): Use -lblastrampoline.
• Linking (Windows): Use -lblastrampoline-5 (where 5 is the major version).
• Naming: On 64-bit systems, BLAS/LAPACK function calls must use the _64 suffix (e.g., dgemm_64).

Alternative: Always use LP64

If renaming symbols to the _64 suffix is too difficult, you can always use the LP64 interface, even on 64-bit systems.

• Option A: Link to libblastrampoline, but you must ensure an LP64 library is backing it. Note that Julia does not provide a default LP64 backing for libblastrampoline on 64-bit systems.
• Option B: Link directly to a library that provides an LP64 interface on 64-bit platforms, such as OpenBLAS32_jll.