From 0a6c7d931c1bd7023e30302b3085bdf912fe6db1 Mon Sep 17 00:00:00 2001 From: Luca Barbato Date: Sat, 10 Dec 2022 12:00:41 +0100 Subject: [PATCH 1/5] Move the language configuration to cbindgen.toml --- Makefile | 2 +- cbindgen.toml | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 20599d11..0f708639 100644 --- a/Makefile +++ b/Makefile @@ -38,7 +38,7 @@ target: mkdir -p $@ src/rustls.h: src/*.rs cbindgen.toml - cbindgen --lang C > $@ + cbindgen > $@ target/$(PROFILE)/librustls_ffi.a: src/*.rs Cargo.toml RUSTFLAGS="-C metadata=rustls-ffi" ${CARGO} build $(CARGOFLAGS) diff --git a/cbindgen.toml b/cbindgen.toml index 1a1b977a..335688d7 100644 --- a/cbindgen.toml +++ b/cbindgen.toml @@ -1,4 +1,5 @@ include_guard = "RUSTLS_H" +language = "C" usize_is_size_t = true From 713973d289d0963427c82c7feb354dee7ae7908c Mon Sep 17 00:00:00 2001 From: Luca Barbato Date: Sat, 10 Dec 2022 12:29:23 +0100 Subject: [PATCH 2/5] Initial cargo-c support --- Cargo.toml | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/Cargo.toml b/Cargo.toml index c14abdf0..7d5010b8 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -20,6 +20,7 @@ rust-version = "1.61" # libraries. no_log_capture = [] read_buf = ["rustls/read_buf"] +capi = [] [dependencies] # Keep in sync with RUSTLS_CRATE_VERSION in build.rs @@ -36,3 +37,16 @@ crate-type = ["lib", "staticlib"] [dev-dependencies] regex = "1.9.6" + +[package.metadata.capi.header] +name = "rustls" +subdirectory = false + +[package.metadata.capi.library] +name = "rustls" +version_suffix_components = 3 +rustflags = "-Cmetadata=rustls-ffi" + +[package.metadata.capi.pkg_config] +name = "rustls" +filename = "rustls" From 58dd02a4d907569d5f7947d876e3cdde2d5856c0 Mon Sep 17 00:00:00 2001 From: Daniel McCarney Date: Wed, 2 Aug 2023 09:01:51 -0400 Subject: [PATCH 3/5] ci: add task for cargo-c. This will prevent bitrot with the cargo-c support. --- .github/workflows/test.yaml | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml index 3f0eddb5..2ade89ad 100644 --- a/.github/workflows/test.yaml +++ b/.github/workflows/test.yaml @@ -221,6 +221,25 @@ jobs: - name: Clang tidy run: clang-tidy tests/*.c -- -I src/ + cargo-c: + name: cargo-c + runs-on: ubuntu-latest + steps: + - name: Checkout sources + uses: actions/checkout@v3 + with: + persist-credentials: false + - name: Install rust toolchain + uses: dtolnay/rust-toolchain@nightly + - name: Install cargo-c + env: + LINK: https://github.com/lu-zero/cargo-c/releases/latest/download + CARGO_C_FILE: cargo-c-x86_64-unknown-linux-musl.tar.gz + run: | + curl -L $LINK/$CARGO_C_FILE | tar xz -C ~/.cargo/bin + - name: Build and test with cargo-c + run: cargo capi test + miri: name: Miri runs-on: ubuntu-latest From 75b6882745d3b30a9c71e23e4b0b53e92ce024d9 Mon Sep 17 00:00:00 2001 From: Daniel McCarney Date: Tue, 17 Oct 2023 16:00:43 -0400 Subject: [PATCH 4/5] docs: add static vs dynamic docs, cargo-c instructions This commit details our current thinking w.r.t static vs dynamic linking for rustls-ffi. It also adds initial documentation of using `cargo-c` to build a dynamic library. In particular we emphasize that: a) we make **no** ABI stability guarantees b) the dynamic library/cargo-c support is considered experimental --- README.md | 76 ++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 72 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index a7c8527e..d494442b 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,21 @@ to provide the cryptographic primitives. # Build You'll need to [install the Rust toolchain](https://rustup.rs/) (version 1.61 -or above) and a C compiler (`gcc` and `clang` should both work). To build in optimized mode: +or above) and a C compiler (`gcc` and `clang` should both work). + +## Static Library + +In its current for rustls-ffi's `Makefile` infrastructure will generate a static +system library (e.g. `--crate-type=staticlib`), producing a `.a` or `.lib` file +(depending on the OS). + +We recommend using rustls-ffi as a static library as we make no guarantees of +[ABI](https://en.wikipedia.org/wiki/Application_binary_interface) stability across +versions at this time, and dynamic library support is considered **experimental**. + +### Building a Static Library + +To build a static library in optimized mode: make @@ -28,15 +42,15 @@ To install in `/usr/local/`: sudo make install -To build in debug mode: +To build a static library in debug mode: make PROFILE=debug -To link against the resulting library, on **Linux**: +To link against the resulting static library, on **Linux**: -lrustls -lgcc_s -lutil -lrt -lpthread -lm -ldl -lc -To link against the resulting library, on **macOS**: +To link against the resulting static library, on **macOS**: -lrustls -framework Security -liconv -lSystem -lc -l @@ -45,6 +59,60 @@ via](https://doc.rust-lang.org/rustc/command-line-arguments.html#--print-print-c RUSTFLAGS="--print native-static-libs" cargo build +## Dynamic Library + +Using rustls-ffi as a static library has some downsides. Notably each application +that links the static library will need to be rebuilt for each update to rustls-ffi, +and duplicated copies of rustls-ffi will be included in each application. + +Building rustls-ffi as a dynamic library (`--crate-type=cdylib`) can resolve these +issues, however this approach comes with its own trade-offs. We currently consider +this option **experimental**. + +### ABI Stability + +At this time rustls-ffi makes **no** guarantees about +[ABI](https://en.wikipedia.org/wiki/Application_binary_interface) stability. +Each release of rustls-ffi may introduce breaking changes to the ABI and so +the built library should use the exact rustls-ffi version as the dynamic library +[SONAME](https://en.wikipedia.org/wiki/Soname). + +### Building a Dynamic Library + +Since building a useful dynamic library is more complex than building a static +library, rustls-ffi uses [cargo-ci](https://github.com/lu-zero/cargo-c) in place +of the `Makefile` system used for the static library. + +This takes care of: +* Generating the `rustls.h` header file. +* Building a `.so` or `.dylib` file (depending on the OS). +* Generating a [pkg-config](https://www.freedesktop.org/wiki/Software/pkg-config/) `.pc` file. +* Installing the library and header files in the appropriate location. + +If your operating system doesn't package `cargo-c` natively +(see [package availability](https://github.com/lu-zero/cargo-c#availability)), +you can install it with: + + cargo install cargo-c + +To build a dynamic library in optimized mode: + + cargo capi build --release + +To install in `/usr/local/`: + + sudo cargo capi install + +To build a static library in debug mode: + + cargo capi build + +To link against the resulting dynamic library, use `pkg-config` to populate your +`LDLIBS` and `CFLAGS` as appropriate: + + pkg-config --libs rustls + pkg-config --cflags rustls + # Overview Rustls doesn't do any I/O on its own. It provides the protocol handling, and From 761c544b51c50dd0c60fdbd8334d7b72e0acd77c Mon Sep 17 00:00:00 2001 From: Jacob Hoffman-Andrews Date: Fri, 8 Mar 2024 12:09:37 -0800 Subject: [PATCH 5/5] README nits --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index d494442b..d114ebd7 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ or above) and a C compiler (`gcc` and `clang` should both work). ## Static Library -In its current for rustls-ffi's `Makefile` infrastructure will generate a static +In its current form rustls-ffi's `Makefile` infrastructure will generate a static system library (e.g. `--crate-type=staticlib`), producing a `.a` or `.lib` file (depending on the OS). @@ -110,8 +110,8 @@ To build a static library in debug mode: To link against the resulting dynamic library, use `pkg-config` to populate your `LDLIBS` and `CFLAGS` as appropriate: - pkg-config --libs rustls - pkg-config --cflags rustls + LDLIBS="$(pkg-config --libs rustls)" + CFLAGS="$(pkg-config --cflags rustls)" # Overview