131 lines
6.2 KiB
Markdown
131 lines
6.2 KiB
Markdown
# 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`.
|