diff --git a/Cargo.lock b/Cargo.lock index c94c32784524..b60980de94ff 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -3315,7 +3315,7 @@ dependencies = [ [[package]] name = "wasmtime-c-api-macros" -version = "0.0.0" +version = "18.0.0" dependencies = [ "proc-macro2", "quote", diff --git a/Cargo.toml b/Cargo.toml index 8f0689c015bd..6b01f8282fef 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -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" } diff --git a/crates/c-api/macros/Cargo.toml b/crates/c-api-macros/Cargo.toml similarity index 89% rename from crates/c-api/macros/Cargo.toml rename to crates/c-api-macros/Cargo.toml index ed01bab94a53..0f45c16f1485 100644 --- a/crates/c-api/macros/Cargo.toml +++ b/crates/c-api-macros/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 diff --git a/crates/c-api/macros/src/lib.rs b/crates/c-api-macros/src/lib.rs similarity index 100% rename from crates/c-api/macros/src/lib.rs rename to crates/c-api-macros/src/lib.rs diff --git a/crates/c-api/Cargo.toml b/crates/c-api/Cargo.toml index 175bbbd9a2b9..3ef655e0443e 100644 --- a/crates/c-api/Cargo.toml +++ b/crates/c-api/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 } diff --git a/crates/c-api/README.md b/crates/c-api/README.md index 5d7149dd18ac..3c73616165cb 100644 --- a/crates/c-api/README.md +++ b/crates/c-api/README.md @@ -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"); +} +``` diff --git a/crates/c-api/build.rs b/crates/c-api/build.rs new file mode 100644 index 000000000000..7f3f03bd93d5 --- /dev/null +++ b/crates/c-api/build.rs @@ -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"); +} diff --git a/crates/c-api/src/lib.rs b/crates/c-api/src/lib.rs index fb686427e6d6..b14c09e0c01a 100644 --- a/crates/c-api/src/lib.rs +++ b/crates/c-api/src/lib.rs @@ -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, diff --git a/scripts/publish.rs b/scripts/publish.rs index 647f0c7e3a09..b5d2dbc36789 100644 --- a/scripts/publish.rs +++ b/scripts/publish.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",