sarasacw-omrf/packer/README.md

# 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.
There is an example about how to define them in `Cargo.toml`.

```toml
[package.metadata.omrf]
# Minimum required version of sarasacw-omrf-packer.
# Running with an older version fails with an error.
# This property is optional; when omitted, no version constraint is enforced.
min_version = "1.0.0"

# Header files to distribute. Each entry installs one file (or, with glob
# expansion, a set of files) into the `include` directory of the installation.
# Each entry carries a `from` source path and a `to` destination path.
# This property is required. If you really want to distribute nothing header files,
# leave empty list here.
headers = [
    # `from` is a path relative to the directory that contains this `Cargo.toml`.
    # `to` is a path relative to the `include` directory (a subdirectory of the install directory).
    # An empty `to` places the file directly under the `include` directory.
    { from = "cbindgen/my_crate.h", to = "" },
    { from = "cbindgen/our_crate.h", to = "SomePrefix" },
    # `from` also supports UNIX-style glob (pathname) expansion.
    # The matcher uses the leading literal portion of the pattern (`pattern/with`
    # here) as the root directory and copies every matched file into the `to`
    # directory, preserving the directory hierarchy beneath that root.
    { from = "pattern/with/**/*", to = "" },
    # The same pattern, but nested under an `AllInOne` prefix.
    { from = "pattern/with/**/*", to = "AllInOne" },
]

[package.metadata.omrf.cmake]
# Namespace part of the generated CMake target.
# This property is optional; it defaults to the name of the target Rust project.
namespace_name = "foobar"
# Target-name part of the generated CMake target.
# This property is optional; it defaults to the name of the target Rust project.
target_name = "foobar"
# Declared CMake dependencies.
# Each entry carries a `package` (passed to find_dependency argument) and a `target`
# (linked into the generated imported target via INTERFACE_LINK_LIBRARIES).
# This property is optional; it defaults to no dependencies.
# Because the packer only ever ships dynamic libraries, there are no private or
# static dependencies, and no separate field for them.
# Declaring dependencies here is rarely necessary and is NOT recommended: it
# behaves like a CMake interface/public dependency, and exposing other
# libraries' raw types across the FFI boundary raises ABI-compatibility
# concerns across runtimes. Use it only when this crate is explicitly a wrapper
# around another library.
dependencies = [
    { package = "ZLIB 1.3.2 REQUIRED", target = "ZLIB::ZLIB" },
]

[package.metadata.omrf.pkgconfig]
# The unique identifier of the package.
# This property is optional; it defaults to the name of the target Rust project.
id = "foobar"
# Human-readable name of the package.
# This property is optional; it defaults to the name of the target Rust project.
name = "Foo Bar"
# Brief description of the package.
# This property is optional; it defaults to the description of the target Rust project.
description = "a brown fox jumps over a lazy dog."
# Declared public pkg-config dependencies.
# This property is optional; it defaults to no dependencies.
# Because the packer only ever ships dynamic libraries, there are no private
# dependencies and Requires.private is not used.
# Declaring dependencies here is rarely necessary and is NOT recommended, for
# the same ABI-compatibility reasons as the CMake dependencies above. Use it
# only when this crate is explicitly a wrapper around another library.
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`.