102 lines
8.0 KiB
Markdown
102 lines
8.0 KiB
Markdown
# Advanced usage
|
|
|
|
## Disposable release fixture
|
|
|
|
The [target_test_project repository](https://proxy.dandaedre.com/gitea/idle-org/target_test_project) is a small standalone Cargo binary for Cross and Gitea integration tests. Clone it separately rather than expecting a submodule in this repository:
|
|
|
|
```bash
|
|
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](https://proxy.dandaedre.com/gitea/idle-org/target_test_project/releases/tag/v0.1.3) 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
|
|
|
|
The bundled `config.toml` supplies defaults. Pass `--config PATH` to use another file; CLI values override its build and tag settings.
|
|
|
|
```toml
|
|
[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`.
|
|
|
|
`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.
|
|
|
|
## 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:
|
|
|
|
```toml
|
|
[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 every binary declared by the selected package:
|
|
|
|
```text
|
|
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-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.
|