builtin.hlb

# An empty filesystem.
#
# @return a scratch filesystem.
fs scratch()

# An OCI image's filesystem.
#
# @param ref a docker registry reference. if not fully qualified, it will be 
# expanded the same as the docker CLI.
# @return a filesystem of the image.
fs image(string ref)

# Resolves the OCI Image Config and inherit its environment, working directory,
# and entrypoint.
#
# @return an option to resolve the image's OCI image config.
option::image resolve()

# A filesystem with a file retrieved from a HTTP URL.
#
# @param url a fully-qualified URL to send a HTTP GET request.
# @return a filesystem with the downloaded HTTP resource.
fs http(string url)

# Verifies the checksum of the retrieved file against a digest.
#
# @param digest a checksum in the form of an OCI digest.
# https://github.com/opencontainers/image-spec/blob/master/descriptor.md#digests
# @return an option to verify the checksum of the file.
option::http checksum(string digest)

# Modifies the permissions of the retrieved file.
#
# @param filemode the new permissions of the file.
# @return an option to chmod the file.
option::http chmod(int filemode)

# Writes the retrieved file with a specified name.
#
# @param name the name of the file.
# @return an option to provide a name for the file.
option::http filename(string name)

# A filesystem with the files from a git repository checked out from
# a git reference. Note that by default, the `.git` directory is not included.
#
# @param remote the fully qualified git remote.
# @param ref the git reference to check out.
# @return a filesystem containing files from a git repository.
fs git(string remote, string ref)

# Keeps the `.git` directory of the git repository.
#
# @return the option to keep the `.git` directory.
option::git keepGitDir()

# A filesystem with the files synced up from a directory on the
# local system.
#
# @param path the local path to the directory to sync up.
# @return a filesystem containing local files.
fs local(string path)

# Sync only files that match any of the included patterns.
#
# @param pattern a list of patterns for files that should be synced.
# @return an option to sync files that match any pattern.
option::local includePatterns(variadic string pattern)

# Sync only files that do not match any of the excluded patterns.
#
# @param pattern a list of patterns for files that should not be synced.
# @return an option to sync files that don't match any pattern.
option::local excludePatterns(variadic string pattern)

# Sync the targets of symlinks if path is to a symlink.
#
# @param path a list of paths to files that may be symlinks.
# @return an option to sync the targets of symlinks.
option::local followPaths(variadic string path)

# Generates a filesystem using an external frontend.
#
# @param frontend a filesystem with an executable that runs a BuildKit gateway
# GRPC client over stdio.
# @return a filesystem generated by the external frontend.
fs frontend(string source)

# Provide an input filesystem to the external frontend. Read the documentation
# for the frontend to see what it will accept.
#
# @param key an unique key for the input.
# @param value a filesystem as an input.
# @return an option to provide an input filesystem to the external frontend.
option::frontend input(string key, fs value)

# Provide a key value pair to the external frontend. Read the documentation
# for the frontend to see what it will accept.
#
# @param key an unique key for the option.
# @param value a value for the option.
# @return an option to provide a key value pair to the external frontend.
option::frontend opt(string key, string value)

# Sets the current shell command to use when executing subsequent `run`
# methods. By default, this is ["sh", "-c"].
#
# @param arg the list of args used to prefix `run` statements.
# @return the filesystem with a new default shell.
fs shell(variadic string arg)

# Executes an command in the current filesystem.
#
# If no arguments are given, it will execute the current args set on the
# filesystem.
# If exactly one arg is given it will be wrapped with /bin/sh -c 'arg'.
# If more than one arg is given, it will be executed directly, without a shell.
#
# @param arg are optional arguments to execute.
# @return the filesystem after the command has executed.
fs run(variadic string arg)

option::run capture()

# Sets the rootfs as read-only for the duration of the run command.
#
# @return an option to set the rootfs as read-only.
option::run readonlyRootfs()

# Sets an environment key pair for the duration of the run command.
#
# @param key the environment key.
# @param value the environment value.
# @return an option to set an environment key pair.
option::run env(string key, string value)

# Sets the working directory for the duration of the run command.
#
# @param path the new working directory.
# @return an option to set the working directory.
option::run dir(string path)

# Sets the current user for the duration of the run command.
#
# @param name the name of the user.
# @return an option to set the current user.
option::run user(string name)

# Ignore any previously cached results for the run command.
#
# @ return an option to ignore existing cache for the run command.
option::run ignoreCache()

# Sets the networking mode for the duration of the run command. By default, the
# value is `unset` (using BuildKit's CNI provider, otherwise its host
# namespace).
#
# @param networkmode the network mode of the container, must be one of the
# following:
# - unset: use the default network provider.
# - host: use the host's network namespace.
# - none: disable networking.
option::run network(string networkmode)

# Sets the security mode for the duration of the run command. By default, the
# value is `sandbox`.
#
# @param securitymode the security mode of the container, must be one of the
# following:
# - sandbox: use the default containerd seccomp profile.
# - insecure: enables all capabilities.
option::run security(string securitymode)

# Attempt to lex the single-argument shell command provided to `run`
# to determine if a `/bin/sh -c '...'` wrapper needs to be added.
#
# @return an option to attempt to optimize the command execution remoiving the /bin/sh -c "..." wrapper when possible.
option::run shlex()

# Adds a host entry to /etc/hosts for the duration of the run command.
#
# @param hostname the host name of the entry, may include spaces to delimit
# multiple host names.
# @param address the IP of the entry.
option::run host(string hostname, string address)

# Mounts a SSH socket for the duration of the run command. By default, it will
# try to use the SSH socket found from $SSH_AUTH_SOCK. Otherwise, an option
# `localPath` can be provided to specify a filepath to a SSH auth socket or
# *.pem file.
#
# @return an option to mount a SSH socket.
option::run ssh()

# Forwards traffic to/from a local source to a unix domain socket mounted for
# the duration of the run command. The source must be a fully qualified URI
# where the scheme must be either `unix://` or `tcp://`.
#
# @param src a fully qualified URI to forward traffic to/from.
# @param dest a mountpoint for a unix domain socket that is forwarded to/from.
# @return an option to forward traffic from a local source.
option::run forward(string src, string dest)

# Mounts a secure file for the duration of the run command. Secrets are
# attached via a tmpfs mount, so all the data stays in volatile memory.
#
# @param localPath the filepath for a secure file or directory.
# @param mountPoint the directory where the secret is attached.
# @return an option to mount a secret.
option::run secret(string localPath, string mountPoint)

# Attaches an additional filesystem for the duration of the run command.
#
# @param input the additional filesystem to mount. the input's root filesystem
# becomes available from the mountPoint directory.
# @param mountPoint the directory where the mount is attached.
# @param an option to mount an additional filesystem.
option::run mount(fs input, string mountPoint)

# Sets the target directory to mount the SSH agent socket. By default, it is
# mounted to `/run/buildkit/ssh_agent.${N}`, where N is the index of the 
# socket. If $SSH_AUTH_SOCK is not set, it will set SSH_AUTH_SOCK to the
# mountPoint.
#
# @param mountPoint the directory where the SSH agent socket is attached.
# @return an option to specify the SSH agent socket mount point.
option::ssh target(string mountPoint)

# Sets the paths for a single SSH agent socket or a list of PEM keys. By
# default, the SSH agent defined by $SSH_AUTH_SOCK will be forwarded into the
# container.
#
# PEM files with passphrases are not supported atm.
#
# @param paths the paths to a single SSH agent socket or a list of PEM keys.
# @return an option to provide an alternative SSH agent socket or PEM keys to
# forward.
option::ssh localPaths(variadic string path)

# Sets the user ID for the SSH agent socket. By default, the UID is 0.
#
# @param id the user ID.
# @return an option to set the user ID of the SSH agent socket.
option::ssh uid(int id)

# Sets the group ID for the SSH agent socket. By default, the GID is 0.
#
# @param id the group ID.
# @return an option to set the group ID of the SSH agent socket.
option::ssh gid(int id)

# Sets the permissions for the SSH agent socket. By default, the file mode is
# 0o600.
#
# @param filemode the new permissions of the SSH agent socket in int.
# @return an option to set the permissions of the SSH agent socket.
option::ssh mode(int filemode)

# Sets the user ID for the secure file. By default, the UID is 0.
#
# @param id the user id.
# @return an option to set the user ID of the secure file.
option::secret uid(int id)

# Sets the group ID for the secure file. By default, the GID is 0.
#
# @param id the group id.
# @return an option to set the group ID of the secure file.
option::secret gid(int id)

# Sets the permissions for the secure file. By default, the file mode is 0o600.
#
# @param filemode the new permissions of the secure file in int.
# @return an option to set the permissions of the secure file.
option::secret mode(int filemode)

# Attach secrets only for files that match any of the included patterns.
#
# @param pattern a list of patterns for files that should be attached as secrets
# @return an option to attach files that match any pattern.
option::secret includePatterns(variadic string pattern)

# Attach secrets only for files that do not match any of the excluded patterns.
#
# @param pattern a list of patterns for files that should not be attached as secrets
# @return an option to attach files that don't match any pattern.
option::secret excludePatterns(variadic string pattern)

# Sets the mount to be attached as a read-only filesystem.
#
# @return an option to attach the mount as a read-only filesystem..
option::mount readonly()

# Sets the mount to be attached as a tmpfs filesystem.
#
# @return an option to attach the mount as a tmpfs filesystem.
option::mount tmpfs()

# Mount a path from the input filesystem. By default, the root of the input
# filesystem is mounted.
#
# @param path the path in the input filesystem.
# @return an option to mount a specific path from the input filesystem.
option::mount sourcePath(string path)

# Cache a snapshot of the mount after the run command has executed. A cacheid
# must be provided to uniquely identify the cache mount.
#
# Compilers and package managers commonly have an option to specify cache
# directories. Depending on their implementation, it may be safe to share the
# cache with concurrent processes. This is adjusted via the `sharingmode`
# argument.
#
# The cache is modified every time the parent run command is executed. A cache
# could also be managed by not using the `cache` option. Instead, the mount can
# be aliased, and then pushed as an image, so that there it can be a stable
# snapshot, or updated externally.
#
# @param cacheid the unique ID to identify the cache.
# @param sharingmode the sharing mode of the cache, must be one of the
# following:
# - shared: can be used concurrently by multiple writers.
# - private: creates a new mount if there are multiple writers.
# - locked: pauses additional writers until the first one releases the mount.
# @return an option to cache a mount.
option::mount cache(string cacheid, string sharingmode)

# Sets an environment key pair for all subsequent calls in this filesystem
# block.
#
# @param key the environment key.
# @param value the environment value.
# @return a filesystem with an environment key pair set.
fs env(string key, string value)

# Sets the working directory for all subsequent calls in this filesystem block.
#
# @param path the new working directory.
# @return a filesystem with a new working directory.
fs dir(string path)

# Sets the current user for all subsequent calls in this filesystem block.
#
# @param name the name of the user.
# @return a filesystem with a new current user.
fs user(string name)

# Creates a directory in the current filesystem.
#
# @param path the path of the directory.
# @param filemode the permissions of the directory.
# @return a filesystem with a new directory.
fs mkdir(string path, int filemode)

# Create the parent directories if they don't exist already.
#
# @return an option to create parent directories.
option::mkdir createParents()

# Change the owner of the directory.
#
# @param owner the user:group owner of the directory.
# @return an option to change the owner of the directory.
option::mkdir chown(string owner)

# Sets the created time of the directory.
#
# @param created the created time in the RFC3339 format.
# @return an option to set the created time of the directory.
option::mkdir createdTime(string created)

# Creates a file in the current filesystem.
#
# @param path the path of the file.
# @param filemode the permissions of the file.
# @param content the contents of the file.
# @return a filesystem with a new file.
fs mkfile(string path, int filemode, string content)

# Change the owner of the file.
#
# @param owner the user:group owner of the file.
# @return an option to change the owner of the file.
option::mkfile chown(string owner)

# Sets the created time of the file.
#
# @param created the created time in the RFC3339 format.
# @return an option to set the created time of the file.
option::mkfile createdTime(string created)

# Removes a file from the current filesystem.
#
# @param path the path of the file to remove.
# @return a filesystem with a file removed.
fs rm(string path)

# Allows the file to not be found.
#
# @return an option to allow the file to not be found.
option::rm allowNotFound()

# Allows wildcards in the path to remove.
#
# @return an option to allow wildcards in the path to remove.
option::rm allowWildcard()

# Copies a file from an input filesystem into the current filesystem.
#
# @param input the filesystem to copy from.
# @param src the path from the input filesystem.
# @param dst the path in the current filesystem.
# @return a filesystem with a file copied from the input filesystem.
fs copy(fs input, string src, string dst)

# Follow symlinks in the input filesystem and copy the symlink targets too.
#
# @return an option to follow symlinks and copy their targets.
option::copy followSymlinks()

# If the `src` path is a directory, only the contents of the directory is
# copied to the destination.
#
# @return an option to copy only the contents of the input directory.
option::copy contentsOnly()

# If the `src` path is an archive, attempt to unpack its contents into the
# destination.
#
# @return an option to unpack an archive to the destination.
option::copy unpack()

# Create the parent directories of the destination if they don't already exist.
#
# @return an option to create the parent directories of the destination.
option::copy createDestPath()

# Allows wildcards in the path to copy.
#
# @return an option to allow wildcards in the path to copy.
option::copy allowWildcard()

# Allows wildcards to match no files in the path to copy.
#
# @return an option to allow wildcards to ignore empty wildcard match in the path to copy.
option::copy allowEmptyWildcard()

# Change the owner of the copy path.
#
# @param owner the user:group owner of the copy path.
# @return an option to change the owner of the copy path.
option::copy chown(string owner)

# Modifies the permissions of the copied files.
#
# @param filemode the new permissions of the file.
# @return an option to chmod the file.
option::copy chmod(int filemode)

# Sets the created time of the copy path.
#
# @param created the created time in the RFC3339 format.
# @return an option to set the created time of the copy path.
option::copy createdTime(string created)

# Pushes the filesystem to a registry following the distribution
# spec: https://github.com/opencontainers/distribution-spec/
#
# @param ref a distribution reference. if not fully qualified, it will be
# expanded the same as the docker CLI.
# @return an option to push the filesystem to a registry.
fs dockerPush(string ref)

# Loads the filesystem as a Docker image to the docker client found in your
# environment.
#
# @param ref the name of the Docker image.
# @return an option to load a filesystem to the docker client found in your
# environment.
fs dockerLoad(string ref)

# Downloads the filesystem to a local path.
#
# @param localPath the destination filepath for the filesystem contents.
# @return an option to download a filesystem to the local system.
fs download(string localPath)

# Downloads the filesystem as a tarball to a local path.
#
# @param localPath the destination filepath for the tarball.
# @return an option to download a filesystem to the local system as a tarball.
fs downloadTarball(string localPath)

# Downloads the filesystem as a OCI filesystem bundle to a local path.
# See: https://github.com/opencontainers/runtime-spec/blob/master/bundle.md
#
# @param localPath the destination filepath for the tarball.
# @return an option to download a filesystem to the local system as a OCI
# filesystem bundle.
fs downloadOCITarball(string localPath)

# Downloads the filesystem as a Docker image tarball to a local path.
# The tarball is able to be loaded into a docker engine via `docker load`.
# See: https://docs.docker.com/engine/reference/commandline/save/
# and https://docs.docker.com/engine/reference/commandline/load/
#
# @param localPath the destination filepath for the tarball.
# @param ref the name of the Docker image.
# @return an option to download a filesystem to the local system as a Docker
# image tarball.
fs downloadDockerTarball(string localPath, string ref)

# A format specifier that is interpolated with values.
#
# @param formatString the format specifier.
# @param values the list of values to be interpolated into the format
# specifier.
# @return the resulting string from formatting.
string format(string formatString, variadic string values)

# The architecture for the clients local environment.
#
# @return the Arch
string localArch()

# The current working directory from the clients local environment.
#
# @return current working directory
string localCwd()

# An environment variable from the client's local environment.
#
# @param key the environment variable's key.
# @return the environment variable's value
string localEnv(string key)

# The OS from the clients local environment.
#
# @return the OS
string localOs()

# Executes an command in the local environment.
#
# If exactly one arg is given it will be wrapped with /bin/sh -c 'arg'.
# If more than one arg is given, it will be executed directly, without a shell.
#
# @param command a command to execute.
# @param args optional arguments to the command.
# @return the string output from the command
string localRun(string command, variadic string args)

# If the command returns a non-zero status code ignore
# the failure and continue processing the hlb file.
#
# @return an option to ignore errors on the command
option::localRun ignoreError()

# Capture stderr intermixed with stdout on the command.
#
# @return an option to capture stderr along with stdout on the command.
option::localRun includeStderr()

# Only capture the stderr from the command, ignore stdout.
#
# @return an option to ignore stdout on the command
option::localRun onlyStderr()

# Attempt to lex the single-argument shell command provided to `localRun`
# to determine if a `/bin/sh -c '...'` wrapper needs to be added.
#
# @return an option to attempt to optimize the command execution remoiving the /bin/sh -c "..." wrapper when possible.
option::localRun shlex()

# Process text as a Go text template.
# For template syntax documentation see:
#   https://golang.org/pkg/text/template/
#
# @param text the text of the template
# @return the text resulting from the processed template
string template(string text)

# Add a string field with provided name to be available
# inside the template.
#
# @param name the name of the field inside the template
# @param value the value of the field inside the template
# @return an option to add a field to the template
option::template stringField(string name, string value)

# Execute groups in parallel.
#
# @param groups the groups to run in parallel
# @return a group that finishes when all of its groups are finished.
group parallel(variadic group groups)