capi: make opt-in via 'capi' feature

There's no need to include the capi code for Rust crates. This also
matches what cargo-c does, so we can easily switch without too many
changes, though for now we can just keep using our own scripts.

Part of making this opt-in means we only add the cdylib and staticlib
crate types if building with that feature enabled.

Signed-off-by: Aleksa Sarai <cyphar@cyphar.com>

Cargo.toml

@@ -31,12 +31,13 @@ rust-version = "1.63"
 
 [badges]
 maintenance = { status = "experimental" }
-travis-ci = { repository = "openSUSE/libpathrs" }
 
 [lib]
-crate-type = ["rlib", "cdylib", "staticlib"]
+# When building the CAPI, our Makefile adds --crate-type={cdylib,staticlib}.
+crate-type = ["rlib"]
 
 [features]
+capi = ["dep:rand"]
 # Only used for tests.
 _test_as_root = []
 
@@ -55,7 +56,7 @@ itertools = "^0.13"
 lazy_static = "^1"
 libc = "^0.2"
 memchr = "^2"
-rand = "^0.8"
+rand = { version = "^0.8", optional = true }
 # MSRV(1.65): Use regex >= 1.10.
 regex = "1.9.*"
 rustix = { version = "^0.38", features = ["fs"] }
@@ -72,5 +73,9 @@ pretty_assertions = "^1"
 rustix = { version = "^0.38", features = ["process"] }
 
 [lints.rust]
-# We have special handling for coverage runs (which set cfg(coverage)).
-unexpected_cfgs = { level = "warn", check-cfg = ['cfg(coverage)'] }
+unexpected_cfgs = { level = "warn", check-cfg = [
+	# We have special handling for coverage runs (which set cfg(coverage)).
+	'cfg(coverage)',
+	# We set these cfgs when building with --features=capi.
+	'cfg(cdylib)', 'cfg(staticlib)'
+] }

Makefile

@@ -19,17 +19,26 @@ CARGO_NIGHTLY ?= cargo +nightly
 
 SRC_FILES = $(shell find . -name '*.rs')
 
+.DEFAULT: debug
 .PHONY: debug
 debug: target/debug
 
 target/debug: $(SRC_FILES)
-	$(CARGO) build
+	# For some reason, --crate-types needs separate invocations. We can't use
+	# #![crate_type] unfortunately, as using it with #![cfg_attr] has been
+	# deprecated. <https://github.com/rust-lang/rust/issues/91632>
+	$(CARGO) rustc --features=capi --crate-type=cdylib
+	$(CARGO) rustc --features=capi --crate-type=staticlib
 
 .PHONY: release
 release: target/release
 
 target/release: $(SRC_FILES)
-	$(CARGO) build --release
+	# For some reason, --crate-types needs separate invocations. We can't use
+	# #![crate_type] unfortunately, as using it with #![cfg_attr] has been
+	# deprecated. <https://github.com/rust-lang/rust/issues/91632>
+	$(CARGO) rustc --features=capi --crate-type=cdylib --release
+	$(CARGO) rustc --features=capi --crate-type=staticlib --release
 
 .PHONY: smoke-test
 smoke-test:
@@ -78,7 +87,7 @@ test: test-rust
 
 .PHONY: docs
 docs:
-	$(CARGO) doc --document-private-items --open
+	$(CARGO) doc --all-features --document-private-items --open
 
 .PHONY: install
 install: release

build.rs

@@ -20,11 +20,15 @@
 use std::env;
 
 fn main() {
-    // Add DT_SONAME to our cdylibs.
-    let name = "pathrs";
-    let major = env::var("CARGO_PKG_VERSION_MAJOR").unwrap();
-    println!(
-        "cargo:rustc-cdylib-link-arg=-Wl,-soname,lib{}.so.{}",
-        name, major
-    );
+    // Add DT_SONAME to our cdylibs. We can't check the crate-type here
+    // directly, but we can at least avoid needless warnings for "cargo build"
+    // by only emitting this when the capi feature is enabled.
+    if cfg!(feature = "capi") {
+        let name = "pathrs";
+        let major = env::var("CARGO_PKG_VERSION_MAJOR").unwrap();
+        println!(
+            "cargo:rustc-cdylib-link-arg=-Wl,-soname,lib{}.so.{}",
+            name, major
+        );
+    }
 }

install.sh

@@ -136,6 +136,12 @@ includedir="${includedir:-$prefix/include}"
 libdir="${libdir:-$(find_libdir "$exec_prefix")}"
 pkgconfigdir="${pkgconfigdir:-$libdir/pkgconfig}"
 
+# TODO: These flags come from RUSTFLAGS="--print=native-static-libs".
+# Unfortunately, getting this information from cargo is incredibly unergonomic
+# and will hopefully be fixed at some point.
+# <https://github.com/rust-lang/rust/pull/43067#issuecomment-330625316>
+native_static_libs="-lgcc_s -lutil -lrt -lpthread -lm -ldl -lc"
+
 echo "[pkg-config] generating pathrs pkg-config"
 cat >"pathrs.pc" <<EOF
 # libpathrs: safe path resolution on Linux
@@ -165,6 +171,7 @@ Description: Safe path resolution library for Linux
 URL: https://github.com/openSUSE/libpathrs
 Cflags: -I\${includedir}
 Libs: -L\${libdir} -lpathrs
+Libs.private: $native_static_libs
 EOF
 
 echo "[install] installing libpathrs into DESTDIR=${DESTDIR:-/}"

src/capi/mod.rs

@@ -20,10 +20,6 @@
 // We need to permit unsafe code because we are exposing C APIs over FFI and
 // thus need to interact with C callers.
 #![allow(unsafe_code)]
-// None of this code is reachable from rust, so including it in coverage doesn't
-// make sense.
-// TODO: We might want to test the cffi bindings from Rust at some point?
-#![cfg_attr(coverage, coverage(off))]
 
 /// Core pathrs function wrappers.
 pub mod core;

src/error.rs

@@ -56,6 +56,7 @@ impl Error {
 
 #[derive(thiserror::Error, Debug)]
 pub(crate) enum ErrorImpl {
+    #[allow(dead_code)]
     #[error("feature {feature} is not implemented")]
     NotImplemented { feature: Cow<'static, str> },
 

src/lib.rs

@@ -156,6 +156,7 @@ pub use resolvers::{Resolver, ResolverBackend};
 pub mod procfs;
 
 // C API.
+#[cfg(feature = "capi")]
 mod capi;
 
 // Internally used helpers.