10 KiB
Advanced usage
Disposable release fixture
The target_test_project repository is a small standalone Cargo binary for Cross and Gitea integration tests. Clone it separately rather than expecting a submodule in this repository:
git clone https://proxy.dandaedre.com/gitea/idle-org/target_test_project.git
rust_realease ./target_test_project --dry-run
Its public v0.1.3 release was used to validate preparation, all three default Cross targets, published checksums, and isolated cargo-binstall installs. Use a new version and tag for future publication tests; release assets with the same names are deliberately treated as collisions.
Sources and package selection
SOURCE can be a local directory, an HTTP(S) Git URL, an SSH URL, or an SCP-style URL such as git@host:owner/repo.git. Remote sources are cloned into a managed checkout. Use --keep-workdir to retain that checkout and its artifacts; preparation retains remote checkouts automatically. Local sources are never deleted.
Use --package NAME to select one workspace member by its exact Cargo package name. Selection uses cargo metadata and accepts inherited workspace version and repository values. Library-only packages cannot be released. Every binary target declared by the selected package is built and packaged; this includes binaries with required-features when those features are enabled by the package's defaults. Checks, tests, and builds are scoped to the selected package.
--repository-url https://host/owner/repo selects the release destination when Cargo metadata or Git origin needs an explicit web URL. Materially conflicting origin and release destinations are refused. Repository URLs with embedded credentials are refused.
Configuration
Configuration is layered in this order, with later values taking precedence:
- bundled defaults;
- the user configuration at the platform-native config directory returned by the
directoriescrate (~/.config/rust_realease/config.tomlon Linux); rust-release.tomlin the acquired project root;- the file passed with
--config PATH; - CLI options.
Missing automatically discovered files are ignored. A path explicitly passed with --config must exist and be valid TOML. Repository fallback lists are combined across layers; a later entry for the same normalized origin replaces the earlier entry.
[release]
tag-prefix = "v"
[build]
targets = [
"x86_64-unknown-linux-musl",
"aarch64-unknown-linux-musl",
"x86_64-pc-windows-gnu",
]
profile = "release"
locked = true
[package]
format = "tgz"
[repository]
fallbacks = []
[gitea]
token-env = "GITEA_TOKEN"
Use --tag-prefix "" for an unprefixed tag such as 0.3.1. --tag TAG must match the selected package version and configured prefix. --unlocked permits builds without the usual locked dependency resolution; the default uses --locked.
package.format accepts "tgz", "binary", or "both". The default "tgz" produces cargo-binstall archives. "binary" produces only directly downloadable executables and does not require or verify cargo-binstall metadata. "both" produces both forms. The --artifact-format option overrides this setting for an individual run.
When a checkout uses an internal Git URL but its Gitea API and release downloads are exposed through another URL, configure an exact fallback pair. For example, either the project file or the user file can contain:
[[repository.fallbacks]]
origin = "http://git.dandaedre.com/idle-org/john-slop"
fallback-url = "https://proxy.dandaedre.com/gitea/idle-org/john-slop"
URLs are normalized, including removal of a trailing .git; SCP-style and SSH URLs normalize to HTTPS. The scheme remains significant for HTTP(S), so add separate rules if the same origin is used through both HTTP and SSH. Each rule matches one repository, not an entire host. The fallback must use HTTPS because it becomes the Gitea API and public download base. It is also written to package.repository during metadata repair. Git continues to clone and push through origin; the mapping tells the safety checks that the internal and public repositories are equivalent.
Metadata and preparation
The publisher checks the selected member's repository and, when archives are enabled, its cargo-binstall metadata. --fix-metadata repairs supported entries in that member's Cargo.toml while preserving comments where practical. It does not commit, tag, or push. To preview the full preparation diff, use --prepare-repo --dry-run.
The required binstall contract is:
[package.metadata.binstall]
pkg-url = "{ repo }/releases/download/v{ version }/{ name }-{ target }-v{ version }.tgz"
pkg-fmt = "tgz"
bin-dir = "{ name }-{ target }-v{ version }/{ bin }{ binary-ext }"
The generated pkg-url uses the configured tag prefix; the archive filename itself retains -v{version}. Unsupported binstall keys are reported as metadata conflicts. A preparation run may create one extra fix commit, as intended. --commit-preparation requires a clean worktree and index. --create-tag requires that commit option, and --push-preparation requires both. No option moves an existing tag or force pushes.
For repositories whose build scripts need a selected Rust toolchain inside Cross, preparation can add the supported Cross.toml environment setting. --cross-image-tag TAG explicitly selects ghcr.io/cross-rs/TARGET:TAG images. Existing unrelated Cross settings are preserved. Repository-provided Cross hooks such as pre-build, dockerfile, and runner are rejected by the release build.
Pipeline stages
--compile-only runs through the package stage and then stops: it performs host checks, cross-compiles, and writes local artifacts without creating or uploading a release. It is the explicit artifact-build mode and conflicts with --dry-run, --prepare-repo, and --stop-after.
--stop-after can stop at inspect, metadata, verify, build, package, release, upload, or binstall. verify runs host cargo check and cargo test; --skip-tests skips only tests. A successful Cross build from a clean checkout records its Git commit, package, targets, profile, lock mode, container engine, active Rust toolchain, and binary list. A later run with the same inputs reuses those regular binary files from Cargo's target directory; dirty checkouts, changed inputs, missing files, and invalid cache records build in a fresh target directory instead. --recompile explicitly bypasses a matching completed build. release creates or reuses the Gitea release; upload uploads archives and checksums. The final stage downloads assets anonymously for public repositories or with Gitea authentication for private repositories, checks their checksums and archive layout, and runs isolated cargo-binstall installs for public targets. --skip-binstall-test skips that install check, while retaining download verification.
--draft --stop-after upload is useful when a release must stay private for review. Private repositories require --skip-binstall-test; cargo-binstall cannot fetch their attachment URLs, even when GITEA_TOKEN is set. --prerelease and --draft set properties when a release is created; reusing a release preserves its existing settings. -m/--message TEXT sets release notes, while --message-file PATH reads them from a UTF-8 file; they are mutually exclusive. Notes are included when creating a release and replace the body of an existing tagged release when explicitly supplied. Asset replacement is not transactional: if an upload fails after a matching asset is deleted, retry the publication explicitly.
Artifact contract
Each archive is named {name}-{target}-v{version}.tgz and contains exactly one root directory with every binary declared by the selected package:
my-tool-x86_64-unknown-linux-musl-v0.1.0.tgz
└── my-tool-x86_64-unknown-linux-musl-v0.1.0/
├── my-tool
└── my-tool-helper
Windows archive members have an .exe suffix. Raw assets are target-qualified to remain unambiguous, for example my-tool-x86_64-unknown-linux-musl-v0.1.0 and my-tool-x86_64-pc-windows-gnu-v0.1.0.exe. SHA256SUMS lists every generated asset. Archive ownership and timestamps are normalized; identical binary bytes and modes produce identical archives. Separate builds can still produce different binaries.
Authentication and security
Authenticated Gitea API publication requires HTTPS. The token comes from the configured environment variable, never from a positional argument or URL. Child Cargo and Cross processes do not receive it. An HTTPS preparation push to the matching release repository can use the token through a temporary askpass helper; SSH pushes use normal Git credentials. Grant the token account code read and release write access, plus code write when using --push-preparation.
Normal publication does not create a commit, tag, or push. Existing asset names cause an error unless --replace-assets is set; unrelated assets are not deleted. Private assets are verified with authenticated downloads and do not establish public installability.
Troubleshooting
- Missing tag: prepare and push the expected tag explicitly, or use
--prepare-repo --commit-preparation --create-tag --push-preparationfrom a clean checkout. - Missing Cargo.lock: run preparation or use
--unlockedwhen unlocked resolution is intentional. - Container unavailable: start Docker or Podman.
CROSS_CONTAINER_ENGINEcan selectdockerorpodman. - Cross image or native library failure: configure an appropriate Cross image and target libraries in the project. The publisher does not substitute an MSVC target or hide linker failures.
- Private release installation: pass
--skip-binstall-testto verify the uploaded assets with Gitea authentication. Use a public disposable release to test real cargo-binstall installation. - Asset collision: inspect the existing release; use
--replace-assetsonly when replacement is intended.
cargo-binstall verification installs into temporary directories and does not run foreign-target binaries. Plain registry based cargo binstall my-tool additionally requires a published crate with the release metadata; this tool does not publish crates.