rust-demo (0.1.0)
Installation
[registry]
default = "gitea"
[registries.gitea]
index = "sparse+https://mgit.flexsiebels.de/api/packages/mAi/cargo/" # Sparse index
# index = "https://mgit.flexsiebels.de/mAi/_cargo-index.git" # Git
[net]
git-fetch-with-cli = truecargo add rust-demo@0.1.0About this package
rust-demo
A small Rust library that counts words, sentences and letters in German text, with a command line front end. It exists to show what a Rust crate is made of and how a crate is published to and consumed from the Cargo registry built into our Gitea at mgit.msbls.de.
What each file is for
| File | Purpose |
|---|---|
Cargo.toml |
The manifest. It names the package, its version, its licence and its dependencies. Cargo reads this file first; everything below follows from it. |
Cargo.lock |
The exact versions Cargo resolved. A crate that ships a binary commits this file so that a build is reproducible; a library-only crate usually does not. |
src/lib.rs |
The library target. Cargo compiles it into a crate named rust_demo (a hyphen in the package name becomes an underscore in the crate name). This is the code another crate can depend on. |
src/main.rs |
The binary target. Cargo compiles it into an executable also called rust-demo, which uses the library the same way any other crate would. |
examples/gedicht.rs |
An example target: a second small program that shows the library in use. Cargo compiles every file under examples/ on cargo test, so an example that stops compiling fails the build. |
.gitignore |
Keeps target/, Cargo's build directory, out of git. |
.cargo/config.toml |
Registers the mgit Cargo registry under the name mgit for commands run inside this repository. It holds no token. |
There are three kinds of test in this crate, and cargo test runs all of them:
- Unit tests — the
mod testsblock at the bottom ofsrc/lib.rs. They sit next to the code and can reach private items. - Doc tests — the fenced code blocks inside the
///doc comments. Cargo compiles and runs each one, so a documented example cannot go stale. - The example —
examples/gedicht.rsis compiled, which proves the public API still fits the way a caller uses it.
Cargo commands
cargo build # compile the library and the binary into target/debug/
cargo build --release # the same, optimised, into target/release/
cargo test # unit tests + doc tests, and compile the examples
cargo run -- "Guten Morgen!" # run the binary; everything after -- goes to the program
echo "Hallo Welt." | cargo run # with no arguments the binary reads standard input
cargo run --example gedicht # run the example
cargo doc --open # build the API documentation from the doc comments and open it
cargo fmt # format every file to the standard Rust style
cargo clippy -- -D warnings # the linter; -D warnings turns every lint into an error
cargo fmt and cargo clippy are separate programs that Cargo calls as subcommands. On this machine the toolchain comes from Nix, so all four are in ~/.nix-profile/bin: cargo 1.98.0, rustc 1.98.1, rustfmt 1.9.0, clippy 0.1.98. On a rustup toolchain they are components instead, added with rustup component add rustfmt clippy.
Depending on this crate from the mgit registry
Gitea serves a Cargo registry per owner. This crate is published under the owner mAi, so its index is https://mgit.msbls.de/api/packages/mAi/cargo/.
1. Register the registry once, in your own ~/.cargo/config.toml (or per project, in .cargo/config.toml next to Cargo.toml):
[registries.mgit]
index = "sparse+https://mgit.msbls.de/api/packages/mAi/cargo/"
sparse+ selects the HTTP index protocol, which Gitea serves directly. No index git repository has to be cloned.
2. Declare the dependency in the consuming crate's Cargo.toml:
[dependencies]
rust-demo = { version = "0.1.0", registry = "mgit" }
A dependency from a registry other than crates.io always names that registry; without registry = "mgit" Cargo looks on crates.io and fails.
3. Use it in code — the hyphen becomes an underscore:
fn main() {
let stats = rust_demo::analyze("Der Fußgänger überquert die Straße.");
println!("{stats}");
}
Reading this registry needs no token. A token is only needed to publish.
Proving it end to end
This sequence builds a throwaway crate against the published package, outside this repository:
cargo new /tmp/rust-demo-consumer
cd /tmp/rust-demo-consumer
mkdir -p .cargo
cat > .cargo/config.toml <<'EOF'
[registries.mgit]
index = "sparse+https://mgit.msbls.de/api/packages/mAi/cargo/"
EOF
cargo add rust-demo@0.1.0 --registry mgit
cargo run
cargo add writes the dependency line for you. cargo run then downloads rust-demo 0.1.0 from mgit, compiles it, and builds the consumer against it.
Publishing a new version
cargo publish --registry mgit
The token goes through the environment and never into a file, a commit or a log:
CARGO_REGISTRIES_MGIT_TOKEN="Bearer <gitea-token>" cargo publish --registry mgit
The variable name is CARGO_REGISTRIES_<NAME>_TOKEN with the registry name in upper case, so the registry called mgit above reads CARGO_REGISTRIES_MGIT_TOKEN. The value carries the Bearer prefix, which is what Gitea expects.
A published version is immutable: a registry refuses a second upload of 0.1.0. Raise the version field in Cargo.toml for every publish.
The package page is https://mgit.msbls.de/mAi/-/packages/cargo/rust-demo.
Licence
MIT. See LICENSE.