Generate a C API for IGVM (#3)

This is a proposal on how to implement
#1 and provide a C API for igvm.

The approach taken is to based on using
[cbindgen](https://github.com/mozilla/cbindgen) to analyze the rust code
and produce header files usable from C. To support this, a set of C
friendly functions have been added to `igvm/src/c_api.rs` which allows,
at present, binary files to be parsed and processed.

The additional functions are hidden behind a rust feature named
`igvm-c`. When performing a normal build (without the C API) the only
change that has any effect is from the first commit
4da1043 which by necessity relaxes the
unsafe_code restriction. Unfortunately this cannot be controlled by the
feature.

The sample in `igvm_c/sample` and the unit test code in `igvm/tests` are
probably the best places to start to see how to use the proposed API
from C.

---------

Signed-off-by: Roy Hopkins <[email protected]>
Signed-off-by: Roy Hopkins <[email protected]>

.github/workflows/rust.yml

@@ -34,6 +34,17 @@ jobs:
     - name: Run doc tests
       run: cargo test --no-fail-fast --doc --workspace
 
+  c_api:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Install cbindgen
+        run: cargo install cbindgen
+      - name: Install build dependencies
+        run: sudo apt-get install -y libcunit1-dev
+      - name: Build and test
+        run: make -f igvm_c/Makefile
+
   miri:
     name: "Miri"
     strategy:

.gitignore

@@ -2,6 +2,7 @@
 # will have compiled files and executables
 debug/
 target/
+target_c/
 
 # Remove Cargo.lock from gitignore if creating an executable, leave it for libraries
 # More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html
@@ -12,3 +13,6 @@ Cargo.lock
 
 # MSVC Windows builds of rustc generate these, which store debugging information
 *.pdb
+
+# Header files generated for the C API by igvm_c/Makefile
+igvm_c/include/*.h

Cargo.toml

@@ -5,10 +5,12 @@
 resolver = "2"
 members = [
     "igvm",
+    "igvm_c/test_data",
 ]
 
 [workspace.dependencies]
 igvm_defs = { path = "igvm_defs", version = "0.1.3" }
+igvm = { path = "igvm", version = "0.1.3" }
 
 anyhow = "1.0"
 bitfield-struct = "0.5"

igvm/Cargo.toml

@@ -12,6 +12,19 @@ repository = "https://github.com/microsoft/igvm"
 keywords = ["virtualization"]
 categories = ["virtualization", "parser-implementations"]
 
+[package.metadata.docs.rs]
+# Document all features
+all-features = true
+# Defines the configuration attribute `docsrs` which emits nicer docs via
+# nightly features.
+#
+# Run locally with RUSTDOCFLAGS="--cfg docsrs" cargo +nightly doc --all-features
+rustdoc-args = ["--cfg", "docsrs"]
+
+[lib]
+name = "igvm"
+crate-type = ["staticlib", "rlib"]
+
 [dependencies]
 igvm_defs = { workspace = true, features = ["unstable"] }
 
@@ -23,3 +36,7 @@ open-enum.workspace = true
 thiserror.workspace = true
 tracing.workspace = true
 zerocopy = { workspace = true, features = ["alloc"] }
+
+[features]
+default = []
+igvm-c = [] # Add exports that allow the library to be used from C