fls-rs

Crates.io	fls-rs
lib.rs	fls-rs
version	0.1.3-alpha.7
created_at	2025-05-19 18:49:26.610918+00
updated_at	2025-05-25 01:01:29.479174+00
description	FastLanes File Format
homepage	https://fastlanes.io
repository	https://github.com/cwida/FastLanes
max_upload_size
id	1680248
size	16,052,646

Azim Afroozeh (azimafroozeh)

documentation

https://docs.rs/fls-rs

README

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

Tool	Minimum	Why
Rust toolchain	1.77.0 (stable)	Needed for `cargo set-version`. Older toolchains work if you install cargo‑edit.
cargo‑edit	latest	Autoinstalled by the Makefile when missing.
C & C++ compilers	clang/gcc	CMake builds the C++ core; `cxx-build` compiles the bridge shim.
CMake	≥3.18	Generates the FastLanes static library.
Git	with annotated tags	The Makefile reads the latest `vX.Y.Z` tag to version the crate.

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:

Action	Command
Build (optimised)	`make build-rust`
Install to local prefix	`make install-rust`
Run example program	`make run-rust-example`
Format Rust sources	`make rust-format`
Clean artefacts & vendored copy	`make clean-rust`

4 How the Makefile automates versioning

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.

It ensures cargo-set-version is available:

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

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

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

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

Common pitfalls

Symptom	Cause & Fix
`✘ No git tag found`	You forgot to create an annotated tag. Run `git tag -s vX.Y.Z -m "…"`.
`no such command: set-version`	Toolchain <1.77 and cargo-edit not installed. The rule now auto‑installs it.
Crate builds but prints `v0.0.0` at runtime	You’re using `env!("CARGO_PKG_VERSION")` instead of the Git‑derived constant `env!("VERGEN_GIT_SEMVER")`.

5 Publishing from CI

GitHub Actions secret: add CRATES_IO_TOKEN.
Checkout, install LLVM/Clang and libc++ (see existing workflow).
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

What if I need to yank a version?

cargo yank --vers 0.2.0

Remember to tag the repo with a new point‑release afterwards.

The C++ build fails on crates.io but works locally.

Make sure you ran make update-fastlanes-src before publishing and that no absolute include paths leak into the build (-I/usr/local/include).

Why don’t we inject the Git tag directly from build.rs?

Cargo locks the crate version from Cargo.toml before running the build script. Overwriting it afterwards has no effect, so we edit the manifest up‑front instead.

Happy releasing! 🎉

Commit count: 36