rust_realease/docs/advanced-usage.md

7.2 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 and members with multiple binaries cannot be released. 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

The bundled config.toml supplies defaults. Pass --config PATH to use another file; CLI values override its build and tag settings.

[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"

[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.

Metadata and preparation

The publisher checks the selected member's repository and 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

--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. Release builds use fresh target directories to avoid stale build-script output. 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. 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 one binary:

my-tool-x86_64-unknown-linux-musl-v0.1.0.tgz
└── my-tool-x86_64-unknown-linux-musl-v0.1.0/
    └── my-tool

Windows archives contain my-tool.exe. SHA256SUMS lists the final archive checksums. 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-preparation from a clean checkout.
  • Missing Cargo.lock: run preparation or use --unlocked when unlocked resolution is intentional.
  • Container unavailable: start Docker or Podman. CROSS_CONTAINER_ENGINE can select docker or podman.
  • 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-test to 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-assets only 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.