README.md
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