Cake.Download.Module 0.1.0-preview.1

Cake.Download.Module

A Cake module that installs command-line tools that are not on NuGet, such as GitHub release assets or any file on an HTTPS server, with the download: scheme. It downloads the file for the current platform, verifies its SHA-256, extracts it if it is an archive, and registers the tool so Cake's aliases and Context.Tools.Resolve(...) find it.

Install

Cake .NET Tool (build.cake):

#module nuget:?package=Cake.Download.Module&version=0.1.0-preview.1
#tool "download:https://github.com/jqlang/jq/releases/download/jq-{version}/jq-{os}-{arch}{exe}?package=jq&version=1.8.2&os.darwin=macos&checksums=sha256sum.txt&checksums_sha256=dc86824a41c165ece971ff691aff6e08bbfe6e1d1f531688b47ee78c283a85cd"

Cake SDK (cake.cs):

#:sdk Cake.Sdk@6.3.0
#:package Cake.Download.Module@0.1.0-preview.1

InstallTool("download:https://github.com/jqlang/jq/releases/download/jq-{version}/jq-{os}-{arch}{exe}?package=jq&version=1.8.2&os.darwin=macos&checksums=sha256sum.txt&checksums_sha256=dc86824a41c165ece971ff691aff6e08bbfe6e1d1f531688b47ee78c283a85cd");

Cake Frosting:

return new CakeHost()
    .UseModule<Cake.Download.Module.DownloadModule>()
    .InstallTool(new Uri("download:https://github.com/jqlang/jq/releases/download/jq-{version}/jq-{os}-{arch}{exe}?package=jq&version=1.8.2&os.darwin=macos&checksums=sha256sum.txt&checksums_sha256=dc86824a41c165ece971ff691aff6e08bbfe6e1d1f531688b47ee78c283a85cd"))
    .Run(args);

The directive

download:<url-template>?package=<name>&version=<version>[&<parameter>=<value>]*

Exactly one integrity option is required. Leave it out once, and the error message contains the exact parameter to paste, with the hash of what was downloaded.

Parameter values are percent-decoded, so a value containing =, &, ? or # (notably url=) must be percent-encoded; otherwise Cake reports "Could not parse query string.". package and version must start with a letter or digit. Placeholders are expanded in the URL, url, url.<rid>, checksums, filename, include and exclude. Validation is strict: unknown parameters are errors.

Placeholders and dialects

{version}, {rid} (win-x64, linux-arm64, osx-arm64, …), {exe} (.exe on Windows) and {archive} (zip on Windows, tar.gz elsewhere) work in every dialect. Supported platforms: win-x64, win-x86, win-arm64, linux-x64, linux-arm64, linux-arm, osx-x64, osx-arm64.

In the rust dialect, {triple} on Linux defaults to musl (x86_64-unknown-linux-musl); override it per platform with triple.<rid>=.

Examples

// Archive whose format differs per OS (gh)
#tool "download:https://github.com/cli/cli/releases/download/v{version}/gh_{version}_{os}_{arch}.{archive}?package=gh&version=2.62.0&os.darwin=macOS&archive.darwin=zip&checksums=gh_{version}_checksums.txt&checksums_sha256=89dc6f5225aa0c70d6f90950f5246225afff2f423f3d242f7d8813fe9993af4d"

// Rust target triples (ripgrep), per-platform pins
#tool "download:https://github.com/BurntSushi/ripgrep/releases/download/{version}/ripgrep-{version}-{triple}.{archive}?package=rg&version=14.1.1&dialect=rust&sha256.win-x64=d0f534024c42afd6cb4d38907c25cd2b249b79bbe6cc1dbee8e3e37c2b6e25a1&sha256.linux-x64=4cf9f2741e6c465ffdb7c26f38056a59e2a2544b51f7cc128ef28337eeae4d8e&sha256.osx-arm64=24ad76777745fbff131c8fbc466742b011f925bfa4fffa2ded6def23b5b937be"

// .NET RIDs (cyclonedx-cli)
#tool "download:https://github.com/CycloneDX/cyclonedx-cli/releases/download/v{version}/cyclonedx-{rid}{exe}?package=cyclonedx&version=0.30.0&dialect=dotnet&sha256.win-x64=1f563ba9644d2f2966fc8029fd701ca4af4f388d44c017c1d60559a1ecc9114f&sha256.linux-x64=f89876326620f5fc78a9b27cc1af57d6ed13d019aab87490e1246a44a910babb&sha256.osx-arm64=dabbaf07e543e7996f708147475e2daa69ddf8a8683c5b06febc7d3f074e5e24"

Where tools go

Each tool is installed into <tools>/<package>.<version>/ (Cake's tools folder, ./tools by default). Archives are extracted verbatim. A .cake-download.json file records what was installed, and later builds with the same directive make no network requests. Different versions are installed side by side and never deleted automatically.

Limitations

Only public HTTPS downloads: no authentication, private repositories, mirrors or signature verification. Archive formats are zip, tar and tar.gz. Authenticated (NTLM) proxies are not supported. On Windows, symbolic links to directories inside tar archives are not materialized.

License

MIT