AutoBuild.jl

export build_tarballs, autobuild, print_artifacts_toml, build, get_meta_json
import GitHub: gh_get_json, DEFAULT_API
import SHA: sha256, sha1
using TOML, Dates, UUIDs
using RegistryTools
import LibGit2
import PkgLicenses

const DEFAULT_JULIA_VERSION_SPEC = "1.0"
const DEFAULT_JLLWRAPPERS_VERSION_SPEC = "1.2.0"
const PKG_VERSIONS = Base.VERSION >= v"1.7-" ? Pkg.Versions : Pkg.Types

mutable struct BuildTimer
    begin_setup::Float64
    end_setup::Float64
    begin_build::Float64
    end_build::Float64
    begin_audit::Float64
    end_audit::Float64
    begin_package::Float64
    end_package::Float64
    BuildTimer() = new(NaN, NaN, NaN, NaN, NaN, NaN, NaN, NaN)
end

function Base.show(io::IO, t::BuildTimer)
    function rnd(a, b)
        min, sec = divrem(b - a, 60)
        out = ""
        if min ≥ 1
            out *= string(Int(min), "m ")
        end
        out *= string(round(sec; digits=2), "s")
        return out
    end
    # Sanity check: make sure all fields are non-NaN: if that's not the case, just skip.
    if all(.!(isnan.(getfield.((t,), fieldnames(BuildTimer)))))
        print(io, "Timings: ",
              "setup: ", rnd(t.begin_setup, t.end_setup), ", ",
              "build: ", rnd(t.begin_build, t.end_build), ", ",
              "audit: ", rnd(t.begin_audit, t.end_audit), ", ",
              "packaging: ", rnd(t.begin_package, t.end_package),
              )
    end
end

exclude_logs(_, f) = f != "logs"
only_logs(_, f)    = f == "logs"

# Helper function to get the minimum version supported by the given compat
# specification, given as a string.
minimum_compat(compat::String) =
    minimum(VersionNumber(rng.lower.t) for rng in PKG_VERSIONS.semver_spec(compat).ranges)

const BUILD_HELP = (
    """
    Usage: build_tarballs.jl [target1,target2,...] [--help]
                             [--verbose] [--debug]
                             [--deploy] [--deploy-bin] [--deploy-jll]
                             [--register] [--meta-json]

    Options:
        targets             By default `build_tarballs.jl` will build a tarball
                            for every target within the `platforms` variable.
                            To override this, pass in a list of comma-separated
                            target triplets for each target to be built.  Note
                            that this can be used to build for platforms that
                            are not listed in the 'default list' of platforms
                            in the build_tarballs.jl script.

        --verbose           This streams compiler output to stdout during the
                            build which can be very helpful for finding bugs.
                            Note that it is colorized if you pass the
                            --color=yes option to julia, see examples below.

        --debug=<mode>      This causes a failed build to drop into an
                            interactive shell for debugging purposes.  `<mode>`
                            can be one of `error`, `begin` or `end`.  `error`
                            drops you into the interactive shell only when there
                            is an error during the build, this is the default
                            when no mode is specified.  `begin` forces an error
                            at the beginning of the build, before any command in
                            the script is run.  `end` forces an error at the end
                            of the build script, useful to debug a successful
                            build for which the auditor would fail.

        --deploy=<repo>     Deploy binaries and JLL wrapper code to a github
                            release of an autogenerated repository.  Uses
                            `github.com/JuliaBinaryWrappers/<name>_jll.jl` by
                            default, unless `<repo>` is set, in which case it
                            should be set as `<owner>/<name>_jll.jl`.  Setting
                            this option is equivalent to setting `--deploy-bin`
                            and `--deploy-jll`.  If `<repo>` is set to "local"
                            then nothing will be uploaded, but JLL packages
                            will still be written out to `~/.julia/dev/`.

        --deploy-bin=<repo> Deploy just the built binaries

        --deploy-jll=<repo> Deploy just the JLL code wrappers

        --register=<depot>  Register into the given depot.  If no path is
                            given, defaults to `~/.julia`.  Registration
                            requires deployment of the JLL wrapper code, so
                            so using `--register` without `--deploy` or the
                            more specific `--deploy-jll` is an error.

        --meta-json         Output a JSON representation of the given build
                            instead of actually building.  Note that this can
                            (and often does) output multiple JSON objects for
                            multiple platforms, multi-stage builds, etc...

        --skip-audit        Skips auditing of the output products.

        --help              Print out this message.

    Examples:
        julia --color=yes build_tarballs.jl --verbose
            This builds all tarballs, with colorized output.

        julia build_tarballs.jl x86_64-linux-gnu,i686-linux-gnu
            This builds two tarballs for the two platforms given, with a
            minimum of output messages.

    Supported Platforms:
        $(join(sort(triplet.(supported_platforms())), "\n    "))
    """
)

"""
    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.

Generally, `ARGS` should be the top-level Julia `ARGS` command-line arguments
object.  `build_tarballs` does some rudimentary parsing of the arguments. To
see what it can do, you can call it with `--help` in the `ARGS` or see the
[Command Line](@ref) section in the manual.

The `kwargs` are passed on to [`autobuild`](@ref), see there for a list of
supported ones. A few additional keyword arguments are accept:

* `julia_compat` can be set to a version string which is used to set the
  supported Julia version in the `[compat]` section of the `Project.toml` of
  the generated JLL package. The default value is `"1.0"`.

* `lazy_artifacts` sets whether the artifacts should be lazy.

* `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.

* `augment_platform_block` may be set to a string containing Julia code; if
  present, this code will be inserted into the top-level of the
  generated JLL package. It must define a function `augment_platform!` that
  takes as a single argument, the target platform and returns the target
  platform, with amended tags. This augmented platform will then be used by the
  JLL wrapper to select the artifact. Note that this option requires the Julia
  compatibility `julia_compat` to be 1.6 or higher.

!!! note

    The `init_block` and `augment_platform_block` keyword arguments are experimental
    and may be removed in a future version of this package. Please use them sparingly.

"""
function build_tarballs(ARGS, src_name, src_version, sources, script,
                        platforms, products, dependencies;
                        julia_compat::String = DEFAULT_JULIA_VERSION_SPEC,
                        kwargs...)
    @nospecialize
    # See if someone has passed in `--help`, and if so, give them the
    # assistance they so clearly long for
    if "--help" in ARGS
        println(BUILD_HELP)
        return nothing
    end

    if !Base.isidentifier(src_name)
        error("Package name \"$(src_name)\" is not a valid identifier")
    end

    # Throw an error if we're going to build for platforms not supported by Julia v1.5-.
    if any(p -> arch(p) == "armv6l" || (Sys.isapple(p) && arch(p) == "aarch64"), platforms) && minimum_compat(julia_compat) < v"1.6"
        error("Experimental platforms cannot be used with Julia v1.5-.\nChange `julia_compat` to require at least Julia v1.6")
    end

    # XXX: These are needed as long as we support old-style sources and
    # dependencies.  Raise a warning for now, deprecate in BB 0.3+
    sources = coerce_source.(sources)
    dependencies = coerce_dependency.(dependencies)

    # Reject user supplied dependencies using a VersionSpec: these should
    # either use compat, or build_version, or both (depending on what they are
    # trying to achieve). We cannot check for this in the Dependency
    # constructor, as there are several valid situations in which we *do* want
    # to store versions here (e.g. after running the dependency through the
    # package resolver).
    for dep in dependencies
        if dep isa Dependency && dep.pkg.version != Pkg.Types.VersionSpec("*")
            error("Dependency $(dep.pkg.name) specifies a version, use build_version and/or compat instead")
        end
    end

    # Do not clobber caller's ARGS
    ARGS = deepcopy(ARGS)

    # This sets whether we should build verbosely or not
    verbose = check_flag!(ARGS, "--verbose")

    # This sets whether auditing should be skipped
    skip_audit = check_flag!(ARGS, "--skip-audit")

    # This sets whether we drop into a debug shell on failure or not
    debug, debug_mode = extract_flag!(ARGS, "--debug", "error")

    # Are we skipping building and just outputting JSON?
    meta_json, meta_json_file = extract_flag!(ARGS, "--meta-json")

    # This sets whether we are going to deploy our binaries/wrapper code to GitHub releases
    deploy, deploy_repo = extract_flag!(ARGS, "--deploy", "JuliaBinaryWrappers/$(src_name)_jll.jl")
    deploy_bin, deploy_bin_repo = extract_flag!(ARGS, "--deploy-bin", "JuliaBinaryWrappers/$(src_name)_jll.jl")
    deploy_jll, deploy_jll_repo = extract_flag!(ARGS, "--deploy-jll", "JuliaBinaryWrappers/$(src_name)_jll.jl")

    # Resolve deploy settings
    if deploy
        deploy_bin = true
        deploy_jll = true
        deploy_bin_repo = deploy_repo
        deploy_jll_repo = deploy_repo
    elseif deploy_bin # make sure bin repo and jll repo match
        deploy_jll_repo = deploy_bin_repo
    elseif deploy_jll
        deploy_bin_repo = deploy_jll_repo
    elseif deploy_bin && deploy_jll
        if deploy_bin_repo != deploy_jll_repo
            error("Binaries and JLLs must be deployed to the same repositories")
        end
    end

    # This sets whether we are going to register, and if so, which
    register, register_path = extract_flag!(ARGS, "--register", Pkg.depots1())
    if register && !deploy_jll
        error("Cannot register without deploying!")
    end
    if register && deploy_jll_repo == "local"
        error("Cannot register with a local deployment!")
    end

    if deploy_bin || deploy_jll
        code_dir = joinpath(Pkg.devdir(), "$(src_name)_jll")

        # Shove them into `kwargs` so that we are conditionally passing them along
        kwargs = (; kwargs..., code_dir = code_dir)
    end

    # If --meta-json was passed, error out if any confusing options were passed
    meta_json_stream = nothing
    if meta_json
        if deploy || deploy_bin || deploy_jll
            error("Cannot specify --deploy* with --meta-json!")
        end
        if register
            error("Cannot specify --register with --meta-json!")
        end
        if debug
            error("Cannot specify --debug with --meta-json!")
        end

        # Otherwise, check to see if we're spitting it out to stdout or a file:
        if meta_json_file === nothing
            meta_json_stream = stdout
        else
            meta_json_stream = open(meta_json_file, "a")
        end
    end

    # If the user passed in a platform (or a few, comma-separated) on the
    # command-line, use that instead of our default platforms
    if length(ARGS) > 0
        platforms = BinaryBuilderBase.parse_platform.(split(ARGS[1], ","))
    end

    # Check to make sure we have the necessary environment stuff
    if deploy_bin || deploy_jll
        # Check to see if we've already got a wrapper package within the Registry,
        # choose a version number that is greater than anything else existent.
        build_version = get_next_wrapper_version(src_name, src_version)
        if deploy_jll_repo != "local"
            @info("Building and deploying version $(build_version) to $(deploy_jll_repo)")
            # We need to make sure that the JLL repo at least exists, so that we can deploy binaries to it
            # even if we're not planning to register things to it today.
            init_jll_package(code_dir, deploy_jll_repo)
        else
            @info("Building and deploying version $(build_version) to $(code_dir)")
            # XXX: should we intialize the git repository here?  The problem is that if we
            # don't clone for the remote we end up with a diverging history.
        end
        tag = "$(src_name)-v$(build_version)"
    end

    # Modify script for debugging
    if debug
        if debug_mode == "begin"
            script = "false\n" * script
        elseif debug_mode == "end"
            script = script * "\nfalse"
        end
    end

    args = (
        # Source information
        src_name,
        src_version,
        sources,

        # Build script
        script,

        # Platforms to build for
        platforms,

        # Products we're expecting
        products,

        # Dependencies that must be downloaded
        dependencies,
    )
    extra_kwargs = extract_kwargs(kwargs, (:lazy_artifacts, :init_block, :augment_platform_block))

    if meta_json_stream !== nothing
        # If they've asked for the JSON metadata, by all means, give it to them!
        dict = get_meta_json(args...; extra_kwargs..., julia_compat=julia_compat)
        println(meta_json_stream, JSON.json(dict))

        if meta_json_stream !== stdout
            close(meta_json_stream)
        end

        build_output_meta = Dict()
    else
        # Build the given platforms using the given sources
        build_output_meta = autobuild(
            # Controls output product placement, mount directory placement, etc...
            pwd(),

            args...;

            # Flags
            verbose,
            debug,
            skip_audit,
            kwargs...,
        )
    end

    if deploy_jll
        if verbose
            @info("Committing and pushing $(src_name)_jll.jl wrapper code version $(build_version)...")
        end

        # For deploy discard build-only dependencies
        # and make sure we get a `Vector{Dependency}`
        dependencies = Dependency[dep for dep in dependencies if is_runtime_dependency(dep)]

        # The location the binaries will be available from
        bin_path = "https://github.com/$(deploy_jll_repo)/releases/download/$(tag)"
        build_jll_package(src_name, build_version, sources, code_dir, build_output_meta,
                          dependencies, bin_path; verbose, julia_compat, extra_kwargs...)
        if deploy_jll_repo != "local"
            push_jll_package(src_name, build_version; code_dir=code_dir, deploy_repo=deploy_jll_repo)
        end
        if register
            if verbose
                @info("Registering new wrapper code version $(build_version)...")
            end

            register_jll(src_name, build_version, dependencies, julia_compat;
                         deploy_repo=deploy_jll_repo, code_dir=code_dir, extra_kwargs...)
        end
    end

    if deploy_bin && deploy_bin_repo != "local"
        # Upload the binaries
        if verbose
            @info("Deploying binaries to release $(tag) on $(deploy_bin_repo) via `ghr`...")
        end
        upload_to_github_releases(deploy_bin_repo, tag, joinpath(pwd(), "products"); verbose=verbose)
    end

    return build_output_meta
end

function check_flag!(ARGS, flag)
    flag_present = flag in ARGS
    filter!(x -> x != flag, ARGS)
    return flag_present
end

function extract_flag!(ARGS, flag, val = nothing)
    for f in ARGS
        if f == flag || startswith(f, string(flag, "="))
            # Check if it's just `--flag` or if it's `--flag=foo`
            if f != flag
                val = split(f, '=')[2]
            end

            # Drop this value from our ARGS
            filter!(x -> x != f, ARGS)
            return (true, val)
        end
    end
    return (false, val)
end

"""
    get_compilers_versions(; compilers = [:c])

Return the script string that is used to print the versions of the given `compilers`.
"""
function get_compilers_versions(; compilers = [:c])
    output =
        """
        set -x
        """
    if :c in compilers
        output *=
            """
            cc --version
            c++ --version
            gcc --version
            g++ --version
            clang --version
            clang++ --version
            objc --version
            f77 --version
            gfortran --version
            ld -v
            """
    end
    if :go in compilers
        output *=
            """
            go version
            """
    end
    if :rust in compilers
        output *=
            """
            rustc --version
            rustup --version
            cargo --version
            """
    end
    return output
end

function upload_to_github_releases(repo, tag, path; gh_auth=Wizard.github_auth(;allow_anonymous=false),
                                   attempts::Int = 3, verbose::Bool = false)
    for attempt in 1:attempts
        try
            ghr() do ghr_path
                run(`$ghr_path -u $(dirname(repo)) -r $(basename(repo)) -t $(gh_auth.token) $(tag) $(path)`)
            end
            return
        catch
            if verbose
                @info("`ghr` upload step failed, beginning attempt #$(attempt)...")
            end
        end
    end
    error("Unable to upload $(path) to GitHub repo $(repo) on tag $(tag)")
end

function get_next_wrapper_version(src_name::AbstractString, src_version::VersionNumber)
    # If src_version already has a build_number, just return it immediately
    if src_version.build != ()
        return src_version
    end
    ctx = Pkg.Types.Context()

    # Force-update the registry here, since we may have pushed a new version recently
    update_registry(devnull)

    jll_name = "$(src_name)_jll"
    uuid = jll_uuid(jll_name)

    # If it does, we need to bump the build number up to the next value
    build_number = UInt64(0)
    if uuid in Pkg.Types.registered_uuids(ctx.registries, jll_name)
        # Collect all version numbers of the package across all registries.
        versions = VersionNumber[]
        for reg in ctx.registries
            if !haskey(reg, uuid)
                continue
            end

            pkg_info = Pkg.Registry.registry_info(reg[uuid])
            append!(versions, sort!(collect(keys(pkg_info.version_info))))
        end
        unique!(sort!(versions))

        # Find largest version number that matches ours
        filter!(v -> (v.major == src_version.major) &&
            (v.minor == src_version.minor) &&
            (v.patch == src_version.patch) &&
            (v.build isa Tuple{<:UInt}), versions)
        # Our build number must be larger than the maximum already present in the registry
        if !isempty(versions)
            build_number = first(maximum(versions).build) + 1
        end
    end

    # Construct build_version (src_version + build_number)
    build_version = VersionNumber(src_version.major, src_version.minor,
                         src_version.patch, src_version.prerelease, (build_number,))
end

function _registered_packages(registry_url::AbstractString)
    tmp_dir = mktempdir()
    atexit(() -> rm(tmp_dir; force = true, recursive = true))
    registry_dir = joinpath(tmp_dir, "REGISTRY")
    LibGit2.clone(registry_url, registry_dir)
    registry = TOML.parsefile(joinpath(registry_dir, "Registry.toml"))
    packages = Vector{String}(undef, 0)
    for p in registry["packages"]
        push!(packages, p[2]["name"])
    end
    rm(tmp_dir; force = true, recursive = true)
    return packages
end

function _package_is_registered(registry_url::AbstractString,
                                package::AbstractString)
    registered_packages = _registered_packages(registry_url)
    return package in registered_packages
end

is_yggdrasil() = get(ENV, "YGGDRASIL", "false") == "true"
# Use an Azure Pipelines environment variable to get the current commit hash
yggdrasil_head() = get(ENV, "BUILD_SOURCEVERSION", "")

function register_jll(name, build_version, dependencies, julia_compat;
                      deploy_repo="JuliaBinaryWrappers/$(name)_jll.jl",
                      code_dir=joinpath(Pkg.devdir(), "$(name)_jll"),
                      gh_auth=Wizard.github_auth(;allow_anonymous=false),
                      gh_username=gh_get_json(DEFAULT_API, "/user"; auth=gh_auth)["login"],
                      augment_platform_block::String="",
                      lazy_artifacts::Bool=!isempty(augment_platform_block) && minimum_compat(julia_compat) < v"1.7",
                      kwargs...)
    if !isempty(augment_platform_block) && minimum_compat(julia_compat) < v"1.6"
        error("Augmentation blocks cannot be used with Julia v1.5-.\nChange `julia_compat` to require at least Julia v1.6")
    end

    # Calculate tree hash of wrapper code
    wrapper_tree_hash = bytes2hex(Pkg.GitTools.tree_hash(code_dir))
    wrapper_commit_hash = LibGit2.head(code_dir)

    # Use RegistryTools to push up a new `General` branch with this JLL package registered within it
    # TODO: Update our fork periodically from upstream `General`.
    cache = RegistryTools.RegistryCache(joinpath(Pkg.depots1(), "registries_binarybuilder"))
    registry_url = "https://$(gh_username):$(gh_auth.token)@github.com/JuliaRegistries/General"
    cache.registries[registry_url] = Base.UUID("23338594-aafe-5451-b93e-139f81909106")
    jllwrappers_compat = isempty(augment_platform_block) ? DEFAULT_JLLWRAPPERS_VERSION_SPEC : "1.4.0"
    project = Pkg.Types.Project(build_project_dict(name, build_version, dependencies, julia_compat; jllwrappers_compat, lazy_artifacts, augment_platform_block))
    errors = setdiff(RegistryTools.registrator_errors, [:version_less_than_all_existing])
    reg_branch = RegistryTools.register(
        "https://github.com/$(deploy_repo).git",
        project,
        wrapper_tree_hash;
        registry=registry_url,
        cache=cache,
        push=true,
        checks_triggering_error = errors,
    )
    if haskey(reg_branch.metadata, "error")
        @error(reg_branch.metadata["error"])
    else
        upstream_registry_url = "https://github.com/JuliaRegistries/General"
        name_jll = "$(name)_jll"
        if _package_is_registered(upstream_registry_url, name_jll)
            pr_title = "New version: $(name_jll) v$(build_version)"
        else
            pr_title = "New package: $(name_jll) v$(build_version)"
        end
        # Open pull request against JuliaRegistries/General
        body = """
        Autogenerated JLL package registration

        * Registering JLL package $(basename(deploy_repo))
        * Repository: https://github.com/$(deploy_repo)
        * Version: v$(build_version)
        * Commit: $(wrapper_commit_hash)
        """
        if is_yggdrasil()
            commit_hash = yggdrasil_head()
            body *= """
                    * Revision on Yggdrasil: https://github.com/JuliaPackaging/Yggdrasil/commit/$commit_hash
                    """
            commit_author_login = get_github_author_login("JuliaPackaging/Yggdrasil", commit_hash; gh_auth=gh_auth)
            if commit_author_login !== nothing
                body *= """
                        * Created by: @$commit_author_login
                        """
            end
        end
        params = Dict(
            "base" => "master",
            "head" => "$(reg_branch.branch)",
            "maintainer_can_modify" => true,
            "title" => pr_title,
            "body" => body,
        )
        Wizard.create_or_update_pull_request("JuliaRegistries/General", params; auth=gh_auth)
    end
end

function get_meta_json(
                   src_name::AbstractString,
                   src_version::VersionNumber,
                   sources::Vector{<:AbstractSource},
                   script::AbstractString,
                   platforms::Vector,
                   products::Vector{<:Product},
                   dependencies::Vector{<:AbstractDependency};
                   julia_compat::String = DEFAULT_JULIA_VERSION_SPEC,
                   init_block::String = "",
                   augment_platform_block::String = "",
                   lazy_artifacts::Bool=!isempty(augment_platform_block) && minimum_compat(julia_compat) < v"1.7",
    )

    dict = Dict(
        "name" => src_name,
        "version" => "v$(src_version)",
        "sources" => sources,
        "script" => script,
        "products" => products,
        "dependencies" => dependencies,
        "julia_compat" => julia_compat,
        "lazy_artifacts" => lazy_artifacts,
        "init_block" => init_block,
        "augment_platform_block" => augment_platform_block,
    )
    # Do not write the list of platforms when building only for `AnyPlatform`
    if platforms != [AnyPlatform()]
        dict["platforms"] = triplet.(platforms)
    end
    return dict
end

function compose_debug_prompt(workspace)
    log_files = String[]
    for (root, dirs, files) in walkdir(joinpath(workspace, "srcdir"))
        for file in files
            if endswith(file, ".log")
                push!(log_files, replace(joinpath(root, file), workspace => "\${WORKSPACE}"))
            end
        end
    end

    if length(log_files) > 0
        log_files_str = join(log_files, "\n  - ")

        debug_shell_prompt = """
        Build failed, the following log files were generated:
          - $log_files_str

        Launching debug shell:
        """
    else
        debug_shell_prompt = "Build failed, launching debug shell:"
    end

    return debug_shell_prompt
end

"""
    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,
              dont_dlopen = false, 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 [`AbstractSource`](@ref)s.

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

* `products`: the list of `Product`s which shall be built.

* `dependencies`: a vector of JLL dependency packages as
  [`AbstractDependency`](@ref) 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.

* `dont_dlopen`: don't try to `dlopen` library products. This is separate from
   specifying `dont_dlopen` on a `LibraryProduct` in that it still results in
   the generated JLL loading the library at run time, and only prevents
   BinaryBuilder from doing so during JLL generation.

"""
function autobuild(dir::AbstractString,
                   src_name::AbstractString,
                   src_version::VersionNumber,
                   sources::Vector{<:AbstractSource},
                   script::AbstractString,
                   platforms::Vector,
                   products::Vector{<:Product},
                   dependencies::Vector{<:AbstractDependency};
                   verbose::Bool = false,
                   debug::Bool = false,
                   skip_audit::Bool = false,
                   ignore_audit_errors::Bool = true,
                   autofix::Bool = true,
                   code_dir::Union{String,Nothing} = nothing,
                   require_license::Bool = true,
                   dont_dlopen::Bool = false,
                   kwargs...)
    @nospecialize

    # This is what we'll eventually return
    @info("Building for $(join(sort(triplet.(platforms)), ", "))")
    build_output_meta = Dict()

    # Resolve dependencies into PackageSpecs now, ensuring we have UUIDs for all deps
    all_resolved, dependencies = resolve_jlls(dependencies, outs=(verbose ? stdout : devnull))
    if !all_resolved
        error("Invalid dependency specifications!")
    end

    # If the user passed in a src_version with a build number, bail out
    if any(!isempty, (src_version.prerelease, src_version.build))
        error("Will not build with a `src_version` that does not have the format `major.minor.patch`!  Do not set prerelease or build numbers.")
    end

    # We must prepare our sources.  Download them, hash them, etc...
    source_files = download_source.(sources; verbose=verbose)

    # Our build products will go into ./products
    out_path = joinpath(dir, "products")
    try mkpath(out_path) catch; end

    for platform in sort(collect(platforms), by = triplet)
        timer = BuildTimer()
        timer.begin_setup = time()

        # We build in a platform-specific directory
        build_path = joinpath(dir, "build", triplet(platform))
        mkpath(build_path)

        shards = choose_shards(platform; extract_kwargs(kwargs, (:preferred_gcc_version,:preferred_llvm_version,:bootstrap_list,:compilers))...)
        concrete_platform = get_concrete_platform(platform, shards)

        prefix = setup_workspace(
            build_path,
            source_files,
            concrete_platform,
            default_host_platform;
            verbose=verbose,
        )
        setup_deps(f, prefix, dependencies, platform, verbose) =
            setup_dependencies(prefix, Pkg.Types.PackageSpec[getpkg(d) for d in filter_platforms(dependencies, platform) if f(d) && is_build_dependency(d)], platform; verbose)
        host_artifact_paths = setup_deps(is_host_dependency, prefix, dependencies, default_host_platform, verbose)
        target_artifact_paths = setup_deps(is_target_dependency, prefix, dependencies, concrete_platform, verbose)

        # Create a runner to work inside this workspace with the nonce built-in
        ur = preferred_runner()(
            prefix.path;
            cwd = "/workspace/srcdir",
            platform = concrete_platform,
            verbose = verbose,
            workspaces = [
                joinpath(prefix, "metadir") => "/meta",
            ],
            compiler_wrapper_dir = joinpath(prefix, "compiler_wrappers"),
            src_name = src_name,
            shards = shards,
            extract_kwargs(kwargs, (:preferred_gcc_version,:preferred_llvm_version,:compilers,:allow_unsafe_flags,:lock_microarchitecture))...,
        )

        # Set up some bash traps
        trapper_wrapper = """
        # Stop if we hit any errors.
        set -e

        # If we're running as `bash`, then use the `DEBUG` and `ERR` traps
        if [ \$(basename \$0) = "bash" ]; then
            trap "RET=\\\$?; \\
                  trap - DEBUG INT TERM ERR EXIT; \\
                  set +e +x; \\
                  auto_install_license; \\
                  save_env; \\
                  exit \\\$RET" \\
                EXIT

            trap "RET=\\\$?; \\
                  trap - DEBUG INT TERM ERR EXIT; \\
                  set +e +x; \\
                  echo Previous command \\\$! exited with \\\$RET >&2; \\
                  save_env; \\
                  exit \\\$RET" \\
                INT TERM ERR

            # Start saving everything into our history
            trap save_history DEBUG
        else
            # If we're running in `sh` or something like that, we need a
            # slightly slimmer set of traps. :(
            trap "RET=\\\$?; \\
                  echo Previous command exited with \\\$RET >&2; \\
                  set +e +x; \\
                  save_env; \\
                  exit \\\$RET" \\
                EXIT INT TERM
        fi

        $(script)
        """

        dest_prefix = Prefix(BinaryBuilderBase.destdir(prefix.path, concrete_platform))
        did_succeed = with_logfile(dest_prefix, "$(src_name).log"; subdir=src_name) do io
            # Let's start the presentations with BinaryBuilder.jl
            write(io, "BinaryBuilder.jl version: $(get_bb_version())\n\n")
            # Get the list of compilers...
            compilers = extract_kwargs(kwargs, (:compilers,))
            # ...because we want to log all their versions.  However, we don't
            # want this to be shown in the console, so we first run this without
            # teeing to stdout
            run(ur, `/bin/bash -l -c $(get_compilers_versions(; compilers...))`, io;
                verbose = verbose, tee_stream = devnull)
            timer.end_setup = time()
            # Run the build script
            timer.begin_build = time()
            res = run(ur, `/bin/bash -l -c $(trapper_wrapper)`, io; verbose=verbose)
            timer.end_build = time()
            res
        end
        if !did_succeed
            if debug
                # Print debug prompt and paths to any generated log files
                debug_shell_prompt = compose_debug_prompt(prefix.path)
                @warn(debug_shell_prompt)
                run_interactive(ur, `/bin/bash -l -i`)
            end
            msg = "Build for $(src_name) on $(triplet(platform)) did not complete successfully\n"
            error(msg)
        end

        # Run an audit of the prefix to ensure it is properly relocatable
        timer.begin_audit = time()
        if !skip_audit
            audit_result = audit(dest_prefix, src_name;
                                 platform=platform, verbose=verbose,
                                 has_csl = any(getname.(dependencies) .== "CompilerSupportLibraries_jll"),
                                 autofix=autofix, require_license=require_license)
            if !audit_result && !ignore_audit_errors
                msg = replace("""
                Audit failed for $(dest_prefix.path).
                Address the errors above to ensure relocatability.
                To override this check, set `ignore_audit_errors = true`.
                """, '\n' => ' ')
                error(strip(msg))
            end
        end
        timer.end_audit = time()

        # Finally, error out if something isn't satisfied
        unsatisfied_so_die = false
        for p in products
            if platform isa AnyPlatform && !(p isa FileProduct)
                # `AnyPlatform` is by design platform-independent, so we allow
                # only `FileProduct`s.
                error("Cannot have $(typeof(p)) for AnyPlatform")
            end
            if !satisfied(p, dest_prefix; verbose=verbose, platform=platform,
                          skip_dlopen=dont_dlopen)
                if !verbose
                    # If we never got a chance to see the verbose output, give it here:
                    locate(p, dest_prefix; verbose=true, platform=platform,
                           skip_dlopen=dont_dlopen)
                end
                @error("Built $(src_name) but $(variable_name(p)) still unsatisfied:")
                unsatisfied_so_die = true
            end
        end
        if unsatisfied_so_die
            error("Cannot continue with unsatisfied build products!")
        end

        # We also need to capture some info about each product
        products_info = Dict{Product,Any}()
        for p in products
            product_path = locate(p, dest_prefix; platform=platform, skip_dlopen=dont_dlopen)
            products_info[p] = Dict("path" => relpath(product_path, dest_prefix.path))
            if p isa LibraryProduct || p isa FrameworkProduct
                products_info[p]["soname"] = something(
                    Auditor.get_soname(product_path),
                    basename(product_path),
                )
            end
        end

        # Unsymlink all the deps from the dest_prefix
        cleanup_dependencies(prefix, host_artifact_paths, default_host_platform)
        cleanup_dependencies(prefix, target_artifact_paths, concrete_platform)

        # Search for dead links in dest_prefix; raise warnings about them.
        Auditor.warn_deadlinks(dest_prefix.path)

        # Cull empty directories, for neatness' sake, unless auditing is disabled
        if !skip_audit
            for (root, dirs, files) = walkdir(dest_prefix.path; topdown=false)
                # We do readdir() here because `walkdir()` does not do a true in-order traversal
                if isempty(readdir(root))
                    rm(root)
                end
            end
        end

        # Compress log files
        compress_dir(logdir(dest_prefix; subdir=src_name); verbose)

        # Once we're built up, go ahead and package this dest_prefix out
        timer.begin_package = time()
        tarball_path, tarball_hash, git_hash = package(
            dest_prefix,
            joinpath(out_path, src_name),
            src_version;
            platform=platform,
            verbose=verbose,
            force=true,
            # Do not include logs into the main tarball
            filter=exclude_logs,
        )
        # Create another tarball only for the logs
        package(
            dest_prefix,
            joinpath(out_path, src_name * "-logs"),
            src_version;
            platform=platform,
            verbose=verbose,
            force=true,
            filter=only_logs,
        )
        timer.end_package = time()

        build_output_meta[platform] = (
            tarball_path,
            tarball_hash,
            git_hash,
            products_info,
        )

        # Destroy the workspace, taking care to make sure that we don't run into any
        # permissions errors while we do so.
        Base.Filesystem.prepare_for_deletion(prefix.path)
        rm(prefix.path; recursive=true)

        # If the whole build_path is empty, then remove it too.  If it's not, it's probably
        # because some other build is doing something simultaneously with this target, and we
        # don't want to mess with their stuff.
        if isempty(readdir(build_path))
            rm(build_path; recursive=true)
        end
        verbose && @info timer
    end

    # Return our product hashes
    return build_output_meta
end

function download_github_release(download_dir, repo, tag; gh_auth=Wizard.github_auth(), verbose::Bool=false)
    release = gh_get_json(DEFAULT_API, "/repos/$(repo)/releases/tags/$(tag)", auth=gh_auth)
    assets = [a for a in release["assets"] if endswith(a["name"], ".tar.gz")]

    for asset in assets
        if verbose
            @info("Downloading $(asset["name"])")
        end
        download(asset["browser_download_url"], joinpath(download_dir, asset["name"]))
    end
    return assets
end

function get_github_author_login(repository, commit_hash; gh_auth=Wizard.github_auth())
    try
        commit = GitHub.commit(repository, commit_hash; auth=gh_auth)
        commit.author.login
    catch
        nothing
    end
end

# Init remote repository, and its local counterpart
function init_jll_package(code_dir, deploy_repo;
                          gh_auth = Wizard.github_auth(;allow_anonymous=false),
                          gh_username = gh_get_json(DEFAULT_API, "/user"; auth=gh_auth)["login"])
    url = "https://github.com/$(deploy_repo)"
    try
        # This throws if it does not exist
        GitHub.repo(deploy_repo; auth=gh_auth)
    catch e
        # If it doesn't exist, create it.
        # check whether gh_org might be a user, not an organization.
        gh_org = dirname(deploy_repo)
        isorg = GitHub.owner(gh_org; auth=gh_auth).typ == "Organization"
        owner = GitHub.Owner(gh_org, isorg)
        @info("Creating new wrapper code repo at $(url)")
        try
            GitHub.create_repo(owner, basename(deploy_repo), Dict("license_template" => "mit", "has_issues" => "false"); auth=gh_auth)
        catch create_e
            # If creation failed, it could be because the repo was created in the meantime.
            # Check for that; if it still doesn't exist, then freak out.  Otherwise, continue on.
            try
                GitHub.repo(deploy_repo; auth=gh_auth)
            catch
                rethrow(create_e)
            end
        end
    end

    if !isdir(code_dir)
        # If it does exist, clone it down:
        @info("Cloning wrapper code repo from $(url) into $(code_dir)")
        Wizard.with_gitcreds(gh_username, gh_auth.token) do creds
            LibGit2.clone(url, code_dir; credentials=creds)
        end
    else
        # Otherwise, hard-reset to latest main:
        repo = LibGit2.GitRepo(code_dir)
        Wizard.with_gitcreds(gh_username, gh_auth.token) do creds
            LibGit2.fetch(repo; credentials=creds)
        end
        main_branch = LibGit2.lookup_branch(repo, "origin/main", true)
        # Starting from 2020-10-01 GitHub uses `main` as the default name of the
        # main branch of a repository, but it used to use `master`
        if isnothing(main_branch)
            main_branch = LibGit2.lookup_branch(repo, "origin/master", true)
            remote_branch = "master"
        else
            remote_branch = "main"
        end
        origin_main_oid = LibGit2.GitHash(main_branch)
        LibGit2.reset!(repo, origin_main_oid, LibGit2.Consts.RESET_HARD)
        if string(LibGit2.head_oid(repo)) != string(origin_main_oid) || remote_branch == "master"
            LibGit2.branch!(repo, "main", string(origin_main_oid); force=true)
        end
    end
end

# rebuild_jll_package is not called from anywhere in BinaryBuilder,
# but rather from JuliaPackaging/Yggdrasil/.ci/register_package.jl
function rebuild_jll_package(obj::Dict;
                             download_dir = nothing,
                             upload_prefix = nothing,
                             build_version = nothing,
                             gh_org::String = "JuliaBinaryWrappers",
                             verbose::Bool = false,
                             from_scratch::Bool = true)
    if build_version === nothing
        build_version = BinaryBuilder.get_next_wrapper_version(obj["name"], obj["version"])
    end
    if download_dir === nothing
        download_dir = mktempdir()
        repo = "$(gh_org)/$(obj["name"])_jll.jl"
        tag = "$(obj["name"])-v$(build_version)"
        download_github_release(download_dir, repo, tag; verbose=verbose)
        upload_prefix = "https://github.com/$(repo)/releases/download/$(tag)"
    elseif upload_prefix === nothing
        error("If download_dir is specified, you must specify upload_prefix as well!")
    end

    julia_compat = get(obj, "julia_compat", DEFAULT_JULIA_VERSION_SPEC)
    augment_platform_block = get(obj, "augment_platform_block", "")
    lazy_artifacts = get(obj, "lazy_artifacts", !isempty(augment_platform_block) && minimum_compat(julia_compat) < v"1.7")
    return rebuild_jll_package(
        obj["name"],
        build_version,
        obj["sources"],
        obj["platforms"],
        obj["products"],
        obj["dependencies"],
        download_dir,
        upload_prefix;
        verbose,
        lazy_artifacts,
        julia_compat,
        init_block = get(obj, "init_block", ""),
        augment_platform_block,
        from_scratch,
    )
end

function rebuild_jll_package(name::String, build_version::VersionNumber, sources::Vector,
                             platforms::Vector, products::Vector, dependencies::Vector,
                             download_dir::String, upload_prefix::String;
                             code_dir::String = joinpath(Pkg.devdir(), "$(name)_jll"),
                             verbose::Bool = false, from_scratch::Bool = true,
                             kwargs...)
    # We're going to recreate "build_output_meta"
    build_output_meta = Dict()

    # For each platform, we have two tarballs: the main with the full product,
    # and the logs-only one.  This function filters out the logs one.
    filter_main_tarball(f, platform) = occursin(".$(triplet(platform)).tar", f) && !occursin("-logs.", f)

    # Then generate a JLL package for each platform
    downloaded_files = readdir(download_dir)
    for platform in sort(collect(platforms), by = triplet)
        # Find the corresponding tarball:
        tarball_idx = findfirst(f -> filter_main_tarball(f, platform), downloaded_files)

        # No tarball matching the given platform...
        if tarball_idx === nothing
            # ..but wait, maybe the tarball still uses the os version number for
            # FreeBSD or macOS?
            for (isos, try_os_version) in ((Sys.isfreebsd, "11.1"), (Sys.isapple, "14"))
                if isos(platform) && os_version(platform) === nothing
                    tmp_platform = deepcopy(platform)
                    tmp_platform["os_version"] = try_os_version
                    tarball_idx = findfirst(f -> filter_main_tarball(f, tmp_platform), downloaded_files)
                end
            end
        end

        # Ok, really no tarball matching the given platform
        if tarball_idx === nothing
            error("Incomplete JLL release!  Could not find tarball for $(triplet(platform))")
        end
        tarball_path = joinpath(download_dir, downloaded_files[tarball_idx])

        # Begin reconstructing all the information we need
        tarball_hash = open(tarball_path, "r") do io
            bytes2hex(sha256(io))
        end

        # Unpack the tarball into a new location, calculate the git hash and locate() each product;
        mktempdir() do dest_prefix
            unpack(tarball_path, dest_prefix)

            git_hash = Base.SHA1(Pkg.GitTools.tree_hash(dest_prefix))
            if verbose
                @info("Calculated git tree hash $(bytes2hex(git_hash.bytes)) for $(basename(tarball_path))")
            end

            # Determine locations of each product
            products_info = Dict{Product,Any}()
            for p in products
                product_path = locate(p, Prefix(dest_prefix); platform=platform, verbose=verbose, skip_dlopen=true)
                if product_path === nothing
                    error("Unable to locate $(p) within $(dest_prefix) for $(triplet(platform))")
                end
                products_info[p] = Dict("path" => relpath(product_path, dest_prefix))
                if p isa LibraryProduct || p isa FrameworkProduct
                    products_info[p]["soname"] = something(
                        Auditor.get_soname(product_path),
                        basename(product_path),
                    )
                end
            end

            # Store all this information within build_output_meta:
            build_output_meta[platform] = (
                joinpath(upload_prefix, downloaded_files[tarball_idx]),
                tarball_hash,
                git_hash,
                products_info,
            )

            # Override read-only permissions before cleaning-up the directory
            Base.Filesystem.prepare_for_deletion(dest_prefix)
        end
    end

    # If `from_scratch` is set (the default) we clear out any old crusty code
    # before generating our new, pristine, JLL package within it.  :)
    if from_scratch
        rm(joinpath(code_dir, "src"); recursive=true, force=true)
        rm(joinpath(code_dir, "Artifacts.toml"); force=true)
    end

    # Finally, generate the full JLL package
    build_jll_package(name, build_version, sources, code_dir, build_output_meta,
                      dependencies, upload_prefix; verbose=verbose,
                      kwargs...)
end

function build_jll_package(src_name::String,
                           build_version::VersionNumber,
                           sources::Vector,
                           code_dir::String,
                           build_output_meta::Dict,
                           dependencies::Vector,
                           bin_path::String;
                           verbose::Bool = false,
                           julia_compat::String = DEFAULT_JULIA_VERSION_SPEC,
                           init_block::String = "",
                           augment_platform_block::String = "",
                           # If we support versions older than Julia v1.7 the artifact
                           # should be lazy when we augment the platform.
                           lazy_artifacts::Bool = !isempty(augment_platform_block) && minimum_compat(julia_compat) < v"1.7",
                           )
    # Make way, for prince artifacti
    mkpath(joinpath(code_dir, "src", "wrappers"))

    # Drop BuildDependency objects
    dependencies = Dependency[d for d in dependencies if is_runtime_dependency(d)]

    platforms = keys(build_output_meta)
    products_info = Dict{Product,Any}()
    for platform in sort(collect(platforms), by = triplet)
        if verbose
            @info("Generating jll package for $(triplet(platform)) in $(code_dir)")
        end

        # Extract this platform's information.  Each of these things can be platform-specific
        # (including the set of products!) so be general here.
        tarball_name, tarball_hash, git_hash, products_info = build_output_meta[platform]

        # Add an Artifacts.toml
        artifacts_toml = joinpath(code_dir, "Artifacts.toml")
        download_info = Tuple[
            (joinpath(bin_path, basename(tarball_name)), tarball_hash),
        ]
        if platform isa AnyPlatform
            # AnyPlatform begs for a platform-independent artifact
            bind_artifact!(artifacts_toml, src_name, git_hash; download_info=download_info, force=true, lazy=lazy_artifacts)
        else
            bind_artifact!(artifacts_toml, src_name, git_hash; platform=platform, download_info=download_info, force=true, lazy=lazy_artifacts)
        end

        # Generate the platform-specific wrapper code
        open(joinpath(code_dir, "src", "wrappers", "$(triplet(platform)).jl"), "w") do io
            println(io, "# Autogenerated wrapper script for $(src_name)_jll for $(triplet(platform))")
            if !isempty(products_info)
                println(io, """
                export $(join(sort(variable_name.(first.(collect(products_info)))), ", "))
                """)
            end
            for dep in filter_platforms(dependencies, platform)
                if !is_top_level_dependency(dep)
                    println(io, "using $(getname(dep))")
                end
            end

            # Generate header definitions like `find_artifact_dir()`
            println(io, "JLLWrappers.@generate_wrapper_header($(repr(src_name)))")

            # Next, begin placing products
            function global_declaration(p::LibraryProduct, p_info::Dict)
                return "JLLWrappers.@declare_library_product($(variable_name(p)), $(repr(p_info["soname"])))"
            end
            global_declaration(p::FrameworkProduct, p_info::Dict) = global_declaration(p.libraryproduct, p_info)

            function global_declaration(p::ExecutableProduct, p_info::Dict)
                vp = variable_name(p)
                # An executable product's public interface is a do-block wrapper function
                return "JLLWrappers.@declare_executable_product($(variable_name(p)))"
            end

            function global_declaration(p::FileProduct, p_info::Dict)
                return "JLLWrappers.@declare_file_product($(variable_name(p)))"
            end

            # Create relative path mappings that are compile-time constant, and mutable
            # mappings that are initialized by __init__() at load time.
            for (p, p_info) in sort(products_info)
                println(io, global_declaration(p, p_info))
            end

            print(io, """
            function __init__()
                JLLWrappers.@generate_init_header($(join(getname.(filter_platforms(dependencies, platform)), ", ")))
            """)

            for (p, p_info) in sort(products_info)
                vp = variable_name(p)

                if Sys.iswindows(platform)
                    # `dlopen` on Windows isn't occasionally happy to see
                    # forward slashes in the path:
                    # https://github.com/JuliaPackaging/BinaryBuilder.jl/issues/941.
                    # Workaround the issue by normalising the path separator to
                    # the backslash.
                    p_info["path"] = replace(p_info["path"], "/" => "\\")
                end

                if p isa LibraryProduct || p isa FrameworkProduct
                    println(io, """
                        JLLWrappers.@init_library_product(
                            $(vp),
                            $(repr(p_info["path"])),
                            $(BinaryBuilderBase.dlopen_flags_str(p)),
                        )
                    """)
                elseif p isa ExecutableProduct
                    println(io, """
                        JLLWrappers.@init_executable_product(
                            $(vp),
                            $(repr(p_info["path"])),
                        )
                    """)
                elseif p isa FileProduct
                    println(io, """
                        JLLWrappers.@init_file_product(
                            $(vp),
                            $(repr(p_info["path"])),
                        )
                    """)
                end
            end
            println(io, "    JLLWrappers.@generate_init_footer()")


            if !isempty(init_block)
                print(io, """
                    $(init_block)
                """)
            end

            print(io, """
            end  # __init__()
            """)
        end
    end

    if !isempty(augment_platform_block)
        pkg_dir = joinpath(code_dir, ".pkg")
        !ispath(pkg_dir) && mkdir(pkg_dir)
        write(joinpath(pkg_dir, "platform_augmentation.jl"), augment_platform_block)

        write(joinpath(pkg_dir, "select_artifacts.jl"),
              """
              push!(Base.LOAD_PATH, dirname(@__DIR__))

              using TOML, Artifacts, Base.BinaryPlatforms
              include("./platform_augmentation.jl")
              artifacts_toml = joinpath(dirname(@__DIR__), "Artifacts.toml")

              # Get "target triplet" from ARGS, if given (defaulting to the host triplet otherwise)
              target_triplet = get(ARGS, 1, Base.BinaryPlatforms.host_triplet())

              # Augment this platform object with any special tags we require
              platform = augment_platform!(HostPlatform(parse(Platform, target_triplet)))

              # Select all downloadable artifacts that match that platform
              artifacts = select_downloadable_artifacts(artifacts_toml; platform, include_lazy=true)

              #Output the result to `stdout` as a TOML dictionary
              TOML.print(stdout, artifacts)
              """)
    end

    # Generate target-demuxing main source file.
    open(joinpath(code_dir, "src", "$(src_name)_jll.jl"), "w") do io
        print(io, """
        # Use baremodule to shave off a few KB from the serialized `.ji` file
        baremodule $(src_name)_jll
        using Base
        using Base: UUID
        """)
        if lazy_artifacts
            println(io, "using LazyArtifacts")
        end

        for dep in dependencies
            if is_top_level_dependency(dep)
                println(io, "using $(getname(dep))")
            end
        end

        if !isempty(augment_platform_block)
            print(io, """
            Base.include(@__MODULE__, joinpath("..", ".pkg", "platform_augmentation.jl"))
            """)
        end

        print(io, """
        import JLLWrappers

        JLLWrappers.@generate_main_file_header($(repr(src_name)))
        JLLWrappers.@generate_main_file($(repr(src_name)), $(repr(jll_uuid("$(src_name)_jll"))))
        end  # module $(src_name)_jll
        """)
    end

    print_source(io, s::ArchiveSource) = println(io, "* compressed archive: ", s.url, " (SHA256 checksum: `", s.hash,"`)")
    print_source(io, s::GitSource) =     println(io, "* git repository: ", s.url, " (revision: `", s.hash,"`)")
    print_source(io, s::FileSource) =    println(io, "* file: ", s.url, " (SHA256 checksum: `", s.hash,"`)")
    function print_source(io, s::DirectorySource)
        print(io, "* files in directory, relative to originating `build_tarballs.jl`: ")
        if is_yggdrasil()
            println(io, "[`", s.path, "`](https://github.com/JuliaPackaging/Yggdrasil/tree/", yggdrasil_head(), "/", ENV["PROJECT"], "/", basename(s.path), ")")
        else
            println(io, "`", s.path, "`")
        end
    end
    function print_jll(io, dep)
        depname = getname(dep)
        if is_yggdrasil()
            # In this case we can easily add a direct link to the repo
            println(io, "* [`", depname, "`](https://github.com/JuliaBinaryWrappers/", depname, ".jl)")
        else
            println(io, "* `", depname, "`")
        end
    end
    print_product(io, p::Product) = println(io, "* `", typeof(p), "`: `", variable_name(p), "`")
    # Add a README.md
    open(joinpath(code_dir, "README.md"), "w") do io
        println(io,
                """
                # `$(src_name)_jll.jl` (v$(build_version))
                """)
        if is_yggdrasil()
            println(io, "[![deps](https://juliahub.com/docs/$(src_name)_jll/deps.svg)](https://juliahub.com/ui/Packages/$(src_name)_jll/$(Base.package_slug(BinaryBuilder.jll_uuid("$(src_name)_jll"), 5))?page=2)\n")
        end
        println(io, """
                This is an autogenerated package constructed using [`BinaryBuilder.jl`](https://github.com/JuliaPackaging/BinaryBuilder.jl).
                """)
        if is_yggdrasil()
            println(io, """
                        The originating [`build_tarballs.jl`](https://github.com/JuliaPackaging/Yggdrasil/blob/$(yggdrasil_head())/$(ENV["PROJECT"])/build_tarballs.jl) script can be found on [`Yggdrasil`](https://github.com/JuliaPackaging/Yggdrasil/), the community build tree.

                        ## Bug Reports

                        If you have any issue, please report it to the Yggdrasil [bug tracker](https://github.com/JuliaPackaging/Yggdrasil/issues).
                        """)
        end
        println(io, """
                ## Documentation

                For more details about JLL packages and how to use them, see `BinaryBuilder.jl` [documentation](https://docs.binarybuilder.org/stable/jll/).
                """)
        if length(sources) > 0
            # `sources` can be empty, and it is for some HelloWorld examples
            println(io, """
                        ## Sources

                        The tarballs for `$(src_name)_jll.jl` have been built from these sources:""")
            println(io)
            print_source.(Ref(io), sources)
            println(io)
        end
        println(io, """
                    ## Platforms

                    `$(src_name)_jll.jl` is available for the following platforms:
                    """)
        for p in sort(collect(platforms), by = triplet)
            println(io, "* `", p, "` (`", triplet(p), "`)")
        end
        # Note: here we list _all_ runtime dependencies, including those that may be
        # required only for some platforms.
        if length(dependencies) > 0
            println(io)
            println(io, """
                        ## Dependencies

                        The following JLL packages are required by `$(src_name)_jll.jl`:""")
            println(io)
            print_jll.(Ref(io), sort(dependencies, by = getname))
        end
        if length(keys(products_info)) > 0
            println(io)
            println(io, """
                        ## Products

                        The code bindings within this package are autogenerated from the following `Products`:
                        """)
            for (p, _) in sort(products_info)
                print_product(io, p)
            end
        end
    end

    # Add before the license a note about to what files this applies
    license = if isfile(joinpath(code_dir, "LICENSE"))
        # In most cases we have a file called `LICENSE`...
        strip(read(joinpath(code_dir, "LICENSE"), String))
    else
        # ...but sometimes this is missing.
        strip("MIT License\n\nCopyright (c) $(year(now()))\n" * PkgLicenses.readlicense("MIT"))
    end
    note_lines = split("""
                       The Julia source code within this repository (all files under `src/`) are
                       released under the terms of the MIT \"Expat\" License, the text of which is
                       included below.  This license does not apply to the binary package wrapped by
                       this Julia package and automatically downloaded by the Julia package manager
                       upon installing this wrapper package.  The binary package's license is shipped
                       alongside the binary itself and can be found within the
                       `share/licenses/$(src_name)` directory within its prefix.""", "\n")
    # Since this function can be called multiple times, we must make sure that
    # the note is written only once.  Do nothing it is already there.
    if !startswith(license, first(note_lines))
        open(joinpath(code_dir, "LICENSE"), "w") do io
            println.(Ref(io), note_lines)
            println(io)
            println(io, license)
        end
    end
    # We used to have a duplicate license file, remove it.
    rm(joinpath(code_dir, "LICENSE.md"); force=true)

    # Add a Project.toml.  Note: here we list _all_ runtime dependencies, including those
    # that may be required only for some platforms.
    jllwrappers_compat = isempty(augment_platform_block) ? "1.2.0" : "1.4.0"
    project = build_project_dict(src_name, build_version, dependencies, julia_compat; lazy_artifacts, jllwrappers_compat, augment_platform_block)
    open(joinpath(code_dir, "Project.toml"), "w") do io
        TOML.print(io, project)
    end

    # Add a `.gitignore`
    open(joinpath(code_dir, ".gitignore"), "w") do io
        println(io, "override/")
    end
end

function push_jll_package(name, build_version;
                          code_dir = joinpath(Pkg.devdir(), "$(name)_jll"),
                          deploy_repo = "JuliaBinaryWrappers/$(name)_jll.jl",
                          gh_auth = Wizard.github_auth(;allow_anonymous=false),
                          gh_username = gh_get_json(DEFAULT_API, "/user"; auth=gh_auth)["login"])
    # Next, push up the wrapper code repository
    wrapper_repo = LibGit2.GitRepo(code_dir)
    LibGit2.add!(wrapper_repo, ".")
    commit = LibGit2.commit(wrapper_repo, "$(name)_jll build $(build_version)")
    Wizard.with_gitcreds(gh_username, gh_auth.token) do creds
        refspecs = ["refs/heads/main"]
        # Fetch the remote repository, to have the relevant refspecs up to date.
        LibGit2.fetch(
            wrapper_repo;
            refspecs=refspecs,
            credentials=creds,
        )
        LibGit2.branch!(wrapper_repo, "main", string(LibGit2.GitHash(commit)); track="main")
        LibGit2.push(
            wrapper_repo;
            refspecs=refspecs,
            remoteurl="https://github.com/$(deploy_repo).git",
            credentials=creds,
        )
    end
end

# For historical reasons, our UUIDs are generated with some rather strange constants
function bb_specific_uuid5(namespace::UUID, key::String)
    data = [reinterpret(UInt8, [namespace.value]); codeunits(key)]
    u = reinterpret(UInt128, sha1(data)[1:16])[1]
    u &= 0xffffffffffff0fff3fffffffffffffff
    u |= 0x00000000000050008000000000000000
    return UUID(u)
end
const uuid_package = UUID("cfb74b52-ec16-5bb7-a574-95d9e393895e")
# For even more interesting historical reasons, we append an extra
# "_jll" to the name of the new package before computing its UUID.
jll_uuid(name) = bb_specific_uuid5(uuid_package, "$(name)_jll")

function find_uuid(ctx, pkg)
    if Pkg.Types.has_uuid(pkg)
        return pkg.uuid
    end
    depname = getname(pkg)
    @static if VERSION >= v"1.7"
        uuids = Pkg.Types.registered_uuids(ctx.registries, depname)
    else
        uuids = Pkg.Types.registered_uuids(ctx, depname)
    end
    if isempty(uuids)
        return nothing
    end
    if length(uuids) == 1
        return first(uuids)
    end
    error("""
    Multiple UUIDs found for package `$(depname)`.
    Use `PackageSpec(name = \"$(depname)\", uuid = ..." to specify the UUID explicitly.
    """)
end

function build_project_dict(name, version, dependencies::Array{Dependency},
                            julia_compat::String=DEFAULT_JULIA_VERSION_SPEC;
                            jllwrappers_compat::String=DEFAULT_JLLWRAPPERS_VERSION_SPEC,
                            augment_platform_block::String="",
                            lazy_artifacts::Bool=!isempty(augment_platform_block) && minimum_compat(julia_compat) < v"1.7",
                            kwargs...)
    Pkg.Types.semver_spec(julia_compat) # verify julia_compat is valid
    project = Dict(
        "name" => "$(name)_jll",
        "uuid" => string(jll_uuid("$(name)_jll")),
        "version" => string(version),
        "deps" => Dict{String,Any}(),
        # We require at least Julia 1.3+, for Pkg.Artifacts support, but we only claim
        # Julia 1.0+ by default so that empty JLLs can be installed on older versions.
        "compat" => Dict{String,Any}("JLLWrappers" => "$(jllwrappers_compat)",
                                     "julia" => "$(julia_compat)")
    )

    ctx = Pkg.Types.Context()
    for dep in dependencies
        pkgspec = getpkg(dep)
        depname = getname(dep)
        uuid = find_uuid(ctx, pkgspec)
        if uuid === nothing
            uuid = jll_uuid(depname)
        end
        project["deps"][depname] = string(uuid)
        if dep isa Dependency && length(dep.compat) > 0
            Pkg.Types.semver_spec(dep.compat) # verify dep.compat is valid
            project["compat"][depname] = dep.compat
        end
    end
    # Always add Libdl, Pkg and Artifacts as dependencies
    # Once we stop supporting Julia 1.5-, we can drop the `Pkg` requirement.
    project["deps"]["Libdl"] = "8f399da3-3557-5675-b5ff-fb832c97cbdb"
    project["deps"]["Pkg"] = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"
    project["deps"]["Artifacts"] = "56f22d72-fd6d-98f1-02f0-08ddc0907c33"
    project["deps"]["JLLWrappers"] = "692b3bcd-3c85-4b1f-b108-f13ce0eb3210"
    if lazy_artifacts
        project["deps"]["LazyArtifacts"] = "4af54fe1-eca0-43a8-85a7-787d91b784e3"
    end
    if !isempty(augment_platform_block)
        project["deps"]["TOML"] = "fa267f1f-6049-4f14-aa54-33bafae1ed76"
    end

    return project
end