|
|
|
|
@ -1,210 +1,3 @@
|
|
|
|
|
# target_test_project
|
|
|
|
|
|
|
|
|
|
`target_test_project` is a small Rust binary used as a disposable integration
|
|
|
|
|
target for
|
|
|
|
|
[`rust_realease`](https://proxy.dandaedre.com/gitea/idle-org/rust_realease).
|
|
|
|
|
It exercises repository preparation, Cross compilation, Gitea release uploads,
|
|
|
|
|
checksums, and `cargo-binstall` installation without using a production project.
|
|
|
|
|
|
|
|
|
|
The program prints its package version and the architecture and operating
|
|
|
|
|
system for which it was compiled.
|
|
|
|
|
|
|
|
|
|
## Prerequisites
|
|
|
|
|
|
|
|
|
|
Install the following before running a complete release:
|
|
|
|
|
|
|
|
|
|
- Rust and Cargo;
|
|
|
|
|
- Git;
|
|
|
|
|
- Docker or Podman, running and available to
|
|
|
|
|
[Cross](https://github.com/cross-rs/cross);
|
|
|
|
|
- `cross` and `cargo-binstall`;
|
|
|
|
|
- a Gitea token with repository read and release write access;
|
|
|
|
|
- working Git credentials with code write access when `rust_realease` pushes
|
|
|
|
|
the preparation commit and tag. This repository's `origin` uses SSH, so the
|
|
|
|
|
push uses the configured SSH key rather than the Gitea token.
|
|
|
|
|
|
|
|
|
|
Install the supporting tools and the publisher:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
cargo install cross --locked
|
|
|
|
|
cargo install cargo-binstall --locked
|
|
|
|
|
cargo binstall --git https://proxy.dandaedre.com/gitea/idle-org/rust_realease \
|
|
|
|
|
rust_realease
|
|
|
|
|
rust_realease --help
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Alternatively, clone `rust_realease` and install the development checkout with
|
|
|
|
|
`cargo install --path . --locked`.
|
|
|
|
|
|
|
|
|
|
## One-time repository configuration
|
|
|
|
|
|
|
|
|
|
The Git remote for this project uses the internal SSH address while Cargo and
|
|
|
|
|
Gitea releases use the public proxy. Add the exact mapping below to
|
|
|
|
|
`~/.config/rust_realease/config.toml` on Linux. If the file already exists,
|
|
|
|
|
merge this entry with its existing settings instead of replacing the file.
|
|
|
|
|
|
|
|
|
|
```toml
|
|
|
|
|
[[repository.fallbacks]]
|
|
|
|
|
origin = "git@git.dandaedre.com:idle-org/target_test_project.git"
|
|
|
|
|
fallback-url = "https://proxy.dandaedre.com/gitea/idle-org/target_test_project"
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
This allows `rust_realease` to keep using `origin` for Git operations while it
|
|
|
|
|
uses the HTTPS proxy for the Gitea API, release downloads, and cargo-binstall
|
|
|
|
|
verification.
|
|
|
|
|
|
|
|
|
|
## Preview the existing project
|
|
|
|
|
|
|
|
|
|
Clone the fixture, enter it, and run a read-only inspection:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
git clone git@git.dandaedre.com:idle-org/target_test_project.git
|
|
|
|
|
cd target_test_project
|
|
|
|
|
rust_realease . --dry-run
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The dry run shows the detected package and version, expected tag, targets,
|
|
|
|
|
artifact names, required metadata, and release destination. It does not edit
|
|
|
|
|
files, build binaries, create tags, or contact the Gitea release API.
|
|
|
|
|
|
|
|
|
|
Version `0.1.3` and tag `v0.1.3` have already been published. Always choose a
|
|
|
|
|
new version for another end-to-end test; reusing it causes intentional release
|
|
|
|
|
asset collision errors.
|
|
|
|
|
|
|
|
|
|
## Make a test release
|
|
|
|
|
|
|
|
|
|
### 1. Choose and commit a new version
|
|
|
|
|
|
|
|
|
|
Start from an up-to-date, clean branch. Change `package.version` in
|
|
|
|
|
`Cargo.toml` to a version that has never been released, for example `0.1.4`.
|
|
|
|
|
Then update the lockfile, run the local checks, and commit the version change:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
git pull --ff-only
|
|
|
|
|
cargo check
|
|
|
|
|
cargo test
|
|
|
|
|
git diff -- Cargo.toml Cargo.lock
|
|
|
|
|
git add Cargo.toml Cargo.lock
|
|
|
|
|
git commit -m "Bump target_test_project to 0.1.4"
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Replace `0.1.4` in this guide with the version you actually selected. The
|
|
|
|
|
publisher expects the tag `v<version>` by default.
|
|
|
|
|
|
|
|
|
|
### 2. Preview repository preparation
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
rust_realease . --prepare-repo --dry-run
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Preparation checks and, when necessary, repairs the cargo-binstall metadata,
|
|
|
|
|
`.gitignore`, `Cross.toml`, and `Cargo.lock`. Review the displayed diff before
|
|
|
|
|
continuing.
|
|
|
|
|
|
|
|
|
|
### 3. Prepare, tag, and push
|
|
|
|
|
|
|
|
|
|
The following command applies the preparation from a clean checkout, commits
|
|
|
|
|
only files managed by the publisher when they changed, creates the annotated
|
|
|
|
|
version tag, and atomically pushes the branch and tag. It never force-pushes or
|
|
|
|
|
moves an existing tag.
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
rust_realease . --prepare-repo \
|
|
|
|
|
--commit-preparation \
|
|
|
|
|
--create-tag \
|
|
|
|
|
--push-preparation
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
If you prefer to review and commit every change manually, run
|
|
|
|
|
`rust_realease . --prepare-repo`, commit the resulting files, create an
|
|
|
|
|
annotated `v<version>` tag, and push both the branch and tag before publishing.
|
|
|
|
|
|
|
|
|
|
### 4. Build the release artifacts locally
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
rust_realease . --compile-only
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
This runs host `cargo check` and `cargo test`, builds the default target matrix
|
|
|
|
|
with Cross, and writes archives plus `SHA256SUMS` under a new
|
|
|
|
|
`dist/release-*/` directory. It does not create or modify a Gitea release.
|
|
|
|
|
|
|
|
|
|
The default targets are:
|
|
|
|
|
|
|
|
|
|
- `x86_64-unknown-linux-musl`;
|
|
|
|
|
- `aarch64-unknown-linux-musl`;
|
|
|
|
|
- `x86_64-pc-windows-gnu`.
|
|
|
|
|
|
|
|
|
|
Use repeatable `--target <target-triple>` options to override the matrix. Add
|
|
|
|
|
`--recompile` to ignore a reusable successful build, or
|
|
|
|
|
`--artifact-format both` to produce standalone binaries as well as the default
|
|
|
|
|
cargo-binstall `.tgz` archives.
|
|
|
|
|
|
|
|
|
|
### 5. Preview publication
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
rust_realease . --dry-run
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Resolve every reported problem before the live run. In particular, the
|
|
|
|
|
checkout must be clean, the local tag must point at `HEAD`, and the same tag
|
|
|
|
|
must exist on `origin`.
|
|
|
|
|
|
|
|
|
|
### 6. Publish and verify the Gitea release
|
|
|
|
|
|
|
|
|
|
Read the token without putting it in shell history, then run the publisher:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
read -r -s -p 'Gitea token: ' GITEA_TOKEN
|
|
|
|
|
printf '\n'
|
|
|
|
|
export GITEA_TOKEN
|
|
|
|
|
rust_realease . --message "target_test_project 0.1.4"
|
|
|
|
|
unset GITEA_TOKEN
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Use `--message-file CHANGELOG.md` instead of `--message` for release notes from
|
|
|
|
|
a UTF-8 file. The options are mutually exclusive.
|
|
|
|
|
|
|
|
|
|
The live command creates or reuses the tagged Gitea release, uploads every
|
|
|
|
|
archive and `SHA256SUMS`, downloads the assets again, verifies their checksums
|
|
|
|
|
and layouts, and tests isolated cargo-binstall installations. Existing assets
|
|
|
|
|
with the same names stop the upload. Use `--replace-assets` only after checking
|
|
|
|
|
the existing release and intentionally deciding to replace them.
|
|
|
|
|
|
|
|
|
|
### 7. Check installation as a user
|
|
|
|
|
|
|
|
|
|
The publisher already performs this check for public releases, but it can also
|
|
|
|
|
be repeated manually:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
cargo binstall --git \
|
|
|
|
|
https://proxy.dandaedre.com/gitea/idle-org/target_test_project \
|
|
|
|
|
target_test_project
|
|
|
|
|
target_test_project
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Useful variations
|
|
|
|
|
|
|
|
|
|
Run against a remote checkout and select its release tag explicitly:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
rust_realease \
|
|
|
|
|
https://proxy.dandaedre.com/gitea/idle-org/target_test_project.git \
|
|
|
|
|
--tag v0.1.4
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Stop after host validation without Cross compilation or publication:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
rust_realease . --stop-after verify
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Build raw executables instead of cargo-binstall archives:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
rust_realease . --artifact-format binary --compile-only
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
For the complete option and configuration reference, see the
|
|
|
|
|
[`rust_realease` README](https://proxy.dandaedre.com/gitea/idle-org/rust_realease)
|
|
|
|
|
and run `rust_realease --help`.
|
|
|
|
|
Target project for the rust_release project
|