An AbstractSource is something used as source to build a package.

Concrete subtypes of AbstractSource are:

• ArchiveSource: a remote archive to download from the Internet;
• FileSource: a remote file to download from the Internet;
• GitSource: a remote Git repository to clone;
• DirectorySource: a local directory to mount.
• JLLSource: A JLL to download/extract

All AbstractSource` objects must support the following operations:

• prepare(::AbstractSource)
• deploy(::AbstractSource, prefix::String)
• content_hash(::AbstractSource)::SHA1Hash
• target(::AbstractSource)::String
• retarget(::AbstractSource, new_target::String)::AbstractSource
• source(::AbstractSource)::String

Note that you must manually call prepare() before you call deploy() or content_hash() upon an AbstractSource.

We define fallthrough methods for batch-preparing and deploying abstract sources, but homogenous batches of certain sources (e.g. JLLSources) may define significantly more efficient methods for batch-prepare(). Note that batches of JLLSources in particular should have deduplicate_jlls() applied to them before prepare() is even called.

ArchiveSource(url, hash; target = "")

Specify a remote archive in one of the supported archive formats (e.g., compressed tarballs or zip balls) to be downloaded from the Internet from url. hash is a MultiHash-compatible archive integrity hash, typically a 64-character hexadecimal SHA256 hash.

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

DirectorySource(path; target = "", follow_symlinks=false)

Specify a local directory to mount from path.

The contents of the directory will be placed in ${WORKSPACE}/srcdir, unless the optional keyword argument target gives a different subdirectory to place the contents within. Symbolic links are replaced by a copy of their target when follow_symlinks is true, allowing for source directories that contain symlinks to external files, such as when sharing patchsets among a common build recipe in Yggdrasil.

GeneratedSource(generator::Function; target = "")

Call a function with a directory as its argument, allowing the function to dynamically generate the source that will be deployed within the build environment. GeneratedSource is implemented as a wrapper around DirectorySource.

GitSource(url, hash; target = basename(url))

Specify a remote Git repository to clone down from url. hash is a SHA1Hash, typically a 40-character hexadecimal string.

The repository will be cloned in ${WORKSPACE}/srcdir, with a directory name equal to the basename of the url, or in some other directory pointed to by the optional keyword argument target.

checkprepared!(me::String, x::AbstractSource)

Helper function to throw an InvalidStateException when you've tried to perform an operation upon an AbstractSource that requires you calling prepare() beforehand (such as deploy() or content_hash()).

content_hash(as::AbstractSource)

Return a SHA1Hash representing the content hash of the given source.

deduplicate_jlls(jlls::Vector{JLLSource})

When we stack multiple independent resolutions of packages together into a single prefix, we sometimes try to install dependencies more than once. This method deduplicates JLLs by attempting to constrain down to a single version bound that satisfies all duplicate JLLs. Usage:

jlls = deduplicate_jlls(jlls)

Note that prepare(jlls) will fail if you have not already called deduplicate_jlls(jlls); it checks upon every preparation.

deploy(jlls::Vector{JLLSource}, prefix::String)

Deploy the previously-downloaded JLL sources to the given prefix.

download_cache_path(fas::FileArchiveSource, download_cache::String)

Returns the full path to the file that will be written to in prepare(as)

download_cache_path(gs::GitSource, download_cache::String)

Returns the full path to the local clone that will be written to in prepare(gs)

noabspath!(target)

Helper function to throw if someone

prepare(jlls::Vector{JLLSource}; verbose=false, force=false)

Ensures that all given JLL sources are downloaded and ready to be used within the build environment. JLLs that already have artifact_paths filled out from a previous invocation of prepare() will not be re-prepared, unless force is set to true.

source(as::AbstractSource)

Return a String representation of the source as stems from. This is typically some kind of URL. Pair this with content_hash(as) for reproducible source tracking.

target(as::AbstractSource)

Returns the target that this source will unpack itself into. TODO: determine if we should remove this function.