Publishing & Building the fls‑rs Rust crate

This guide walks you (and CI) through every step required to turn the FastLanes Rust bindings into a versioned release on https://crates.io. It assumes you are in the project‑root and have the tooling listed below.

1 Prerequisites

Tip: On fresh CI runners nothing but rustup and the host compiler toolchain are usually pre‑installed. The Makefile’s version-bump-rust rule installs cargo-edit automatically if the sub‑command is missing.

2 Project layout recap

FastLanes/
├─ mk/               # this Makefile lives here
├─ rust/             # Cargo workspace member (crate root)
│  ├─ src/
│  ├─ build.rs       # emits VERGEN_* vars & builds C++
│  └─ vendor/fastlanes/ (optional)  # vendored fallback for crates.io build
├─ include/ & src/   # C++ headers & source used when building from Git checkout
└─ CMakeLists.txt    # top‑level CMake build for C++ core

3 One‑liner cheat‑sheet

# 1. Tag the release (annotated tag `v0.2.0`)
git tag -s v0.2.0 -m "FastLanes 0.2.0"

# 2. Dry‑run the publish to be safe
make dry-run-rust       # rewrites Cargo.toml → 0.2.0

# 3. Publish for real
make publish-rust       # uploads if the dry‑run looked good

All other common tasks:

4 How the Makefile automates versioning

1. version-bump-rust (called by both publish targets) executes

   GIT_TAG := $(shell git describe --tags --abbrev=0)
   SEMVER  := $(patsubst v%,%,$(GIT_TAG))
   

   extracting 0.2.0 from the last tag v0.2.0.

2. It ensures cargo-set-version is available:

   command -v cargo-set-version || cargo install cargo-edit -q
   

3. Finally, it writes that semver into every Cargo.toml in the workspace:

   cargo set-version 0.2.0 --manifest-path rust/Cargo.toml --workspace
   

4. The subsequent cargo publish therefore uploads fls-rs v0.2.0.

Common pitfalls

5 Publishing from CI

1. GitHub Actions secret: add CRATES_IO_TOKEN.

2. Checkout, install LLVM/Clang and libc++ (see existing workflow).

3. Add a final job step:

   - name: Publish fls-rs
     run: |
       cargo login $CRATES_IO_TOKEN
       make publish-rust
   

   Because the Makefile bumps the manifest first, the workflow will fail early if no Git tag is present.

6 Updating the vendored C++ sources

When you change headers or C++ code in the main workspace:

make update-fastlanes-src  # copies src/include → rust/vendor/… & commits

This ensures the crate remains buildable when fetched from crates.io (where the Git workspace is not available).

7 FAQ

cargo yank --vers 0.2.0

Happy releasing! 🎉