API reference

Types

BinaryBuilderBase.AbstractDependencyType

An AbstractDependency is a binary dependency of the JLL package. Dependencies are installed to ${prefix} in the build environment.

Concrete subtypes of AbstractDependency are

  • Dependency: a JLL package that is necessary for to build the package and to load the generated JLL package.
  • BuildDependency: a JLL package that is necessary only to build the package. This will not be a dependency of the generated JLL package.
BinaryBuilderBase.AbstractSourceType

An AbstractSource is something used as source to build the package. Sources are installed to ${WORKSPACE}/srcdir in the build environment.

Concrete subtypes of AbstractSource are:

BinaryBuilderBase.AnyPlatformType
AnyPlatform()

A special platform to be used to build platform-independent tarballs, like those containing only header files. FileProduct is the only product type allowed with this platform.

BinaryBuilderBase.ArchiveSourceType
ArchiveSource(url::String, hash::String; unpack_target::String = "")

Specify a remote archive in one of the supported archive formats (e.g., TAR or ZIP balls) to be downloaded from the Internet from url. hash is the 64-character SHA256 checksum of the file.

In the builder environment, the archive will be automatically unpacked to ${WORKSPACE}/srcdir, or in its subdirectory pointed to by the optional keyword unpack_target, if provided.

BinaryBuilderBase.BuildDependencyType
BuildDependency(dep::Union{PackageSpec,String})

Define a binary dependency that is necessary only to build the package. The argument can be either a string with the name of the JLL package or a Pkg.PackageSpec.

BinaryBuilderBase.DependencyType
Dependency(dep::Union{PackageSpec,String})

Define a binary dependency that is necessary to build the package and load the generated JLL package. The argument can be either a string with the name of the JLL package or a Pkg.PackageSpec.

BinaryBuilderBase.DirectorySourceType
DirectorySource(path::String; target::String = basename(path))

Specify a local directory to mount from path.

The content of the directory will be mounted in ${WORKSPACE}/srcdir, or in its subdirectory pointed to by the optional keyword target, if provided.

BinaryBuilderBase.DockerRunnerType
DockerRunner

Use docker as an execution engine; a reasonable backup for platforms that do not have user namespaces (e.g. MacOS, Windows).

BinaryBuilderBase.ExecutableProductType

An ExecutableProduct is a Product that represents an executable file.

On all platforms, an ExecutableProduct checks for existence of the file. On non-Windows platforms, it will check for the executable bit being set. On Windows platforms, it will check that the file ends with ".exe", (adding it on automatically, if it is not already present).

BinaryBuilderBase.ExtendedPlatformType
ExtendedPlatform(p::Platform; kwargs...)

Extend a Pkg.BinaryPlatforms.Platform object with extra key-value mappings. Arbitrary String values are supported, with the following constraints:

  • the key cannot be any of "os", "arch", "libc", "libgfortranversion", "libstdcxxversion", "cxxstring_abi";
  • if the key is called "march", only specific values are allowed, depending on what is the base platform,
  • all strings should only use alphanumeric characters, the underscore, or the dot (the latter only for the value).

This type is, for example, used to tag a standard platform from Pkg.BinaryPlatforms with additional features besides the C library or the compiler ABI.

julia> using BinaryBuilderBase

julia> ExtendedPlatform(Linux(:x86_64; libc=:glibc, compiler_abi=CompilerABI(; libgfortran_version=v"4")); march = "avx", cuda = "9.2")
ExtendedPlatform(Linux(:x86_64, libc=:glibc, compiler_abi=CompilerABI(libgfortran_version=v"4.0.0")); march="avx", cuda="9.2")
BinaryBuilderBase.FileProductType
FileProduct(path::AbstractString, varname::Symbol, dir_path = nothing)

Declares a FileProduct that points to a file located relative to the root of a Prefix, must simply exist to be satisfied.

BinaryBuilderBase.FileSourceType
FileSource(url::String, hash::String; filename::String = basename(url))

Specify a remote file to be downloaded from the Internet from url. hash is the 64-character SHA256 checksum of the file.

In the builder environment, the file will be saved under ${WORKSPACE}/srcdir with the same name as the basename of the originating URL, unless the the keyword argument filename is specified.

BinaryBuilderBase.FrameworkProductType

A FrameworkProduct is a Product that encapsulates a macOS Framework. It behaves mostly as a LibraryProduct for now, but is a distinct type. This implies that for cross-platform builds where a library is provided as a Framework on macOS and as a normal library on other platforms, two calls to build_tarballs are needed: one with the LibraryProduct and all non-macOS platforms, and one with the FrameworkProduct and the MacOS platforms.

BinaryBuilderBase.GitSourceType
GitSource(url::String, hash::String; unpack_target::String = "")

Specify a remote Git repository to clone form url. hash is the 40-character SHA1 revision to checkout after cloning.

The repository will be cloned in ${WORKSPACE}/srcdir, or in its subdirectory pointed to by the optional keyword unpack_target, if provided.

BinaryBuilderBase.LibraryProductType

A LibraryProduct is a special kind of Product that not only needs to exist, but needs to be dlopen()'able. You must know which directory the library will be installed to, and its name, e.g. to build a LibraryProduct that refers to "/lib/libnettle.so", the "directory" would be "/lib", and the "libname" would be "libnettle". Note that a LibraryProduct can support multiple libnames, as some software projects change the libname based on the build configuration.

BinaryBuilderBase.ProductType

A Product is an expected result after building or installation of a package.

Examples of Products include LibraryProduct, FrameworkProduct, ExecutableProduct and FileProduct. All Product types must define the following minimum set of functionality:

  • locate(::Product): given a Product, locate it within the wrapped Prefix returning its location as a string

  • satisfied(::Product): given a Product, determine whether it has been successfully satisfied (e.g. it is locateable and it passes all callbacks)

  • variable_name(::Product): return the variable name assigned to a Product

  • repr(::Product): Return a representation of this Product, useful for auto-generating source code that constructs Products, if that's your thing.

BinaryBuilderBase.UserNSRunnerType
UserNSRunner

A UserNSRunner represents an "execution context", an object that bundles all necessary information to run commands within the container that contains our crossbuild environment. Use run() to actually run commands within the UserNSRunner, and runshell() as a quick way to get an interactive shell within the crossbuild environment.

BinaryBuilder.Wizard.WizardStateType
WizardState

Building large dependencies can take a lot of time. This state object captures all relevant state of this function. It can be passed back to the function to resume where we left off. This can aid debugging when code changes are necessary. It also holds all necessary metadata such as input/output streams.

source

Functions

BinaryBuilderBase.accept_apple_sdkMethod
accept_apple_sdk(ins::IO, outs::IO) -> Bool

Ask the user whether they accept the terms of the macOS SDK, and return a boolean with their choice. Write messages to outs, read input from ins.

BinaryBuilderBase.choose_shardsMethod
choose_shards(p::Platform; rootfs_build, ps_build, GCC_builds,
                           LLVM_builds, archive_type)

This method chooses, given a Platform, which shards to download, extract and mount, returning a list of CompilerShard objects. At the moment, this always consists of four shards, but that may not always be the case.

BinaryBuilderBase.chown_cleanupMethod
chown_cleanup(dr::DockerRunner)

On Linux, the user id inside of the docker container doesn't correspond to ours on the outside, so permissions get all kinds of screwed up. To fix this, we have to chown -R $(id -u):$(id -g) $prefix, which really sucks, but is still better than nothing. This is why we prefer the UserNSRunner on Linux.

BinaryBuilderBase.compress_dirMethod
compress_dir(dir::AbstractString;
             compressor_stream = GzipCompressorStream,
             level::Int = 9,
             extension::AbstractString = ".gz",
             verbose::Bool = false)

Compress all files in dir using the specified compressor_stream with compression level equal to level, appending extension to the filenames. Remove the original uncompressed files at the end.

BinaryBuilderBase.create_and_bind_mutable_artifact!Method
create_and_bind_mutable_artifact!(f::Function, art_name::String)

Create (and bind) an artifact to MutableArtifacts.toml in one fell swoop. Used in things like .squashfs UID remapping and BB wizard state serialization.

BinaryBuilderBase.download_all_artifactsMethod
download_all_shards(; verbose::Bool=false)

Helper function to download all shards/helper binaries so that no matter what happens, you don't need an internet connection to build your precious, precious binaries.

BinaryBuilderBase.download_sourceFunction
download_source(source::AbstractSource; verbose::Bool = false)

Download the given source. All downloads are cached within the BinaryBuilder downloads storage directory.

BinaryBuilderBase.enable_apple_fileMethod
enable_apple_file()

Return the path to file that, if exists, indicates that the user accepts to download macOS SDK. The file is automatically created when the package is loaded if the environment variable BINARYBUILDER_AUTOMATIC_APPLE is set to "true".

BinaryBuilderBase.expand_cxxstring_abisMethod
expand_cxxstring_abis(p::Platform)

Given a Platform, returns an array of Platforms with a spread of identical entries with the exception of the cxxstring_abi member of the CompilerABI struct within the Platform. This is used to take, for example, a list of supported platforms and expand them to include multiple GCC versions for the purposes of ABI matching. If the given Platform already specifies a GCC version (as opposed to nothing) only that Platform is returned.

BinaryBuilderBase.expand_gfortran_versionsMethod
expand_gfortran_versions(p::Platform)

Given a Platform, returns an array of Platforms with a spread of identical entries with the exception of the gfortran_version member of the CompilerABI struct within the Platform. This is used to take, for example, a list of supported platforms and expand them to include multiple GCC versions for the purposes of ABI matching. If the given Platform already specifies a GCC version (as opposed to nothing) only that Platform is returned.

BinaryBuilderBase.expand_microarchitecturesMethod
expand_microarchitectures(ps::Vector{<:Platform})

Expand all platforms in the given vector with the supported microarchitectures.

julia> using BinaryBuilderBase

julia> expand_microarchitectures(filter!(p -> p isa Linux && libc(p) == :glibc, supported_platforms()))
12-element Array{Platform,1}:
 Linux(:i686, libc=:glibc)
 ExtendedPlatform(Linux(:x86_64, libc=:glibc); march="avx")
 ExtendedPlatform(Linux(:x86_64, libc=:glibc); march="avx2")
 ExtendedPlatform(Linux(:x86_64, libc=:glibc); march="avx512")
 ExtendedPlatform(Linux(:x86_64, libc=:glibc); march="x86_64")
 ExtendedPlatform(Linux(:aarch64, libc=:glibc); march="armv8")
 ExtendedPlatform(Linux(:aarch64, libc=:glibc); march="carmel")
 ExtendedPlatform(Linux(:aarch64, libc=:glibc); march="thunderx2")
 ExtendedPlatform(Linux(:armv7l, libc=:glibc, call_abi=:eabihf); march="armv7l")
 ExtendedPlatform(Linux(:armv7l, libc=:glibc, call_abi=:eabihf); march="neon")
 ExtendedPlatform(Linux(:armv7l, libc=:glibc, call_abi=:eabihf); march="vfp4")
 Linux(:powerpc64le, libc=:glibc)
BinaryBuilderBase.expand_microarchitecturesMethod
expand_microarchitectures(p::Platform)

Given a Platform, returns a vector of Platforms with a spread of identical ExtendedPlatform entries with the exception of the microarchitectures. If the given Platform is already an ExtendedPlatform with a march feature, only that platform is returned.

Currently, only platforms with architecture x86_64, amrv7l or aarch64 have supported microarchitectures. If the architecture of the platform does not have supported microarchitectures, a 1-element vector containing the given platform is returned.

julia> using BinaryBuilderBase

julia> expand_microarchitectures(FreeBSD(:x86_64))
4-element Array{Platform,1}:
 ExtendedPlatform(FreeBSD(:x86_64); march="avx")
 ExtendedPlatform(FreeBSD(:x86_64); march="avx2")
 ExtendedPlatform(FreeBSD(:x86_64); march="avx512")
 ExtendedPlatform(FreeBSD(:x86_64); march="x86_64")

julia> expand_microarchitectures(Linux(:armv7l))
3-element Array{Platform,1}:
 ExtendedPlatform(Linux(:armv7l, libc=:glibc, call_abi=:eabihf); march="armv7l")
 ExtendedPlatform(Linux(:armv7l, libc=:glibc, call_abi=:eabihf); march="neon")
 ExtendedPlatform(Linux(:armv7l, libc=:glibc, call_abi=:eabihf); march="vfp4")

julia> expand_microarchitectures(Linux(:aarch64))
3-element Array{Platform,1}:
 ExtendedPlatform(Linux(:aarch64, libc=:glibc); march="armv8")
 ExtendedPlatform(Linux(:aarch64, libc=:glibc); march="carmel")
 ExtendedPlatform(Linux(:aarch64, libc=:glibc); march="thunderx2")

julia> expand_microarchitectures(Windows(:i686))
1-element Array{Windows,1}:
 Windows(:i686)
BinaryBuilderBase.gcc_versionMethod
gcc_version(p::Platform, , GCC_builds::Vector{GCCBuild})

Returns the closest matching GCC version number for the given particular platform, from the given set of options. The compiler ABI and the microarchitecture of the platform will be taken into account. If no match is found, returns an empty list.

This method assumes that the compiler ABI of the platform represents a platform that binaries will be run on, and thus versions are always rounded down; e.g. if the platform supports a libstdc++ version that corresponds to GCC 5.1.0, but the only GCC versions available to be picked from are 4.8.5 and 5.2.0, it will return 4.8.5, as binaries compiled with that version will run on this platform, whereas binaries compiled with 5.2.0 may not.

BinaryBuilderBase.generate_compiler_wrappers!Method
generate_compiler_wrappers!(platform::Platform; bin_path::AbstractString,
                            host_platform::Platform = Linux(:x86_64; libc=:musl),
                            rust_platform::Platform = Linux(:x86_64; libc=:glibc),
                            compilers::Vector{Symbol} = [:c],
                            allow_unsafe_flags::Bool = false,
                            lock_microarchitecture::Bool = true)

We generate a set of compiler wrapper scripts within our build environment to force all build systems to honor the necessary sets of compiler flags to build for our systems. Note that while platform_envs() sets many environment variables, those values are intended to be optional/overridable. These values, while still overridable by directly invoking a compiler binary directly (e.g. /opt/{target}/bin/{target}-gcc), are much more difficult to override, as the flags embedded in these wrappers are absolutely necessary, and even simple programs will not compile without them.

BinaryBuilderBase.generate_per_uid_squashfsFunction
generate_per_uid_squashfs(cs, new_uid = getuid())

In order for the sandbox to work well, we need to have the uids of the squashfs images match the uid of the current unprivileged user. Unfortunately there is no mount-time option to do this for us. Fortunately, squashfs is simple enough that if the ID table is uncompressed, we can just manually patch the uids to be what we need. This function performs this operation, by rewriting all UIDs and GIDs to the given new_uid (which defaults to the current user's UID)..

BinaryBuilderBase.get_concrete_platformMethod
get_concrete_platform(platform::Platform, shards::Vector{CompilerShard})

Return the concrete platform for the given platform based on the GCC compiler ABI in the shards.

BinaryBuilderBase.get_concrete_platformMethod
get_concrete_platform(platform::Platform;
                      preferred_gcc_version = nothing,
                      preferred_llvm_version = nothing,
                      compilers = nothing)

Return the concrete platform for the given platform based on the GCC compiler ABI. The set of shards is chosen by the keyword arguments (see choose_shards).

BinaryBuilderBase.import_docker_imageMethod
import_docker_image(rootfs::CompilerShard; verbose::Bool = false)

Checks to see if the given rootfs has been imported into docker yet; if it hasn't, then do so so that we can run things like:

docker run -ti binarybuilder_rootfs:v2018.08.27 /bin/bash

Which, after all, is the foundation upon which this whole doodad is built.

BinaryBuilderBase.is_ecryptfsMethod
is_ecryptfs(path::AbstractString; verbose::Bool=false)

Checks to see if the given path (or any parent directory) is placed upon an ecryptfs mount. This is known not to work on current kernels, see this bug for more details: https://bugzilla.kernel.org/show_bug.cgi?id=197603

This method returns whether it is encrypted or not, and what mountpoint it used to make that decision.

BinaryBuilderBase.is_mountedMethod
is_mounted(cs::CompilerShard, build_prefix::String)

Return true if the given shard is mounted. Uses run() so will error out if something goes awry.

BinaryBuilderBase.libdirsFunction
libdirs(prefix::Prefix, platform = platform_key_abi())

Returns the library directories for the given prefix (note that this differs between unix systems and windows systems, and between 32- and 64-bit systems).

BinaryBuilderBase.locateMethod
locate(ep::ExecutableProduct, prefix::Prefix;
       platform::Platform = platform_key_abi(),
       verbose::Bool = false,
       isolate::Bool = false)

If the given executable file exists and is executable, return its path.

On all platforms, an ExecutableProduct checks for existence of the file. On non-Windows platforms, it will check for the executable bit being set. On Windows platforms, it will check that the file ends with ".exe", (adding it on automatically, if it is not already present).

BinaryBuilderBase.locateMethod
locate(fp::FileProduct, prefix::Prefix;
       platform::Platform = platform_key_abi(),
       verbose::Bool = false,
       isolate::Bool = false)

If the given file exists, return its path. The platform and isolate arguments are is ignored here, but included for uniformity. For ease of use, we support a limited number of custom variable expansions such as ${target}, and ${nbits}, so that the detection of files within target-specific folders named things like /lib32/i686-linux-musl is simpler.

BinaryBuilderBase.locateMethod
locate(lp::LibraryProduct, prefix::Prefix;
       verbose::Bool = false,
       platform::Platform = platform_key_abi())

If the given library exists (under any reasonable name) and is dlopen()able, (assuming it was built for the current platform) return its location. Note that the dlopen() test is only run if the current platform matches the given platform keyword argument, as cross-compiled libraries cannot be dlopen()ed on foreign platforms.

BinaryBuilderBase.map_targetMethod
map_target(cs::CompilerShard)

Return the location this compiler shard should be mounted at. We basically analyze the name and platform of this shard and return a path based on that.

BinaryBuilderBase.mountMethod
mount(cs::CompilerShard, build_prefix::String)

Mount a compiler shard, if possible. Uses run() so will error out if something goes awry. Note that this function only does something when using a .squashfs shard, with a UserNS or Docker runner, on Linux. All other combinations of shard archive type, runner and platform result in a no-op from this function.

BinaryBuilderBase.platform_envsMethod
platform_envs(platform::Platform)

Given a platform, generate a Dict mapping representing all the environment variables to be set within the build environment to force compiles toward the defined target architecture. Examples of things set are PATH, CC, RANLIB, as well as nonstandard things like target.

BinaryBuilderBase.preferred_cxxstring_abiMethod
preferred_cxxstring_abi(platform::Platform, shard::CompilerShard;
                        gcc_builds::Vector{GCCBuild} = available_gcc_builds)

Return the C++ string ABI preferred by the given platform or GCCBootstrap shard.

BinaryBuilderBase.preferred_libgfortran_versionMethod
preferred_libgfortran_version(platform::Platform, shard::CompilerShard;
                              gcc_builds::Vector{GCCBuild} = available_gcc_builds)

Return the libgfortran version preferred by the given platform or GCCBootstrap shard.

BinaryBuilderBase.runshellFunction
runshell(platform::Platform = platform_key_abi())

Launch an interactive shell session within the user namespace, with environment setup to target the given platform.

BinaryBuilderBase.satisfiedMethod
satisfied(p::Product;
          platform::Platform = platform_key_abi(),
          verbose::Bool = false,
          isolate::Bool = false)

Given a Product, return true if that Product is satisfied, e.g. whether a file exists that matches all criteria setup for that Product. If isolate is set to true, will isolate all checks from the main Julia process in the event that dlopen()'ing a library might cause issues.

BinaryBuilderBase.setup_dependenciesMethod
setup_dependencies(prefix::Prefix, dependencies::Vector{PackageSpec})

Given a list of JLL package specifiers, install their artifacts into the build prefix. The artifacts are installed into the global artifact store, then copied into a temporary location, then finally symlinked into the build prefix. This allows us to (a) save download bandwidth by not downloading the same artifacts over and over again, (b) maintain separation in the event of catastrophic containment failure, avoiding hosing the main system if a build script decides to try to modify the dependent artifact files, and (c) keeping a record of what files are a part of dependencies as opposed to the package being built, in the form of symlinks to a specific artifacts directory.

BinaryBuilderBase.setup_workspaceMethod
setup_workspace(build_path::String, sources::Vector{SetupSource};
                verbose::Bool = false)

Sets up a workspace within build_path, creating the directory structure needed by further steps, unpacking the source within build_path, and defining the environment variables that will be defined within the sandbox environment.

This method returns the Prefix to install things into, and the runner that can be used to launch commands within this workspace.

BinaryBuilderBase.shard_pathMethod
shard_path(cs::CompilerShard)

Return the path to this shard on-disk; for unpacked shards, this is a directory. For squashfs shards, this is a file. This will not cause a shard to be downloaded.

BinaryBuilderBase.supported_microarchitecturesMethod
supported_microarchitectures(p::Platform)

Return a vector with the list of supported microarchitectures for the given platform, an empty vector if there are any. If p is an ExtendedPlatform which already specifies a microarchitecture, returns a 1-element vector containing only that one.

BinaryBuilderBase.supported_platformsMethod
supported_platforms(;exclude::Union{Vector{<:Platform},Function}=x->false)

Return the list of supported platforms as an array of Platforms. These are the platforms we officially support building for, if you see a mapping in get_shard_hash() that isn't represented here, it's probably because that platform is still considered "in beta".

Platforms can be excluded from the list by specifying an array of platforms to exclude i.e. supported_platforms(exclude=[Windows(:i686),Windows(:x86_64)]) or a function that returns true for exclusions i.e.

islin(x) = typeof(x) == Linux
supported_platforms(exclude=islin)
BinaryBuilderBase.temp_prefixMethod
temp_prefix(func::Function)

Create a temporary prefix, passing the prefix into the user-defined function so that build/packaging operations can occur within the temporary prefix, which is then cleaned up after all operations are finished. If the path provided exists already, it will be deleted.

Usage example:

out_path = abspath("./libfoo")
temp_prefix() do p
    # <insert build steps here>

    # tarball up the built package
    tarball_path, tarball_hash = package(p, out_path)
end
BinaryBuilderBase.unameMethod
uname()

On Linux systems, return the strings returned by the uname() function in libc

BinaryBuilderBase.unmountMethod
unmount(cs::CompilerShard, build_prefix::String)

Unmount a compiler shard from a given build prefix, if possible. Uses run() so will error out if something goes awry. Note that this function only does something when using a squashfs shard on Linux. All other combinations of shard archive type and platform result in a no-op.

Pkg.PlatformEngines.packageMethod
package(prefix::Prefix, output_base::AbstractString,
        version::VersionNumber;
        platform::Platform = platform_key_abi(),
        verbose::Bool = false, force::Bool = false)

Build a tarball of the prefix, storing the tarball at output_base, appending a version number, a platform-dependent suffix and a file extension. If no platform is given, defaults to current platform. Returns the full path to, the SHA256 hash and the git tree SHA1 of the generated tarball.

BinaryBuilder.autobuildMethod
autobuild(dir::AbstractString, src_name::AbstractString,
          src_version::VersionNumber, sources::Vector,
          script::AbstractString, platforms::Vector,
          products::Vector, dependencies::Vector;
          verbose = false, debug = false,
          skip_audit = false, ignore_audit_errors = true,
          autofix = true, code_dir = nothing,
          meta_json_file = nothing, require_license = true, kwargs...)

Runs the boiler plate code to download, build, and package a source package for a list of platforms. This method takes a veritable truckload of arguments, here are the relevant actors, broken down in brief:

  • dir: the root of the build; products will be placed within dir/products, and mountpoints will be placed within dir/build/.

  • src_name: the name of the source package being built and will set the name of the built tarballs.

  • src_version: the version of the source package.

  • platforms: a list of platforms to build for.

  • sources: a vector of all sources to download and unpack before building begins, as AbstractSources.

  • script: a string representing a shell script to run as the build.

  • products: the list of Products which shall be built.

  • dependencies: a vector of JLL dependency packages as AbstractDependency that should be installed before building begins.

  • verbose: Enable verbose mode. What did you expect?

  • debug: cause a failed build to drop into an interactive shell so that the build can be inspected easily.

  • skip_audit: disable the typical audit that occurs at the end of a build.

  • ignore_audit_errors: do not kill a build even if a problem is found.

  • autofix: give BinaryBuilder permission to automatically fix issues it finds during audit passes. Highly recommended.

  • code_dir: sets where autogenerated JLL packages will be put.

  • require_license enables a special audit pass that requires licenses to be installed by all packages.

  • lazy_artifacts sets whether the artifacts should be lazy.

  • meta_json_stream: If this is set to an IOStream, do not actually build, just output a JSON representation of all the metadata about this build to the stream.

source
BinaryBuilder.build_tarballsMethod
build_tarballs(ARGS, src_name, src_version, sources, script, platforms,
               products, dependencies; kwargs...)

This should be the top-level function called from a build_tarballs.jl file. It takes in the information baked into a build_tarballs.jl file such as the sources to download, the products to build, etc... and will automatically download, build and package the tarballs, generating a build.jl file when appropriate. Note that ARGS should be the top-level Julia ARGS command- line arguments object. This function does some rudimentary parsing of the ARGS, call it with --help in the ARGS to see what it can do.

The kwargs are passed on to autobuild, see there for a list of supported ones. In addition, the keyword argument init_block may be set to a string containing Julia code; if present, this code will be inserted into the initialization path of the generated JLL package. This can for example be used to invoke an initialization API of a shared library.

Note

The init_block keyword argument is experimental and may be removed in a future version of this package. Please use it sparingly.

source
BinaryBuilder.Auditor.analyze_instruction_setMethod
analyze_instruction_set(oh::ObjectHandle, platform::Platform; verbose::Bool = false)

Analyze the instructions within the binary located at the given path for which minimum instruction set it requires, taking note of groups of instruction sets used such as avx, sse4.2, i486, etc....

Some binary files (such as libopenblas) contain multiple versions of functions, internally determining which version to call by using the cpuid instruction to determine processor support. In an effort to detect this, we make note of any usage of the cpuid instruction, disabling our minimum instruction set calculations if such an instruction is found, and notifying the user of this if verbose is set to true.

Note that this function only really makes sense for x86/x64 binaries. Don't run this on armv7l, aarch64, ppc64le etc... binaries and expect it to work.

source
BinaryBuilder.Auditor.auditFunction
audit(prefix::Prefix; platform::Platform = platform_key_abi();
                      verbose::Bool = false,
                      silent::Bool = false,
                      autofix::Bool = false,
                      require_license::Bool = true)

Audits a prefix to attempt to find deployability issues with the binary objects that have been installed within. This auditing will check for relocatability issues such as dependencies on libraries outside of the current prefix, usage of advanced instruction sets such as AVX2 that may not be usable on many platforms, linkage against newer glibc symbols, etc...

This method is still a work in progress, only some of the above list is actually implemented, be sure to actually inspect Auditor.jl to see what is and is not currently in the realm of fantasy.

source
BinaryBuilder.Auditor.check_licenseFunction
check_license(prefix, src_name; verbose::Bool = false,, silent::Bool = false)

Check that there are license files for the project called src_name in the prefix.

source
BinaryBuilder.Auditor.collect_filesFunction
collect_files(path::AbstractString, predicate::Function = f -> true)

Find all files that satisfy predicate() when the full path to that file is passed in, returning the list of file paths.

source
BinaryBuilder.Auditor.instruction_mnemonicsMethod
instruction_mnemonics(path::AbstractString, platform::Platform)

Dump a binary object with objdump, returning a list of instruction mnemonics for further analysis with analyze_instruction_set().

Note that this function only really makes sense for x86/x64 binaries. Don't run this on armv7l, aarch64, ppc64le etc... binaries and expect it to work.

This function returns the list of mnemonics as well as the counts of each, binned by the mapping defined within instruction_categories.

source
BinaryBuilder.Auditor.is_for_platformMethod
is_for_platform(h::ObjectHandle, platform::Platform)

Returns true if the given ObjectHandle refers to an object of the given platform; E.g. if the given platform is for AArch64 Linux, then h must be an ELFHandle with h.header.e_machine set to ELF.EM_AARCH64.

In particular, this method and platform_for_object() both exist because the latter is not smart enough to deal with :glibc and :musl yet.

source
BinaryBuilder.Auditor.minimum_instruction_setMethod
minimum_instruction_set(counts::Dict, is_64bit::Bool)

This function returns the minimum instruction set required, depending on whether the object file being pointed to is a 32-bit or 64-bit one:

  • For 32-bit object files, this returns one of [:pentium4, :prescott]

  • For 64-bit object files, this returns one of [:x8664, :sandybridge, :haswell, :skylakeavx512]

source
BinaryBuilder.Auditor.platform_for_objectMethod
platform_for_object(oh::ObjectHandle)

Returns the platform the given ObjectHandle should run on. E.g. if the given ObjectHandle is an x86_64 Linux ELF object, this function will return Linux(:x86_64). This function does not yet distinguish between different libc's such as :glibc and :musl.

source
BinaryBuilder.Auditor.symlink_soname_libMethod
symlink_soname_lib(path::AbstractString)

We require that all shared libraries are accessible on disk through their SONAME (if it exists). While this is almost always true in practice, it doesn't hurt to make doubly sure.

source
BinaryBuilder.Auditor.translate_symlinksMethod
translate_symlinks(root::AbstractString; verbose::Bool=false)

Walks through the root directory given within root, finding all symlinks that point to an absolute path within root, and rewriting them to be a relative symlink instead, increasing relocatability.

source
BinaryBuilder.Auditor.update_linkageMethod
update_linkage(prefix::Prefix, platform::Platform, path::AbstractString,
               old_libpath, new_libpath; verbose::Bool = false)

Given a binary object located at path within prefix, update its dynamic linkage to point to new_libpath instead of old_libpath. This is done using a tool within the cross-compilation environment such as install_name_tool on MacOS or patchelf on Linux. Windows platforms are completely skipped, as they do not encode paths or RPaths within their executables.

source
BinaryBuilder.Auditor.warn_deadlinksMethod
warn_deadlinks(root::AbstractString)

Walks through the given root directory, finding broken symlinks and warning the user about them. This is used to catch instances such as a build recipe copying a symlink that points to a dependency; by doing so, it implicitly breaks relocatability.

source
Pkg.BinaryPlatforms.detect_cxxstring_abiMethod
detect_cxxstring_abi(oh::ObjectHandle, platform::Platform)

Given an ObjectFile, examine its symbols to discover which (if any) C++11 std::string ABI it's using. We do this by scanning the list of exported symbols, triggering off of instances of St7__cxx11 or _ZNSs to give evidence toward a constraint on cxx11, cxx03 or neither.

source
Pkg.BinaryPlatforms.detect_libgfortran_versionMethod
detect_libgfortran_version(oh::ObjectHandle, platform::Platform)

Given an ObjectFile, examine its dynamic linkage to discover which (if any) libgfortran it's linked against. The major SOVERSION will determine which GCC version we're restricted to.

source
Pkg.BinaryPlatforms.detect_libstdcxx_versionMethod
detect_libstdcxx_version(oh::ObjectHandle, platform::Platform)

Given an ObjectFile, examine its dynamic linkage to discover which (if any) libgfortran it's linked against. The major SOVERSION will determine which GCC version we're restricted to.

source
BinaryBuilder.Wizard.cloneMethod
clone(url::String, source_path::String)

Clone a git repository hosted at url into source_path, with a progress bar displayed to stdout.

source
BinaryBuilder.Wizard.download_sourceMethod
download_source(state::WizardState)

Ask the user where the source code is coming from, then download and record the relevant parameters, returning the source url, the local path it is stored at after download, and a hash identifying the version of the code. In the case of a git source URL, the hash will be a git treeish identifying the exact commit used to build the code, in the case of a tarball, it is the sha256 hash of the tarball itself.

source
BinaryBuilder.Wizard.edit_scriptMethod
edit_script(state::WizardState, script::AbstractString)

For consistency (and security), use the sandbox for editing a script, launching vi within an interactive session to edit a buildscript.

source
BinaryBuilder.Wizard.interactive_buildMethod
interactive_build(state::WizardState, prefix::Prefix,
                  ur::Runner, build_path::AbstractString)

Runs the interactive shell for building, then captures bash history to save
reproducible steps for building this source. Shared between steps 3 and 5
source
BinaryBuilder.Wizard.match_filesMethod
match_files(state::WizardState, prefix::Prefix,
            platform::Platform, files::Vector; silent::Bool = false)

Inspects all binary files within a prefix, matching them with a given list of files, complaining if there are any files that are not properly matched and returning the set of normalized names that were not matched, or an empty set if all names were properly matched.

source
BinaryBuilder.Wizard.normalize_nameMethod
normalize_name(file::AbstractString)

Given a filename, normalize it, stripping out extensions. E.g. the file path "foo/libfoo.tar.gz" would get mapped to "libfoo".

source
BinaryBuilder.Wizard.pick_preferred_platformMethod

Pick the first platform for use to run on. We prefer Linux x86_64 because that's generally the host platform, so it's usually easiest. After that we go by the following preferences:

  • OS (in order): Linux, Windows, OSX
  • Architecture: x86_64, i686, aarch64, powerpc64le, armv7l
  • The first remaining after this selection
source
BinaryBuilder.Wizard.provide_hintsMethod
provide_hints(state::WizardState, path::AbstractString)

Given an unpacked source directory, provide hints on how a user might go about building the binary bounty they so richly desire.

source
BinaryBuilder.Wizard.step1Method
step1(state::WizardState)

It all starts with a single step, the unabashed ambition to leave your current stability and engage with the universe on a quest to create something new, beautiful and unforeseen. It all ends with compiler errors.

This step selects the relevant platform(s) for the built binaries.

source
BinaryBuilder.Wizard.step34Method
step34(state::WizardState)

Starts initial build for Linux x86_64, which is our initial test target platform. Sources that build properly for this platform continue on to attempt builds for more complex platforms.

source
BinaryBuilder.Wizard.step3_interactiveMethod
step3_interactive(state::WizardState, prefix::Prefix, platform::Platform,
                  ur::Runner, build_path::AbstractString)

The interactive portion of step3, moving on to either rebuild with an edited script or proceed to step 4.

source
BinaryBuilder.Wizard.step4Method
step4(state::WizardState, ur::Runner, platform::Platform,
      build_path::AbstractString, prefix::Prefix)

The fourth step selects build products after the first build is done

source
BinaryBuilder.Wizard.yggdrasil_build_tarballs_pathMethod
yggdrasil_build_tarballs_path(name::String)

Return the relative path within an Yggdrasil clone where this project (given its name) would be stored. This is useful for things like generating the build_tarballs.jl file and checking to see if it already exists, etc...

Note that we do not allow case-ambiguities within Yggdrasil, we check for this using the utility function case_insensitive_file_exists(path).

source
BinaryBuilder.Wizard.yn_promptFunction
yn_prompt(state::WizardState, question::AbstractString, default = :y)

Perform a [Y/n] or [y/N] question loop, using default to choose between the prompt styles, and looping until a proper response (e.g. "y", "yes", "n" or "no") is received.

source