= Consuming librnp in downstream projects

This document describes how to use `librnp` — the RNP OpenPGP library — as a
dependency of your own project: via CMake `find_package`, via pkg-config, via
a package manager, or by embedding the sources.

The public C API is declared in `include/rnp/rnp.h`, which is installed as
`<prefix>/include/rnp/rnp.h` together with `rnp_err.h`, `rnp_export.h` and
`rnp_ver.h`. See link:c-usage.adoc[C API usage] for an introduction.

== Choosing a crypto backend

librnp is built against one crypto backend, selected at build time with
`-DCRYPTO_BACKEND=`:

* `botan` (default) — Botan 2.14 or later; use `botan3` to require Botan 3.x.
  Supports all features.
* `openssl` — OpenSSL 1.1.1 or later. Some features are unsupported with this
  backend: SM2, Twofish, crypto-refresh (v6) support and PQC.

The backend choice is recorded in the installed CMake and pkg-config files,
so consumers automatically get the matching dependency (Botan or OpenSSL).

== Shared vs static

By default (`-DBUILD_SHARED_LIBS=ON`, the common case for packaged
installations) librnp is installed as a shared library and linking
`rnp::librnp` (CMake) or `-lrnp` (pkg-config/manual) is all a consumer needs.

With `-DBUILD_SHARED_LIBS=OFF` a static `librnp.a` is installed, and
consumers must also link the transitive dependencies (the crypto backend,
zlib, bzip2 and sexpp). With CMake this happens automatically — see
below. A static librnp built with the bundled sexpp sources installs
`libsexpp.a` next to it and exports it as `rnp::sexpp`, so no separate sexpp
installation is needed (unless rnp was built with `-DSYSTEM_LIBSEXPP=ON`, in
which case the sexpp package is required at consume time).

Note that librnp is written in C++. When linking the *static* library from a
C project, the C++ runtime must be linked as well: with CMake enable the CXX
language in your project, with manual flags link via the C++ compiler driver
or add the C++ standard library explicitly (`-lc++` or `-lstdc++`).

== CMake find_package

The installed CMake package (`<prefix>/lib/cmake/rnp/rnp-config.cmake`)
resolves all transitive dependencies via `find_dependency()` and provides
the imported target `rnp::librnp`:

[source,cmake]
--
cmake_minimum_required(VERSION 3.18)
# CXX is only needed to link a static librnp (see above)
project(example C CXX)

find_package(rnp REQUIRED)

add_executable(example main.c)
target_link_libraries(example PRIVATE rnp::librnp)
--

If rnp or its dependencies are installed in non-standard prefixes, list them
in `CMAKE_PREFIX_PATH`:

[source,console]
--
cmake -B build -DCMAKE_PREFIX_PATH="/opt/rnp;/opt/botan"
--

== pkg-config

A pkg-config file is installed as `<prefix>/lib/pkgconfig/librnp.pc`:

[source,console]
--
export PKG_CONFIG_PATH=/opt/rnp/lib/pkgconfig
cc $(pkg-config --cflags librnp) main.c $(pkg-config --libs librnp) -o example
--

For a static librnp, use `--static` to also get the private dependencies and
link with the C++ driver:

[source,console]
--
cc $(pkg-config --cflags librnp) -c main.c
c++ main.o $(pkg-config --libs --static librnp) -o example
--

== vcpkg

A vcpkg port for rnp is being prepared. Until it lands, install rnp from
source and consume it via `find_package(rnp)` or pkg-config as described
above — with vcpkg's CMake toolchain, adding the rnp installation prefix to
`CMAKE_PREFIX_PATH` is enough for `find_package(rnp)` to work.

== Prebuilt static libraries (release assets)

Each librnp GitHub release ships per-target static-library tarballs alongside
the source tarball. Each tarball bundles `librnp.a` plus a curated static
build of every transitive dependency (sexpp, Botan or OpenSSL, zlib,
bzip2), so downstream consumers can link against librnp without compiling
the C++ + Botan stack from source and without any system package
dependencies.

This is intended for build systems that cannot reach a system package
manager — Cargo `--features vendored`, embedded cross-compile targets,
Windows app vendors, and CI pipelines that pin a specific librnp version.
For conventional Linux distro consumers, the system packages described
above remain the recommended path.

=== Asset naming

Each tarball follows the convention:

----
rnp-v<version>-<target>-<backend>.tar.gz
rnp-v<version>-<target>-<backend>.sha256
----

For example:

----
rnp-v0.18.1-x86_64-unknown-linux-gnu-botan.tar.gz
rnp-v0.18.1-aarch64-apple-darwin-openssl.tar.gz
----

=== Available targets

[cols="2,1,1,2", options="header"]
|===
| Target triple | Backend(s) | CI runner | Notes

| `x86_64-unknown-linux-gnu`  | botan, openssl | `ubuntu-latest`     | glibc; broadest Linux compatibility
| `aarch64-unknown-linux-gnu` | botan, openssl | `ubuntu-24.04-arm`  | glibc ARM64
| `x86_64-unknown-linux-musl` | botan, openssl | `ubuntu-latest` (alpine container) | static libc; Alpine / Docker
| `aarch64-unknown-linux-musl`| botan, openssl | `ubuntu-24.04-arm` (alpine container) | static libc ARM64
| `aarch64-apple-darwin`      | botan, openssl | `macos-14`          | Apple Silicon; `MACOSX_DEPLOYMENT_TARGET=12.0`
| `x86_64-pc-windows-msvc`    | openssl        | `windows-latest`    | MSVC 2022, `/MT` static runtime, via vcpkg
|===

11 tarballs per release. Windows + botan is not currently shipped: vcpkg's botan port for the x64-windows-static triplet declares the C FFI symbols with `__declspec(dllimport)`, so the MSVC linker emits unresolved `__imp_botan_*` externals when rnp links statically. Fixing it needs an upstream vcpkg port change or a from-source Botan build on Windows; tracked as follow-up.

=== Tarball layout

----
include/
  rnp/             public FFI headers (rnp.h, rnp_err.h, rnp_export.h, rnp_ver.h)
  botan-3/         (botan backend) or openssl/ (openssl backend)
  bzlib.h
  zlib.h
lib/
  librnp.a
  libsexpp.a
  libbotan-3.a     (botan backend) or libcrypto.a + libssl.a (openssl backend)
  libz.a
  libbz2.a
  cmake/rnp/       CMake config (find_package(rnp))
  pkgconfig/       pkg-config files
MANIFEST.txt       human-readable summary, dependency versions, link flags
----

NOTE: sexpp's headers are not included in the tarball. They are not needed
by C API consumers (the public rnp FFI is pure C). C++ consumers that use
rnp's internal C++ API additionally need sexpp's headers from a separate
sexpp installation.

=== Consuming a prebuilt tarball

Extract the tarball anywhere on disk and point your build system at the
`include/` and `lib/` directories.

CMake:

[source,cmake]
--
cmake_minimum_required(VERSION 3.18)
project(example C CXX)

# Unpack the tarball to /opt/rnp-prebuilt, then:
set(rnp_PREBUILT_DIR /opt/rnp-prebuilt CACHE PATH "Path to rnp prebuilt bundle")
list(APPEND CMAKE_PREFIX_PATH "${rnp_PREBUILT_DIR}")

find_package(rnp REQUIRED)

add_executable(example main.c)
target_link_libraries(example PRIVATE rnp::librnp)
--

Or with raw compiler flags (see `MANIFEST.txt` inside the tarball for the
exact list, since it depends on backend and target):

[source,console]
----
tar xzf rnp-v0.18.1-aarch64-apple-darwin-botan.tar.gz
cc -I rnp-v0.18.1-aarch64-apple-darwin-botan/include \
   -L rnp-v0.18.1-aarch64-apple-darwin-botan/lib \
   main.c -o example \
   -lrnp -lsexpp -lbotan-3 -lz -lbz2 \
   -lc++ -framework Security -framework CoreFoundation
----

=== Verifying integrity

Each tarball ships with a `.sha256` sidecar:

[source,console]
----
sha256sum -c rnp-v0.18.1-x86_64-unknown-linux-gnu-botan.sha256
----

When the project's release signing key is configured in CI (via the
`RNP_RELEASE_GPG_KEY` and `RNP_RELEASE_GPG_PASSPHRASE` repository
secrets), each tarball also ships with a `.asc` detached signature.
Verify with the project's published signing key fingerprint:

[source,console]
----
gpg --verify rnp-v0.18.1-x86_64-unknown-linux-gnu-botan.tar.gz.asc \
             rnp-v0.18.1-x86_64-unknown-linux-gnu-botan.tar.gz
----

Tarballs without a sidecar `.asc` were published before signing was
configured; rely on the `.sha256` instead.

=== Reproducibility

The tarball contents are reproducible to the extent the underlying
compilers and libc allow:

* `SOURCE_DATE_EPOCH=0` is exported for every dependency build, so
  tools that embed build timestamps (gzip header, libtool archives,
  Python bytecode) produce identical output across runs on the same
  platform.
* The gzip wrapper header is normalized via `GZIP=-n`.

Two known sources of non-reproducibility remain:

* `.a` archive members retain their per-object mtime, which `ar`
  embeds in the archive index. GNU `ar -D` (deterministic mode) would
  fix this; wiring it through CMake across every dep is follow-up.
* Compiled object files embed the absolute build path in some debug
  info sections. `-ffile-prefix-map=$WORK=.` would fix this; same
  follow-up scope.

Cross-platform reproducibility (Linux build == macOS build) is not
achievable since the binary contents differ by definition.

=== How the tarballs are built

The build is driven by two scripts:

* `ci/build_prebuilt.sh` — Linux glibc, Linux musl, macOS. Downloads
  pinned versions of each dependency (zlib, bzip2, Botan or
  OpenSSL), builds them as static libraries into a temporary prefix,
  builds librnp against that prefix, and stages the resulting headers
  and archives into the tarball layout shown above.
* `ci/build_prebuilt.ps1` — Windows MSVC. Uses vcpkg's
  `x64-windows-static` triplet to install the dependency stack, then
  builds librnp against it via CMake.

The matrix itself lives in `.github/workflows/prebuilt.yml`, a
reusable workflow with three triggers:

* `pull_request` — runs on PRs touching `ci/build_prebuilt.*` or
  the workflow itself, so changes to the static-build machinery get
  end-to-end validation before merge. Uploads the resulting tarballs
  as workflow artifacts (downloadable from the PR checks page under
  the `prebuilt-<target>-<backend>` artifact name) instead of
  attaching to a release.
* `workflow_call` — invoked by `release.yml` after the source tarball
  is published. Attaches the resulting tarballs to the release.
* `workflow_dispatch` — manual run against an existing release tag,
  for re-building prebuilts for an older release without re-pushing
  the tag.

The Botan module set (Linux/macOS) is in `ci/botan3-pqc-modules`.

== Embedding the sources

rnp can also be built as part of your own CMake project with
`add_subdirectory`:

[source,cmake]
--
add_subdirectory(rnp)
target_link_libraries(example PRIVATE librnp)
--

sexpp (a required dependency) can be provided in two ways:

* bundled: clone rnp with `--recurse-submodules` or run
  `git submodule update --init` — the `src/libsexpp` submodule is then built
  together with librnp and nothing else is needed;
* system-wide: configure rnp with `-DSYSTEM_LIBSEXPP=ON` to use an installed
  sexpp (0.8.7 or later). The sexpp CMake package (target `sexpp::sexpp`,
  available since sexpp 0.9.1) is preferred, with a pkg-config fallback for
  older installations.

== Smoke test

The script `ci/tests/downstream-consumer.sh` builds and installs rnp (shared
and static) and compiles a minimal consumer program against each
installation in all three ways described above (CMake `find_package`,
pkg-config and raw compiler flags). It can be used to verify a local
installation end to end.