From e312a44652f9acfe7cacd164a2789c32e4dfa6c9 Mon Sep 17 00:00:00 2001 From: Luca Barbato Date: Sat, 31 Aug 2024 21:27:59 +0200 Subject: [PATCH 1/6] Add the metadata needed by cargo-c --- libz-rs-sys/Cargo.toml | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/libz-rs-sys/Cargo.toml b/libz-rs-sys/Cargo.toml index 689709aa..18863301 100644 --- a/libz-rs-sys/Cargo.toml +++ b/libz-rs-sys/Cargo.toml @@ -17,6 +17,17 @@ rust-allocator = ["zlib-rs/rust-allocator"] # by default, use the rust global al std = ["zlib-rs/std"] # assume `::std` is available custom-prefix = [] # use the LIBZ_RS_SYS_PREFIX to prefix all exported symbols testing-prefix = [] # prefix all symbols with LIBZ_RS_SYS_TEST_ for testing +capi = [] [dependencies] zlib-rs = { workspace = true, default-features = false } + +[package.metadata.capi.library] +name = "z_rs" + +[package.metadata.capi.header] +enabled = false + +[package.metadata.capi.pkg_config] +name = "libz_rs" +filename = "libz_rs" From 2cf226b91f15ad623de35a0dbdfae0a5679b6822 Mon Sep 17 00:00:00 2001 From: Folkert de Vries Date: Wed, 4 Sep 2024 15:38:46 +0200 Subject: [PATCH 2/6] point `cargo c` to the dylib crate instead --- libz-rs-sys-cdylib/Cargo.toml | 11 ++++++++++ libz-rs-sys-cdylib/README.md | 41 ++++++++++++++++++++++++++++++++--- libz-rs-sys/Cargo.toml | 11 ---------- 3 files changed, 49 insertions(+), 14 deletions(-) diff --git a/libz-rs-sys-cdylib/Cargo.toml b/libz-rs-sys-cdylib/Cargo.toml index be89213b..e3585cff 100644 --- a/libz-rs-sys-cdylib/Cargo.toml +++ b/libz-rs-sys-cdylib/Cargo.toml @@ -19,6 +19,17 @@ default = ["c-allocator"] # when used as a cdylib crate, use the c allocator c-allocator = ["libz-rs-sys/c-allocator"] # by default, use malloc/free for memory allocation rust-allocator = ["libz-rs-sys/rust-allocator", "libz-rs-sys/std"] # by default, use the rust global alloctor for memory allocation custom-prefix = ["libz-rs-sys/custom-prefix"] # use the LIBZ_RS_SYS_PREFIX to prefix all exported symbols +capi = [] [dependencies] libz-rs-sys = { version = "0.4.0", path = "../libz-rs-sys", default-features = false } + +[package.metadata.capi.library] +name = "z_rs" + +[package.metadata.capi.header] +enabled = false + +[package.metadata.capi.pkg_config] +name = "libz_rs" +filename = "libz_rs" diff --git a/libz-rs-sys-cdylib/README.md b/libz-rs-sys-cdylib/README.md index 212efdf9..df1129d9 100644 --- a/libz-rs-sys-cdylib/README.md +++ b/libz-rs-sys-cdylib/README.md @@ -4,6 +4,7 @@ Build `zlib-rs` as a drop-in replacement for the zlib dynamic library ```sh # build the cdylib +# using `cargo build` will work but has limitations, see below cargo build --release # the extension of a cdylib varies per platform @@ -14,8 +15,9 @@ cc zpipe.c target/release/libz_rs.so ``` By default this build uses libc `malloc`/`free` to (de)allocate memory, and only depends on the rust `core` library. +See below for the available feature flags. -## Features +## Feature Flags ### Allocators @@ -74,6 +76,39 @@ the standard library has the following limitations: - CPU feature detection is currently disabled. This is true for both compile-time and run-time feature detection. This means `zlib-rs` will not make use of SIMD or other custom instructions. -- The `rust-allocator` should not be used. It internally enables the standard library, causing issues. Using `c-allocator` - or not providing an allocator at build time is still supported.On embedded it is most common to provide a custom allocator +- The `rust-allocator` should not be used. It internally enables the standard library, causing issues. Using `c-allocator` + or not providing an allocator at build time is still supported.On embedded it is most common to provide a custom allocator that "allocates" into a custom array. + +## Build for Distribution + +A `cargo build` currently does not set some fields that are required or useful when using a dynamic library from C. +For instance, the soname and version are not set by a standard `cargo build`. + +To build a proper, installable dynamic library, we recommend [`cargo-c`](https://github.com/lu-zero/cargo-c): + +``` +cargo install cargo-c +``` + +This tool deals with setting fields (soname, version) that a normal `cargo build` does not set (today). +It's configuration is in the `Cargo.toml`, where e.g. the library name or version can be changed. + +``` +> cargo cbuild --release + Compiling zlib-rs v0.2.1 + Compiling libz-rs-sys v0.2.1 + Compiling libz-rs-sys-cdylib v0.2.1 + Finished `release` profile [optimized] target(s) in 1.86s + Building pkg-config files +> tree target +target +├── CACHEDIR.TAG +└── x86_64-unknown-linux-gnu + └── release + ├── libz_rs.a + ├── libz_rs.d + ├── libz_rs.pc + ├── libz_rs.so + └── libz_rs-uninstalled.pc +``` diff --git a/libz-rs-sys/Cargo.toml b/libz-rs-sys/Cargo.toml index 18863301..689709aa 100644 --- a/libz-rs-sys/Cargo.toml +++ b/libz-rs-sys/Cargo.toml @@ -17,17 +17,6 @@ rust-allocator = ["zlib-rs/rust-allocator"] # by default, use the rust global al std = ["zlib-rs/std"] # assume `::std` is available custom-prefix = [] # use the LIBZ_RS_SYS_PREFIX to prefix all exported symbols testing-prefix = [] # prefix all symbols with LIBZ_RS_SYS_TEST_ for testing -capi = [] [dependencies] zlib-rs = { workspace = true, default-features = false } - -[package.metadata.capi.library] -name = "z_rs" - -[package.metadata.capi.header] -enabled = false - -[package.metadata.capi.pkg_config] -name = "libz_rs" -filename = "libz_rs" From e7fca91dd2eff4cdc76a13015b9806e63a4682ac Mon Sep 17 00:00:00 2001 From: Folkert de Vries Date: Thu, 21 Nov 2024 13:41:49 +0100 Subject: [PATCH 3/6] add CI action for `cargo cbuild` --- .github/workflows/checks.yaml | 41 ++++++++++++++++++++++++++++++++++- 1 file changed, 40 insertions(+), 1 deletion(-) diff --git a/.github/workflows/checks.yaml b/.github/workflows/checks.yaml index 192dc385..bdbe8473 100644 --- a/.github/workflows/checks.yaml +++ b/.github/workflows/checks.yaml @@ -251,7 +251,7 @@ jobs: done link-c-dynamic-library: - name: dynamic library + name: vanilla dynamic library strategy: matrix: include: @@ -304,6 +304,45 @@ jobs: cargo build --release --target ${{matrix.target}} --features=custom-prefix objdump -tT target/${{matrix.target}}/release/deps/libz_rs.so | grep -q "MY_CUSTOM_PREFIX_uncompress" || (echo "symbol not found!" && exit 1) + cargo-c-dynamic-library: + name: cargo-c dynamic library + strategy: + matrix: + include: + - target: x86_64-unknown-linux-gnu + features: + - '' + runs-on: ubuntu-latest + steps: + - name: Checkout sources + uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 + with: + persist-credentials: false + - name: Install rust toolchain + uses: dtolnay/rust-toolchain@be73d7920c329f220ce78e0234b8f96b7ae60248 + with: + toolchain: stable + targets: ${{matrix.target}} + - name: Install cargo-c + env: + LINK: https://github.com/lu-zero/cargo-c/releases/latest/download + run: | + curl -L "$LINK/cargo-c-x86_64-unknown-linux-musl.tar.gz" | + tar xz -C $HOME/.cargo/bin + - name: build with and test the result of cargo-c + working-directory: libz-rs-sys-cdylib + run: | + # build using cargo-c this time + cargo cinstall --offline --release --destdir=/tmp/cargo-cbuild-libz-rs + tree /tmp/cargo-cbuild-libz-rs + # verify that the SONAME is set and includes a version + objdump -p target/x86_64-unknown-linux-gnu/release/libz_rs.so | awk '/SONAME/{print $2}' | grep -E 'libz_rs\.so\.[0-9]+\.[0-9]+' + # build zpipe with our library + cc -o zpipe zpipe.c -L/tmp/cargo-cbuild-libz-rs/usr/local/lib/x86_64-linux-gnu -lz_rs + export LD_LIBRARY_PATH=/tmp/cargo-cbuild-libz-rs/usr/local/lib/x86_64-linux-gnu:$LD_LIBRARY_PATH + ./zpipe < Cargo.toml | ./zpipe -d > out.txt + cmp -s Cargo.toml out.txt + wasm32: name: "wasm32" runs-on: ubuntu-latest From 7723ebc36716a926f0a71acb83dcfa3380d5bb1c Mon Sep 17 00:00:00 2001 From: Folkert de Vries Date: Tue, 26 Nov 2024 11:07:59 +0100 Subject: [PATCH 4/6] pin cargo-c release --- .github/workflows/checks.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/checks.yaml b/.github/workflows/checks.yaml index bdbe8473..6bb4787e 100644 --- a/.github/workflows/checks.yaml +++ b/.github/workflows/checks.yaml @@ -325,7 +325,7 @@ jobs: targets: ${{matrix.target}} - name: Install cargo-c env: - LINK: https://github.com/lu-zero/cargo-c/releases/latest/download + LINK: https://github.com/lu-zero/cargo-c/releases/tag/v0.10.5/download run: | curl -L "$LINK/cargo-c-x86_64-unknown-linux-musl.tar.gz" | tar xz -C $HOME/.cargo/bin From b3ea962a9f91f3e10cb5fe6ecf0858c637ffb1f4 Mon Sep 17 00:00:00 2001 From: Folkert de Vries Date: Tue, 26 Nov 2024 11:07:59 +0100 Subject: [PATCH 5/6] pin cargo-c release --- .github/workflows/checks.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/checks.yaml b/.github/workflows/checks.yaml index 6bb4787e..707f28ee 100644 --- a/.github/workflows/checks.yaml +++ b/.github/workflows/checks.yaml @@ -325,7 +325,7 @@ jobs: targets: ${{matrix.target}} - name: Install cargo-c env: - LINK: https://github.com/lu-zero/cargo-c/releases/tag/v0.10.5/download + LINK: https://github.com/lu-zero/cargo-c/releases/download/v0.10.5 run: | curl -L "$LINK/cargo-c-x86_64-unknown-linux-musl.tar.gz" | tar xz -C $HOME/.cargo/bin From e7d03c7d20730b31b6a51f9c648ba8528524d83e Mon Sep 17 00:00:00 2001 From: Folkert de Vries Date: Tue, 26 Nov 2024 11:30:02 +0100 Subject: [PATCH 6/6] use the zlib (not the rust) version in the SONAME --- .github/workflows/checks.yaml | 2 +- libz-rs-sys-cdylib/Cargo.toml | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/checks.yaml b/.github/workflows/checks.yaml index 707f28ee..323e77c5 100644 --- a/.github/workflows/checks.yaml +++ b/.github/workflows/checks.yaml @@ -336,7 +336,7 @@ jobs: cargo cinstall --offline --release --destdir=/tmp/cargo-cbuild-libz-rs tree /tmp/cargo-cbuild-libz-rs # verify that the SONAME is set and includes a version - objdump -p target/x86_64-unknown-linux-gnu/release/libz_rs.so | awk '/SONAME/{print $2}' | grep -E 'libz_rs\.so\.[0-9]+\.[0-9]+' + objdump -p target/x86_64-unknown-linux-gnu/release/libz_rs.so | awk '/SONAME/{print $2}' | grep -E 'libz_rs\.so\.1' # build zpipe with our library cc -o zpipe zpipe.c -L/tmp/cargo-cbuild-libz-rs/usr/local/lib/x86_64-linux-gnu -lz_rs export LD_LIBRARY_PATH=/tmp/cargo-cbuild-libz-rs/usr/local/lib/x86_64-linux-gnu:$LD_LIBRARY_PATH diff --git a/libz-rs-sys-cdylib/Cargo.toml b/libz-rs-sys-cdylib/Cargo.toml index e3585cff..974ed6b2 100644 --- a/libz-rs-sys-cdylib/Cargo.toml +++ b/libz-rs-sys-cdylib/Cargo.toml @@ -25,6 +25,7 @@ capi = [] libz-rs-sys = { version = "0.4.0", path = "../libz-rs-sys", default-features = false } [package.metadata.capi.library] +version = "1.3.0" # the zlib api version we match name = "z_rs" [package.metadata.capi.header]