119 lines
4.3 KiB
Markdown
119 lines
4.3 KiB
Markdown
# rust_realease
|
|
|
|

|
|

|
|

|
|
|
|
`rust_realease` builds Rust binary packages for multiple targets and publishes
|
|
them as Gitea or GitHub release assets, including mirrored releases sent to
|
|
multiple repositories. It is intended for maintainers who want
|
|
repeatable Cross builds, checksums, cargo-binstall archives, and post-upload
|
|
verification without maintaining a separate release pipeline.
|
|
|
|
## Prerequisites and installation
|
|
|
|
Install [Git](https://git-scm.com/),
|
|
[Cross](https://github.com/cross-rs/cross), and a Cross-compatible Docker or
|
|
Podman backend. The default archive format also requires
|
|
[cargo-binstall](https://github.com/cargo-bins/cargo-binstall).
|
|
|
|
Install the latest prebuilt release:
|
|
|
|
```bash
|
|
cargo binstall --git https://proxy.dandaedre.com/gitea/idle-org/rust_realease \
|
|
rust_realease
|
|
rust_realease --help
|
|
```
|
|
|
|
To build the current checkout instead:
|
|
|
|
```bash
|
|
cargo install --path . --locked
|
|
```
|
|
|
|
## Quick start
|
|
|
|
Preview a local project without changing files, building binaries, or
|
|
contacting a release service:
|
|
|
|
```bash
|
|
rust_realease ./my-tool --dry-run
|
|
```
|
|
|
|
The preview reports the selected package and binaries, expected version tag,
|
|
metadata changes, build targets, artifact names, prerequisites, and release
|
|
destination. It exits nonzero when something needs attention. Select a package
|
|
explicitly when the source is a workspace:
|
|
|
|
```bash
|
|
rust_realease ./my-workspace --package my-tool --dry-run
|
|
```
|
|
|
|
Build local artifacts through the package stage with:
|
|
|
|
```bash
|
|
rust_realease ./my-tool --compile-only
|
|
```
|
|
|
|
This mode does not require a release token or contact Gitea or GitHub. Artifacts and
|
|
`SHA256SUMS` are written under `dist/release-*/`. A later publication with the
|
|
same clean commit and build settings reuses the completed target builds; pass
|
|
`--recompile` to rebuild them instead.
|
|
|
|
## Publish a release
|
|
|
|
The package version must match a local tag, and the same tag must already
|
|
exist on the remote. Publication also requires a clean checkout and an HTTPS
|
|
Gitea or GitHub release destination.
|
|
|
|
For one destination, store an access token in a single-line UTF-8 file:
|
|
|
|
```bash
|
|
rust_realease ./my-tool --token-file ../gitea_token.txt
|
|
```
|
|
|
|
The token file takes precedence over the configured token environment
|
|
variable. Without `--token-file`, the defaults are `GITEA_TOKEN` and
|
|
`GITHUB_TOKEN`. Grant the token
|
|
repository read and release write access; preparation pushes also require code
|
|
write access. Tokens are redacted from diagnostics and are not passed to Cargo
|
|
or Cross child processes.
|
|
|
|
Configure named `[[release.endpoints]]` entries to publish the same release to
|
|
several repositories. Each can use its own `token-env`, or `--token-file` can
|
|
point to a JSON object whose keys match the endpoint names. See the advanced
|
|
guide for the complete configuration and token-file format.
|
|
|
|
Use `--prepare-repo --dry-run` to preview supported metadata and repository
|
|
preparation before publishing. See the advanced guide for explicit commit,
|
|
tag, push, release-note, private-repository, and asset-replacement workflows.
|
|
|
|
## Documentation
|
|
|
|
- [Advanced usage](docs/advanced-usage.md) covers sources, configuration,
|
|
metadata preparation, pipeline stages, artifact formats, authentication,
|
|
this repository's release procedure, and troubleshooting.
|
|
- [Cross configuration](docs/advanced-usage.md#cross-configuration) explains
|
|
target images, environment passthrough, and global or target-specific
|
|
`pre-build` commands for native build dependencies.
|
|
- `rust_realease --help` is the complete option reference.
|
|
|
|
## Development
|
|
|
|
From the repository root, run:
|
|
|
|
```bash
|
|
cargo fmt --check
|
|
cargo clippy --all-targets --all-features -- -D warnings
|
|
cargo test --locked --all
|
|
```
|
|
|
|
Jenkins enforces an 80% line-coverage floor. The opt-in real cargo-binstall
|
|
fixture requires its external test repository and is ignored by the ordinary
|
|
test suite; its setup is documented in [Advanced usage](docs/advanced-usage.md#disposable-release-fixture).
|
|
|
|
## License and support
|
|
|
|
This project is licensed under the [MIT License](LICENSE). Report problems in
|
|
the canonical [Gitea repository](https://proxy.dandaedre.com/gitea/idle-org/rust_realease/issues).
|