Add cmake compatibility to c-api (bytecodealliance#4369)

* Add cmake compatibility to c-api

* Add CMake documentation to wasmtime.h

* Add CMake instructions in examples

* Modify CI for CMake support

* Use correct rust in CI

* Trigger build

* Refactor run-examples

* Reintroduce example_to_run in run-examples

* Replace run-examples crate with cmake

* Fix markdown formatting in examples readme

* Fix cmake test quotes

* Build rust wasm before cmake tests

* Pass CTEST_OUTPUT_ON_FAILURE

* Another cmake test

* Handle os differences in cmake test

* Fix bugs in memory and multimemory examples

.github/workflows/main.yml

@@ -273,11 +273,21 @@ jobs:
         touch ${{ runner.tool_cache }}/qemu/built
       if: matrix.gcc != ''
 
-    # Ensure all our examples build and execute
-    - run: cargo run -p run-examples
+    # Prepare tests in CMake
+    - run: cmake -Sexamples -Bexamples/build -DBUILD_SHARED_LIBS=OFF
+      if: matrix.target == ''
+    # Build tests
+    - run: cmake --build examples/build --config Debug
+      if: matrix.target == ''
+    # Run tests
+    - run: cmake -E env CTEST_OUTPUT_ON_FAILURE=1 cmake --build examples/build --config Debug --target RUN_TESTS
       env:
         RUST_BACKTRACE: 1
-      if: matrix.target == ''
+      if: matrix.target == '' && matrix.os == 'windows-2019'
+    - run: cmake -E env CTEST_OUTPUT_ON_FAILURE=1 cmake --build examples/build --config Debug --target test
+      env:
+        RUST_BACKTRACE: 1
+      if: matrix.target == '' && matrix.os != 'windows-2019'
 
     # Build and test all features
     - run: ./ci/run-tests.sh --locked

.gitignore

@@ -19,3 +19,4 @@ foo
 .cargo
 publish
 vendor
+examples/build

Cargo.toml

@@ -81,7 +81,6 @@ members = [
   "crates/bench-api",
   "crates/c-api",
   "crates/cli-flags",
-  "crates/misc/run-examples",
   "examples/fib-debug/wasm",
   "examples/wasi/wasm",
   "examples/tokio/wasm",

README.md

@@ -111,7 +111,7 @@ You can use Wasmtime from a variety of different languages through embeddings of
 the implementation:
 
 * **[Rust]** - the [`wasmtime` crate]
-* **[C]** - the [`wasm.h`, `wasi.h`, and `wasmtime.h` headers][c-headers] or use [`wasmtime` Conan package]
+* **[C]** - the [`wasm.h`, `wasi.h`, and `wasmtime.h` headers][c-headers], [CMake](crates/c-api/CMakeLists.txt) or [`wasmtime` Conan package]
 * **C++** - the [`wasmtime-cpp` repository][wasmtime-cpp] or use [`wasmtime-cpp` Conan package]
 * **[Python]** - the [`wasmtime` PyPI package]
 * **[.NET]** - the [`Wasmtime` NuGet package]

crates/c-api/CMakeLists.txt

@@ -0,0 +1,64 @@
+cmake_minimum_required(VERSION 3.10)
+
+option(BUILD_SHARED_LIBS "Build using shared libraries" OFF)
+
+if (CMAKE_BUILD_TYPE STREQUAL "Release")
+	set(WASMTIME_BUILD_TYPE_FLAG "--release")
+	set(WASMTIME_BUILD_TYPE "release")
+else()
+	set(WASMTIME_BUILD_TYPE "debug")
+endif()
+
+if (BUILD_SHARED_LIBS)
+	# Copy shared library into build directory
+	if(WIN32)
+		set(WASMTIME_INSTALL_COMMAND ${CMAKE_COMMAND} -E copy_if_different
+			${CMAKE_CURRENT_SOURCE_DIR}/../../target/${WASMTIME_BUILD_TYPE}/wasmtime.dll
+			${CMAKE_BINARY_DIR})
+	elseif(APPLE)
+		set(WASMTIME_INSTALL_COMMAND ${CMAKE_COMMAND} -E copy_if_different
+			${CMAKE_CURRENT_SOURCE_DIR}/../../target/${WASMTIME_BUILD_TYPE}/libwasmtime.dylib
+			${CMAKE_BINARY_DIR})
+	else()
+		set(WASMTIME_INSTALL_COMMAND ${CMAKE_COMMAND} -E copy_if_different
+			${CMAKE_CURRENT_SOURCE_DIR}/../../target/${WASMTIME_BUILD_TYPE}/libwasmtime.so
+			${CMAKE_BINARY_DIR})
+	endif()
+endif()
+
+include(ExternalProject)
+ExternalProject_Add(
+	wasmtime-crate
+	DOWNLOAD_COMMAND ""
+	CONFIGURE_COMMAND ""
+	INSTALL_COMMAND "${WASMTIME_INSTALL_COMMAND}"
+	BUILD_COMMAND cargo build ${WASMTIME_BUILD_TYPE_FLAG}
+	BINARY_DIR ${CMAKE_CURRENT_SOURCE_DIR}
+	BUILD_ALWAYS ON)
+add_library(wasmtime INTERFACE)
+add_dependencies(wasmtime wasmtime-crate)
+
+if (BUILD_SHARED_LIBS)
+	if(WIN32)
+		target_link_libraries(wasmtime INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}/../../target/${WASMTIME_BUILD_TYPE}/wasmtime.dll.lib)
+	elseif(APPLE)
+		target_link_libraries(wasmtime INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}/../../target/${WASMTIME_BUILD_TYPE}/libwasmtime.dylib)
+		set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -Wl,-rpath='$ORIGIN'")
+	else()
+		target_link_libraries(wasmtime INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}/../../target/${WASMTIME_BUILD_TYPE}/libwasmtime.so)
+		set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -Wl,-rpath='$ORIGIN'")
+	endif()
+else()
+	if(WIN32)
+		target_compile_options(wasmtime INTERFACE -DWASM_API_EXTERN= -DWASI_API_EXTERN=)
+		target_link_libraries(wasmtime INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}/../../target/${WASMTIME_BUILD_TYPE}/wasmtime.lib
+			ws2_32 advapi32 userenv ntdll shell32 ole32 bcrypt)
+	elseif(APPLE)
+		target_link_libraries(wasmtime INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}/../../target/${WASMTIME_BUILD_TYPE}/libwasmtime.a)
+	else()
+		target_link_libraries(wasmtime INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}/../../target/${WASMTIME_BUILD_TYPE}/libwasmtime.a
+			pthread dl m)
+	endif()
+endif()
+
+target_include_directories(wasmtime INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}/include ${CMAKE_CURRENT_SOURCE_DIR}/wasm-c-api/include)

crates/c-api/include/wasmtime.h

@@ -28,6 +28,22 @@
  * as a `lib` directory with both a static archive and a dynamic library of
  * Wasmtime. You can link to either of them as you see fit.
  *
+ * ## Installing the C API through CMake
+ *
+ * CMake can be used to make the process of linking and compiling easier. An
+ * example of this if you have wasmtime as a git submodule at
+ * `third_party/wasmtime`:
+ * ```
+ * add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/third_party/wasmtime/crates/c-api
+ * ${CMAKE_CURRENT_BINARY_DIR}/wasmtime)
+ * ...
+ * target_include_directories(YourProject PUBLIC wasmtime)
+ * target_link_libraries(YourProject PUBLIC wasmtime)
+ * ```
+ * `BUILD_SHARED_LIBS` is provided as a define if you would like to build a
+ * shared library instead. You must distribute the appropriate shared library
+ * for your platform if you do this.
+ *
  * ## Linking against the C API
  *
  * You'll want to arrange the `include` directory of the C API to be in your
@@ -166,8 +182,8 @@
 
 #include <wasi.h>
 #include <wasmtime/config.h>
-#include <wasmtime/error.h>
 #include <wasmtime/engine.h>
+#include <wasmtime/error.h>
 #include <wasmtime/extern.h>
 #include <wasmtime/func.h>
 #include <wasmtime/global.h>

examples/CMakeLists.txt

@@ -0,0 +1,73 @@
+cmake_minimum_required(VERSION 3.10)
+project(wasmtime-examples)
+
+add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/../crates/c-api ${CMAKE_CURRENT_BINARY_DIR}/wasmtime)
+
+function(CREATE_TARGET TARGET TARGET_PATH)
+	add_executable(wasmtime-${TARGET} ${TARGET_PATH})
+
+	if(CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
+		target_compile_options(wasmtime-${TARGET} PRIVATE -Wall -Wextra -Wno-deprecated-declarations)
+	elseif(CMAKE_CXX_COMPILER_ID STREQUAL "MSVC")
+		target_compile_options(wasmtime-${TARGET} PRIVATE /W3)
+	endif()
+
+	set_target_properties(wasmtime-${TARGET} PROPERTIES
+		OUTPUT_NAME wasmtime-${TARGET}
+		RUNTIME_OUTPUT_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/$<0:>
+		CXX_VISIBILITY_PRESET hidden
+		POSITION_INDEPENDENT_CODE ON)
+
+	target_include_directories(wasmtime-${TARGET} PUBLIC wasmtime)
+	target_link_libraries(wasmtime-${TARGET} PUBLIC wasmtime)
+	add_test(NAME ${TARGET}-c COMMAND $<TARGET_FILE:wasmtime-${TARGET}> WORKING_DIRECTORY ../..)
+endfunction()
+
+function(CREATE_RUST_TEST EXAMPLE)
+	if(ARGC GREATER 1)
+		add_test(NAME ${EXAMPLE}-rust COMMAND cargo run --example ${EXAMPLE} --features ${ARGV1} WORKING_DIRECTORY ../..)
+	else()
+		add_test(NAME ${EXAMPLE}-rust COMMAND cargo run --example ${EXAMPLE} WORKING_DIRECTORY ../..)
+	endif()
+endfunction()
+function(CREATE_RUST_WASM EXAMPLE TARGET)
+	execute_process(COMMAND cargo build -p example-${EXAMPLE}-wasm --target ${TARGET})
+endfunction()
+
+# Enable testing
+enable_testing()
+
+# Add all examples
+create_target(externref externref.c)
+create_target(fib-debug fib-debug/main.c)
+create_target(fuel fuel.c)
+create_target(gcd gcd.c)
+create_target(hello hello.c)
+create_target(interrupt interrupt.c)
+create_target(linking linking.c)
+create_target(memory memory.c)
+create_target(multi multi.c)
+create_target(multimemory multimemory.c)
+create_target(serialize serialize.c)
+create_target(threads threads.c)
+create_target(wasi wasi/main.c)
+
+# Add rust tests
+create_rust_wasm(fib-debug wasm32-unknown-unknown)
+create_rust_wasm(tokio wasm32-wasi)
+create_rust_wasm(wasi wasm32-wasi)
+create_rust_test(epochs)
+create_rust_test(externref)
+create_rust_test(fib-debug)
+create_rust_test(fuel)
+create_rust_test(gcd)
+create_rust_test(hello)
+create_rust_test(interrupt)
+create_rust_test(linking)
+create_rust_test(memory)
+create_rust_test(multi)
+create_rust_test(multimemory)
+create_rust_test(serialize)
+create_rust_test(threads)
+create_rust_test(wasi)
+create_rust_test(tokio wasmtime-wasi/tokio)

examples/README.md

@@ -8,7 +8,10 @@ Each example is available in both C and in Rust. Examples are accompanied with a
 `*.wat` file which is the wasm input, or a Rust project in a `wasm` folder which
 is the source code for the original wasm file.
 
-Rust examples can be executed with `cargo run --example $name`, and C examples
-need to be compiled using your system compiler and appropriate header files.
+Rust examples can be executed with `cargo run --example $name`. C examples can
+be built with `mkdir build && cd build && cmake ..`. You can run
+`cmake --build .` to build all examples or
+`cmake --build . --target wasmtime-$name`, replacing the name as you wish. They
+can also be [built manually](https://docs.wasmtime.dev/c-api/).
 
 For more information see the examples themselves!