Introduce capi crate

This change moves all C API functionality into the capi crate in the
existing workspace.

Closes: libbpf#344

Signed-off-by: Daniel Müller <[email protected]>

.github/workflows/test.yml

@@ -117,7 +117,7 @@ jobs:
         RUSTFLAGS: "-Zsanitizer=${{ matrix.sanitizer }}"
         ASAN_OPTIONS: "detect_odr_violation=0:detect_leaks=0"
         LSAN_OPTIONS: ""
-      run: cargo test --lib --tests --target x86_64-unknown-linux-gnu
+      run: cargo test --workspace --lib --tests --target x86_64-unknown-linux-gnu
   test-release:
     name: Test with release build
     runs-on: ubuntu-22.04
@@ -162,7 +162,7 @@ jobs:
         toolchain: stable
         profile: minimal
         override: true
-    - run: cargo check --workspace --features=generate-c-header
+    - run: cargo check --package=cblazesym --features=generate-c-header
     - name: Check that C header is up-to-date
       run: git diff --exit-code ||
              (echo "!!!! CHECKED IN C HEADER IS OUTDATED !!!!" && false)

Cargo.toml

@@ -1,6 +1,7 @@
 [workspace]
 members = [
   ".",
+  "capi",
   "cli",
 ]
 
@@ -33,10 +34,6 @@ autobenches = false
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
-[lib]
-name = "blazesym"
-crate-type = ["lib", "cdylib", "staticlib"]
-
 [features]
 default = ["backtrace", "demangle", "dwarf"]
 # Enable this feature to compile in support for capturing backtraces in errors.
@@ -47,11 +44,6 @@ backtrace = []
 dwarf = ["gimli"]
 # Enable this feature to get transparent symbol demangling.
 demangle = ["cpp_demangle", "rustc-demangle"]
-# Enable this feature to re-generate the library's C header file. An
-# up-to-date version of this header should already be available in the
-# include/ directory, so this feature is only necessary when APIs are
-# changed.
-generate-c-header = ["cbindgen", "which"]
 # Enable this feature to opt in to the generation of unit test files.
 # Having these test files created is necessary for running tests.
 generate-unit-test-files = ["xz2", "zip"]
@@ -96,9 +88,7 @@ test-log = {version = "0.2", default-features = false, features = ["trace"]}
 tracing-subscriber = {version = "0.3", default-features = false, features = ["env-filter", "fmt"]}
 
 [build-dependencies]
-cbindgen = {version = "0.26", optional = true}
 libc = "0.2.137"
 reqwest = {version = "0.11.18", optional = true, features = ["blocking"]}
 xz2 = {version = "0.1.7", optional = true}
-which = {version = "5.0.0", optional = true}
 zip = {version = "0.6.4", optional = true, default-features = false}

capi/.cargo

@@ -0,0 +1 @@
+../.cargo

capi/Cargo.toml

@@ -0,0 +1,33 @@
+[package]
+name = "cblazesym"
+version = "0.0.0"
+edition = "2021"
+rust-version = "1.64"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[lib]
+name = "cblazesym"
+# `lib` is necessary for end-to-end tests.
+crate-type = ["lib", "cdylib", "staticlib"]
+
+[features]
+# Enable this feature to re-generate the library's C header file. An
+# up-to-date version of this header should already be available in the
+# include/ directory, so this feature is only necessary when APIs are
+# changed.
+generate-c-header = ["cbindgen", "which"]
+
+[build-dependencies]
+cbindgen = {version = "0.26", optional = true}
+which = {version = "5.0.0", optional = true}
+
+[dependencies]
+# Pinned, because we use #[doc(hidden)] APIs.
+blazesym = {version = "=0.2.0-alpha.8", path = "../"}
+libc = "0.2.137"
+
+[dev-dependencies]
+env_logger = "0.10"
+test-log = {version = "0.2.13", default-features = false, features = ["trace"]}
+tracing-subscriber = {version = "0.3", default-features = false, features = ["env-filter", "fmt"]}

capi/build.rs

@@ -0,0 +1,170 @@
+#![allow(clippy::let_unit_value)]
+
+use std::env;
+use std::ffi::OsStr;
+use std::io::Error;
+use std::io::ErrorKind;
+use std::io::Result;
+use std::ops::Deref as _;
+use std::path::Path;
+use std::process::Command;
+use std::process::Stdio;
+
+
+/// Format a command with the given list of arguments as a string.
+fn format_command<C, A, S>(command: C, args: A) -> String
+where
+    C: AsRef<OsStr>,
+    A: IntoIterator<Item = S>,
+    S: AsRef<OsStr>,
+{
+    args.into_iter().fold(
+        command.as_ref().to_string_lossy().into_owned(),
+        |mut cmd, arg| {
+            cmd += " ";
+            cmd += arg.as_ref().to_string_lossy().deref();
+            cmd
+        },
+    )
+}
+
+/// Run a command with the provided arguments.
+fn run<C, A, S>(command: C, args: A) -> Result<()>
+where
+    C: AsRef<OsStr>,
+    A: IntoIterator<Item = S> + Clone,
+    S: AsRef<OsStr>,
+{
+    let instance = Command::new(command.as_ref())
+        .stdin(Stdio::null())
+        .stdout(Stdio::null())
+        .env_clear()
+        .envs(env::vars().filter(|(k, _)| k == "PATH"))
+        .args(args.clone())
+        .output()
+        .map_err(|err| {
+            Error::new(
+                ErrorKind::Other,
+                format!(
+                    "failed to run `{}`: {err}",
+                    format_command(command.as_ref(), args.clone())
+                ),
+            )
+        })?;
+
+    if !instance.status.success() {
+        let code = if let Some(code) = instance.status.code() {
+            format!(" ({code})")
+        } else {
+            " (terminated by signal)".to_string()
+        };
+
+        let stderr = String::from_utf8_lossy(&instance.stderr);
+        let stderr = stderr.trim_end();
+        let stderr = if !stderr.is_empty() {
+            format!(": {stderr}")
+        } else {
+            String::new()
+        };
+
+        Err(Error::new(
+            ErrorKind::Other,
+            format!(
+                "`{}` reported non-zero exit-status{code}{stderr}",
+                format_command(command, args)
+            ),
+        ))
+    } else {
+        Ok(())
+    }
+}
+
+/// Compile `src` into `dst` using the provided compiler.
+fn compile(compiler: &str, src: &Path, dst: &str, options: &[&str]) {
+    let dst = src.with_file_name(dst);
+    println!("cargo:rerun-if-changed={}", src.display());
+    println!("cargo:rerun-if-changed={}", dst.display());
+
+    let () = run(
+        compiler,
+        options
+            .iter()
+            .map(OsStr::new)
+            .chain([src.as_os_str(), "-o".as_ref(), dst.as_os_str()]),
+    )
+    .unwrap_or_else(|err| panic!("failed to run `{compiler}`: {err}"));
+}
+
+/// Compile `src` into `dst` using `cc`.
+#[cfg_attr(not(feature = "generate-c-header"), allow(dead_code))]
+fn cc(src: &Path, dst: &str, options: &[&str]) {
+    compile("cc", src, dst, options)
+}
+
+fn main() {
+    #[cfg(feature = "generate-c-header")]
+    {
+        use std::fs::copy;
+        use std::fs::write;
+
+        let crate_dir = env!("CARGO_MANIFEST_DIR");
+
+        cbindgen::Builder::new()
+            .with_crate(crate_dir)
+            .with_config(cbindgen::Config::from_root_or_default(crate_dir))
+            .generate()
+            .expect("Unable to generate bindings")
+            .write_to_file(Path::new(crate_dir).join("include").join("blazesym.h"));
+
+        // Generate a C program that just included blazesym.h as a basic
+        // smoke test that cbindgen didn't screw up completely.
+        let out_dir = env::var_os("OUT_DIR").unwrap();
+        let out_dir = Path::new(&out_dir);
+        let blaze_src_c = out_dir.join("blazesym.c");
+        let () = write(
+            &blaze_src_c,
+            r#"
+#include <blazesym.h>
+
+int main() {
+  return 0;
+}
+"#,
+        )
+        .unwrap();
+
+        let blaze_src_cxx = out_dir.join("blazesym.cpp");
+        let _bytes = copy(&blaze_src_c, &blaze_src_cxx).expect("failed to copy file");
+
+        cc(
+            &blaze_src_c,
+            "blazesym.bin",
+            &[
+                "-Wall",
+                "-Wextra",
+                "-Werror",
+                "-I",
+                Path::new(crate_dir).join("include").to_str().unwrap(),
+            ],
+        );
+
+        // Best-effort check that C++ can compile the thing as well. Hopefully
+        // all flags are supported...
+        for cxx in ["clang++", "g++"] {
+            if which::which(cxx).is_ok() {
+                compile(
+                    cxx,
+                    &blaze_src_cxx,
+                    &format!("blazesym_cxx_{cxx}.bin"),
+                    &[
+                        "-Wall",
+                        "-Wextra",
+                        "-Werror",
+                        "-I",
+                        Path::new(crate_dir).join("include").to_str().unwrap(),
+                    ],
+                );
+            }
+        }
+    }
+}

cbindgen.toml → capi/cbindgen.toml

@@ -1,4 +1,4 @@
-# See https://github.com/eqrion/cbindgen/blob/master/docs.md#cbindgentoml
+# See https://github.com/mozilla/cbindgen/blob/master/docs.md#cbindgentoml
 
 language = "C"
 cpp_compat = true
@@ -11,9 +11,9 @@ exclude = ["Addr"]
 
 [export.rename]
 "Addr" = "uintptr_t"
-"Inspector" = "blaze_inspector"
-"Normalizer" = "blaze_normalizer"
-"Symbolizer" = "blaze_symbolizer"
+"Inspector" = "struct blaze_inspector"
+"Normalizer" = "struct blaze_normalizer"
+"Symbolizer" = "struct blaze_symbolizer"
 
 [fn]
 args = "Vertical"