Revision control
Copy as Markdown
Other Tools
= Prebuilt tarball layout spec
This document is the contract that every prebuilt static-library
tarball shipped from a librnp GitHub release must satisfy. It is the
input to `ci/test_prebuilt.sh`, which mechanically asserts every
requirement below.
== Naming
Tarball filename:
----
rnp-v<version>-<target>-<backend>.tar.gz
----
Where:
* `<version>` is the librnp release tag, including the leading `v`
(e.g. `v0.18.1`). For PR-review runs the placeholder
`v0.0.0-pr-test` is used.
* `<target>` is a Rust-style target triple from the matrix in
`.github/workflows/prebuilt.yml` (e.g.
`x86_64-unknown-linux-gnu`, `aarch64-apple-darwin`).
* `<backend>` is one of `botan` or `openssl`.
A sidecar `<filename>.sha256` MUST accompany every tarball. It uses
the `sha256sum -c` format:
----
<64 hex chars> <filename>
----
When GPG signing is configured (via the `RNP_RELEASE_GPG_KEY`
repository secret), a detached signature `<filename>.asc` MUST also
accompany every tarball.
== Top-level layout
The tarball extracts to a single top-level directory whose name
matches the tarball filename without `.tar.gz`:
----
rnp-v<version>-<target>-<backend>/
├── include/ # required
├── lib/ # required
├── MANIFEST.txt # required
└── MANIFEST.txt.asc # optional; only when GPG signing is configured
----
== `include/`
Required subdirectories:
* `rnp/` -- the public librnp FFI headers. MUST contain at least:
** `rnp.h`
** `rnp_err.h`
** `rnp_export.h`
** `rnp_ver.h`
* `botan-3/` (botan backend) or `openssl/` (openssl backend)
* `bzlib.h` (bzip2)
* `zlib.h` (zlib)
* `zconf.h` (zlib internal)
== `lib/`
Required static archives are declared per-backend in
`ci/backends/<name>.env` (`BACKEND_LIB_NAMES`). The file extension
(`.a` or `.lib`) comes from `ci/targets/<triple>.env`
(`TARGET_ARCHIVE_EXT`). Both are read at build time and at test time
from the same source of truth.
Required subdirectories:
* `cmake/rnp/` -- CMake config files. MUST contain at least:
** `rnp-config.cmake`
** `rnp-config-version.cmake`
** `rnp-targets.cmake`
* `pkgconfig/` -- pkg-config files. MUST contain at least:
** `librnp.pc`
== `lib/pkgconfig/librnp.pc`
Must use `${pcfiledir}` (not absolute build paths) for all
prefix-relative variables. After unpacking the tarball to any
location, the following must succeed from a clean environment:
----
PKG_CONFIG_PATH=<bundle>/lib/pkgconfig pkg-config --cflags --static librnp
PKG_CONFIG_PATH=<bundle>/lib/pkgconfig pkg-config --libs --static librnp
----
The output must NOT contain any path under `/tmp/`, `/home/`,
`/Users/`, `D:\a\`, or any other build-host-specific prefix.
== `MANIFEST.txt`
Human-readable, must contain:
* Target triple matching the filename.
* Backend matching the filename.
* Build host description (OS + arch).
* A list of all directories/files in the tarball.
* The link libraries required, in link order, for the target platform.
Authoritative values come from `ci/backends/<name>.env`
(`BACKEND_LINK_LIBS`) and `ci/targets/<triple>.env`
(`TARGET_PLATFORM_LINK`).
* Source attribution (repo URL).
* Dependency versions used.
== Configuration files (single source of truth)
The link flags, required archives, archive extension, platform link
flags, CMake flags, and header directories are declared in:
* `ci/backends/<name>.env` -- per-backend properties.
* `ci/targets/<triple>.env` -- per-target properties.
* `ci/prebuilt-versions.env` -- pinned dep versions.
The build script (`ci/build_prebuilt.sh`), the PowerShell build script
(`ci/build_prebuilt.ps1`), and the validator (`ci/test_prebuilt.sh`)
all read from these files. They cannot drift because there is exactly
one source of truth per property.
See link:backends.adoc[Backends policy] and
link:target-matrix.adoc[Target matrix policy] for the contracts each
config file must satisfy.
== Linkability
A minimal C program:
[source,c]
----
#include <rnp/rnp.h>
#include <rnp/rnp_err.h>
int main(void) {
rnp_ffi_t ffi = NULL;
rnp_result_t r = rnp_ffi_create(&ffi, "GPG", "GPG");
if (r != RNP_SUCCESS) return 1;
rnp_ffi_destroy(ffi);
return 0;
}
----
Must compile, link, and run successfully against the tarball, using
only the headers in `include/` and the static archives in `lib/`,
plus the standard system runtime libraries (`-lc++` on macOS,
`-lpthread -ldl` on Linux, MSVC runtime on Windows).
== Out of scope
The following are explicitly NOT part of this spec:
Reproducibility (byte-identical output across runs) is documented
separately in `docs/packaging.adoc` ("Reproducibility" section) and is
best-effort. A `reproducibility-check` CI job on every PR reports the
diff via `ci/check_reproducibility.sh`. It is NOT asserted by
`ci/test_prebuilt.sh`.
* Cross-platform ABI compatibility (Linux tarball links on macOS).
Each target is self-contained; cross-target compatibility is the
consumer's responsibility.
* sexpp public headers. sexpp is a transitive link-time dependency
only; its headers are not in the tarball because librnp's C API
is pure C. C++ consumers that use rnp's internal C++ API
additionally need sexpp's headers from a separate installation.