Add the metadata needed by cargo-c

.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/download/v0.10.5
+        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\.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
+          ./zpipe < Cargo.toml | ./zpipe -d > out.txt
+          cmp -s Cargo.toml out.txt
+
   wasm32:
     name: "wasm32"
     runs-on: ubuntu-latest

libz-rs-sys-cdylib/Cargo.toml

@@ -19,6 +19,18 @@ 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]
+version = "1.3.0" # the zlib api version we match
+name = "z_rs"
+
+[package.metadata.capi.header]
+enabled = false
+
+[package.metadata.capi.pkg_config]
+name = "libz_rs"
+filename = "libz_rs"

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
+```