Statics
A static is a special function that gets resolved by Brioche before your script runs, most commonly returning a recipe.
Some statics are resolved by reading files locally from your project, others get resources from the internet and record the results in your project’s lockfile. In either case, using a static lets you “pull in” something from outside Brioche, but in a way that Brioche can track to guarantee reliability.
Since they are resolved so early in the process, there are some restrictions on how you can define and use them in your scripts (hence why they are called “statics”). When calling a static function, all of the arguments must use string literals! In the root module (project.bri
), you can use string templates that reference the project metadata value as well. If you try to pass a string from a dynamic value or other variable for a static recipe, you will get an error when trying to build your project.
All of these statics are implemented by the std
package, so you will need import std
in your project to use them. This also means that, if a new static gets added, you’ll need to both update Brioche and update the std
package to use it.
Brioche.includeFile
Returns a file recipe from a file in your project. The path is resolved relative to the current module.
Brioche.includeDirectory
Returns a directory recipe from a directory in your project. The path is resolved relative to the current module.
Note that all files within the directory are included! If you want to include only some files, consider using Brioche.glob
instead.
Brioche.glob
Return a directory recipe from a list of glob patterns. Any files relative to the current module that match the glob pattern will be included in the directory. Included files will have the same path, relative to the directory recipe.
Glob patterns are matched using the globset
Rust crate.
Note that using a glob pattern that tries to traverse outside the module’s directory will not work.
Brioche.download
Returns a file recipe containing the contents of the provided URL. The hash of the URL’s contents will be recorded in the lockfile, and the hash from the lockfile will be used to validate the download in subsequent builds if not already cached. This ensures that the URL’s contents are the same, even when running the build on a different machine.
This function is similar to std.download
, except the hash is handled for you using the lockfile.
The project metadata can also be used as part of the URL, which helps to ensure that the right version of a release gets downloaded.
Brioche.gitRef
Takes a git repository URL and a git ref (such as a branch or tag name), and returns an object containing the repository URL and a git commit hash. Brioche will query the repository URL to get the current commit hash for the ref, then record the result in the lockfile. The same commit hash will be returned until the lockfile is updated again, even if the ref changes in the repository.
This function is best paired with the gitCheckout
function from the git
package, which can checkout the repository from the returned commit.
Only public git repositories can be used, since authentication is disabled when querying the repository. Additionally, querying the repository uses the gitoxide
Rust crate, which means that some legacy git protocol versions aren’t supported.
The project metadata can also be used for either the repository URL or for the git ref, which can be used to check out the correct version of the source code.