Add wasmtime-c-api-impl to the list of crates to publish (#7837) (#7872)

* Add wasmtime-c-api-impl to the list of crates to publish

* Enable rustdoc and publishing for c-api crate

* Provide paths to c-api headers as cargo links metadata

* Add a README section about using wasm-c-api in a rust crate

* In C API doc comment, mention use case for crates w/ C bindings

* Enable publishing for wasmtime-c-api-macros (prtest:full)

* Move c-api crates later in the publishing sequence (prtest:full)

Author: maxbrunsfeld

Cargo.lock

@@ -154,6 +154,7 @@ all = 'allow'
 arbitrary = { version = "1.3.1" }
 wasmtime-wmemcheck = { path = "crates/wmemcheck", version = "=18.0.0" }
 wasmtime = { path = "crates/wasmtime", version = "18.0.0", default-features = false }
+wasmtime-c-api-macros = { path = "crates/c-api-macros", version = "=18.0.0" }
 wasmtime-cache = { path = "crates/cache", version = "=18.0.0" }
 wasmtime-cli-flags = { path = "crates/cli-flags", version = "=18.0.0" }
 wasmtime-cranelift = { path = "crates/cranelift", version = "=18.0.0" }

Cargo.toml

@@ -1,10 +1,9 @@
 [package]
 name = "wasmtime-c-api-macros"
-version = "0.0.0"
+version.workspace = true
 authors = ["The Wasmtime Project Developers"]
 license = "Apache-2.0 WITH LLVM-exception"
 edition.workspace = true
-publish = false
 
 [lints]
 workspace = true

crates/c-api/macros/Cargo.toml renamed to crates/c-api-macros/Cargo.toml

@@ -7,14 +7,14 @@ license = "Apache-2.0 WITH LLVM-exception"
 repository = "https://github.com/bytecodealliance/wasmtime"
 readme = "README.md"
 edition.workspace = true
-publish = false
+links = "wasmtime-c-api"
+include = ["include", "src", "wasm-c-api/include", "build.rs"]
 
 [lints]
 workspace = true
 
 [lib]
 name = "wasmtime_c_api"
-doc = false
 test = false
 doctest = false
 
@@ -23,7 +23,7 @@ env_logger = { workspace = true, optional = true }
 anyhow = { workspace = true }
 once_cell = { workspace = true }
 wasmtime = { workspace = true, features = ['cranelift', 'runtime'] }
-wasmtime-c-api-macros = { path = "macros" }
+wasmtime-c-api-macros = { workspace = true }
 log = { workspace = true }
 tracing = { workspace = true }
 

crates/c-api/macros/src/lib.rs renamed to crates/c-api-macros/src/lib.rs

@@ -2,3 +2,43 @@
 
 For more information you can find the documentation for this library
 [online](https://bytecodealliance.github.io/wasmtime/c-api/).
+
+## Using in a C Project
+
+To use Wasmtime from a C or C++ project, you can use Cargo to build the Wasmtime C bindings. From the root of the Wasmtime repository, run the following command:
+
+```
+cargo build --release wasmtime-c-api
+```
+
+This will create static and dynamic libraries called `libwasmtime` in the `target/release` directory.
+
+## Using in a Rust Project
+
+If you have a Rust crate that contains bindings to a C or C++ library that uses Wasmtime, you can link the Wasmtime C API using Cargo.
+
+1. Add a dependency on the `wasmtime-c-api-impl` crate to your `Cargo.toml`. Note that package name differs from the library name.
+
+```toml
+[dependencies]
+wasmtime-c-api = { version = "16.0.0", package = "wasmtime-c-api-impl" }
+```
+
+2. In your `build.rs` file, when compiling your C/C++ source code, add the C `wasmtime-c-api` headers to the include path:
+
+```rust
+fn main() {
+    let mut cfg = cc::Build::new();
+
+    // Add to the include path the wasmtime headers and the standard
+    // Wasm C API headers.
+    cfg
+        .include(std::env::var("DEP_WASMTIME_C_API_INCLUDE").unwrap());
+        .include(std::env::var("DEP_WASMTIME_C_API_WASM_INCLUDE").unwrap());
+
+    // Compile your C code.
+    cfg
+        .file("src/your_c_code.c")
+        .compile("your_library");
+}
+```

crates/c-api/Cargo.toml

@@ -0,0 +1,5 @@
+fn main() {
+    let dir = std::env::var("CARGO_MANIFEST_DIR").unwrap();
+    println!("cargo:include={dir}/include");
+    println!("cargo:wasm_include={dir}/wasm-c-api/include");
+}

crates/c-api/README.md

@@ -1,8 +1,11 @@
 //! This crate is the implementation of Wasmtime's C API.
 //!
-//! This crate is not intended to be used from Rust itself, for that see the
-//! `wasmtime` crate. Otherwise this is typically compiled as a
-//! cdylib/staticlib. Documentation for this crate largely lives in the header
+//! This crate is normally not intended to be used from Rust itself. For that,
+//! see the `wasmtime` crate. It is possible to use this crate via Cargo, for
+//! Rust crates that wrap C libraries that use wasmtime. Most often, this crate
+//! is compiled as a cdylib or staticlib, via the `wasmtime-c-api` crate.
+//!
+//! Documentation for this crate largely lives in the header
 //! files of the `include` directory for this crate.
 //!
 //! At a high level this crate implements the `wasm.h` API with some gymnastics,

crates/c-api/build.rs

@@ -71,6 +71,8 @@ const CRATES_TO_PUBLISH: &[&str] = &[
     "wasmtime-wasi-nn",
     "wasmtime-wasi-threads",
     "wasmtime-wast",
+    "wasmtime-c-api-macros",
+    "wasmtime-c-api-impl",
     "wasmtime-cli-flags",
     "wasmtime-explorer",
     "wasmtime-cli",