chore: update packer metadata and readme

2026-08-06 13:47:05 +08:00
parent bf0837e4a6
commit f9333c72be
2 changed files with 71 additions and 3 deletions
@@ -1,5 +1,52 @@
 # sarasacw-omrf-packer

+`sarasacw-omrf-packer` is the distribution packer of the Sarasas Chip Workshop Oh My Rust FFI (OMRF) toolset.
+Given a Rust project that exposes a C-friendly FFI as a `cdylib`, it assembles a CMake-style redistributable tree.
+It involves header files, the built dynamic library, and generated CMake and pkg-config package files,
+and it can additionally bundle the result into a zip archive.
+
+It targets Rust FFI projects that need to be distributed and consumed like ordinary CMake/pkg-config packages, 
+including on MSVC-only Windows toolchains where pkg-config alone is not enough.
+
+## Status
+
+Barely works for the specific workflow of Sarasas Chip Workshop.
+And will be improved by new requirement coming from Sarasas Chip Workshop devlopment.
+
+Projects declare the minimum required packer version through the `min_version` field in their `[package.metadata.omrf]` table; 
+running an older packer than requested fails fast with a clear error.
+
+## License
+
+Licensed under the MIT License.
+
+## Usage
+
+Install from PyPI (the project is built with `uv`, but `pipx install` or `pip install` work just as well on the published wheel):
+
+```console
+uv tool install sarasacw-omrf-packer
+```
+
+The packer does not build the project itself. Build it first -- `cargo build --release`, adding `--target <triple>` for cross-compilation -- then run:
+
+```console
+sarasacw-omrf-packer -m path/to/Cargo.toml
+```
+
+`cargo` and `rustc` are resolved from `PATH`; override them with the environment variables listed in the [Environment Variables](#environment-variables) section.
+
+### Command-line options
+
+| Option | Required | Description |
+|---|---|---|
+| `-m`, `--manifest <CARGO.TOML>` | yes | Path to the `Cargo.toml` of the project to pack. |
+| `-d`, `--dist-dir <DIR>` | no | Directory where the redistributable tree is materialized (`bin/`, `include/`, `lib/`, ...). |
+| `-z`, `--dist-zip <ZIP>` | no | Path of the zip archive produced from the redistributable tree. |
+| `-t`, `--target <TRIPLE>` | no | Target triple to pack for (e.g. `x86_64-pc-windows-msvc`). Defaults to the host toolchain triple. |
+
+`--dist-dir` and `--dist-zip` are independent: pass either, both, or neither. Omitting both performs a dry run that validates the configuration without writing any output. Run `sarasacw-omrf-packer --help` for the authoritative list.
+
 ## Metadata

 All packer used properties are stored in target Rust manifest file as metadata style.
@@ -77,5 +124,7 @@ requires = ["libfoo >= 1.0", "libbar"]

 ## Environment Variables

- `OMRF_PACKER_CARGO`: Path to the `cargo` executable used to collect project metadata. When unset, the packer invokes `cargo` as resolved from `PATH`.
- `OMRF_PACKER_RUSTC`: Path to the `rustc` executable used to resolve the host toolchain triple. When unset, the packer invokes `rustc` as resolved from `PATH`.
+- `OMRF_PACKER_CARGO`: Path to the `cargo` executable used to collect project metadata. 
+When unset, the packer invokes `cargo` as resolved from `PATH`.
+- `OMRF_PACKER_RUSTC`: Path to the `rustc` executable used to resolve the host toolchain triple. 
+When unset, the packer invokes `rustc` as resolved from `PATH`.