1# Wasmtime's C/C++ API 2 3## API Documentation 4 5[The API documentation for the Wasmtime C library is hosted 6here.](https://bytecodealliance.github.io/wasmtime/c-api/). 7 8## Using in a C/C++ Project 9 10### Using a Pre-Built Static or Dynamic Library 11 12Each release on Wasmtime's [GitHub Releases 13page](https://github.com/bytecodealliance/wasmtime/releases) has pre-built 14binaries for both static and dynamic libraries for a variety of architectures 15and operating systems attached, as well as header files you can include. 16 17### Building Wasmtime's C/C++ API from Source 18 19To use Wasmtime from a C or C++ project, you must have 20[CMake](https://cmake.org/) and [a Rust 21toolchain](https://www.rust-lang.org/tools/install) installed. 22 23From the root of the Wasmtime repository, run the following commands: 24 25```shell-session 26$ cmake -S crates/c-api -B target/c-api --install-prefix "$(pwd)/artifacts" 27$ cmake --build target/c-api 28$ cmake --install target/c-api 29``` 30 31These commands will produce the following files: 32 33* `artifacts/lib/libwasmtime.{a,lib}`: Static Wasmtime library. Exact extension 34 depends on your operating system. 35 36* `artifacts/lib/libwasmtime.{so,dylib,dll}`: Dynamic Wasmtime library. Exact 37 extension depends on your operating system. 38 39* `artifacts/include/**.{h,hh}`: Header files for working with Wasmtime. 40 41## Using in a C++ Project 42 43A header only C++ API is also offered as `wasmtime.hh`, which is built on top 44of the C API. Its located next to the C headers when you download a pre-built 45library, or when building from source. C++17 is required. 46 47## Using in a Rust Project 48 49If 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. 50 511. Add a dependency on the `wasmtime-c-api-impl` crate to your `Cargo.toml`. Note that package name differs from the library name. 52 53```toml 54[dependencies] 55wasmtime-c-api = { version = "16.0.0", package = "wasmtime-c-api-impl" } 56``` 57 582. In your `build.rs` file, when compiling your C/C++ source code, add the C `wasmtime-c-api` headers to the include path: 59 60```rust 61fn main() { 62 let mut cfg = cc::Build::new(); 63 64 // Add to the include path the wasmtime headers and the standard 65 // Wasm C API headers. 66 cfg 67 .include(std::env::var("DEP_WASMTIME_C_API_INCLUDE").unwrap()); 68 69 // Compile your C code. 70 cfg 71 .file("src/your_c_code.c") 72 .compile("your_library"); 73} 74``` 75 76## Testing 77 78Running tests for the C API can be done using cmake from the root of the repo: 79 80```shell-session 81$ cmake -S examples -B examples/build -DBUILD_SHARED_LIBS=OFF -DBUILD_TESTS=ON -DCMAKE_BUILD_TYPE=Debug 82$ cmake --build examples/build --config Debug 83$ CTEST_OUTPUT_ON_FAILURE=1 cmake --build examples/build --config Debug --target test 84``` 85 86To build and run a subset of tests by name: 87 88```shell-session 89$ cmake --build examples/build --config Debug 90$ ctest --test-dir examples/build --output-on-failure -R $MY_TEST 91``` 92 93where `$MY_TEST` is the test name or glob pattern; for example, 94`MemoryType.Simple` to run that one particular test or `TypedFunc.*` to run all 95typed function tests. 96 97To run under `gdb`: 98 99```shell-session 100$ gdb --args ctest --test-dir examples/build/ --output-on-failure -R $MY_TEST 101(gdb) set follow-fork-mode child 102(gdb) run 103``` 104 105To run under `rr`: 106 107``` 108$ rr record ctest --test-dir examples/build/ --output-on-failure -R $MY_TEST 109$ rr replay 110``` 111