diff --git a/CHANGELOG.md b/CHANGELOG.md index 2a1b0ed5cc7..6a9b3942fd0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,7 @@ - [#2054](https://github.com/wasmerio/wasmer/pull/2054) Add `wasm_config_delete` to the Wasm C API. ### Changed +- [#2083](https://github.com/wasmerio/wasmer/pull/2083) Mark `wasi_env_set_(instance|memory)` as deprecated. You may simply remove them with no side-effect. - [#2056](https://github.com/wasmerio/wasmer/pull/2056) Change back to depend on the `enumset` crate instead of `wasmer_enumset` ### Fixed diff --git a/lib/c-api/build.rs b/lib/c-api/build.rs index 6fcc41b6456..8212c3bfb37 100644 --- a/lib/c-api/build.rs +++ b/lib/c-api/build.rs @@ -89,8 +89,41 @@ fn build_wasm_c_api_headers(crate_dir: &str, out_dir: &str) { out_header_file.push("wasmer_wasm"); let mut pre_header = format!( - r#"// The Wasmer C/C++ header file compatible with the `wasm-c-api` standard API. -// This file is generated by lib/c-api/build.rs. + r#"// The Wasmer C/C++ header file compatible with the [`wasm-c-api`] +// standard API, as `wasm.h` (included here). +// +// This file is automatically generated by `lib/c-api/build.rs` of the +// [`wasmer-c-api`] Rust crate. +// +// # Stability +// +// The [`wasm-c-api`] standard API is a _living_ standard. There is no +// commitment for stability yet. We (Wasmer) will try our best to keep +// backward compatibility as much as possible. Nonetheless, some +// necessary API aren't yet standardized, and as such, we provide a +// custom API, e.g. `wasi_*` types and functions. +// +// The documentation makes it clear whether a function is unstable. +// +// When a type or a function will be deprecated, it will be marked as +// such with the appropriated compiler warning, and will be removed at +// the next release round. +// +// # Documentation +// +// At the time of writing, the [`wasm-c-api`] standard has no +// documentation. This file also does not include inline +// documentation. However, we have made (and we continue to make) an +// important effort to document everything. [See the documentation +// online][documentation]. Please refer to this page for the real +// canonical documentation. It also contains numerous examples. +// +// To generate the documentation locally, run `cargo doc --open` from +// within the [`wasmer-c-api`] Rust crate. +// +// [`wasm-c-api`]: https://github.com/WebAssembly/wasm-c-api +// [`wasmer-c-api`]: https://github.com/wasmerio/wasmer/tree/master/lib/c-api +// [documentation]: https://wasmerio.github.io/wasmer/crates/wasmer_c_api/ #if !defined(WASMER_WASM_H_PRELUDE) @@ -184,10 +217,12 @@ fn build_wasmer_c_api_headers(crate_dir: &str, out_dir: &str) { out_header_file.set_extension("h"); // Build and generate the header file. - exclude_items_from_wasm_c_api(new_builder(Language::C, crate_dir, guard, &pre_header)) - .generate() - .expect("Unable to generate C bindings") - .write_to_file(out_header_file.as_path()); + exclude_items_from_wasm_c_api( + new_builder(Language::C, crate_dir, guard, &pre_header).with_documentation(true), + ) + .generate() + .expect("Unable to generate C bindings") + .write_to_file(out_header_file.as_path()); // Copy the generated bindings from `OUT_DIR` to // `CARGO_MANIFEST_DIR`. @@ -203,10 +238,12 @@ fn build_wasmer_c_api_headers(crate_dir: &str, out_dir: &str) { out_header_file.set_extension("hh"); // Build and generate the header file. - exclude_items_from_wasm_c_api(new_builder(Language::Cxx, crate_dir, guard, &pre_header)) - .generate() - .expect("Unable to generate C++ bindings") - .write_to_file(out_header_file.as_path()); + exclude_items_from_wasm_c_api( + new_builder(Language::Cxx, crate_dir, guard, &pre_header).with_documentation(true), + ) + .generate() + .expect("Unable to generate C++ bindings") + .write_to_file(out_header_file.as_path()); // Copy the generated bindings from `OUT_DIR` to // `CARGO_MANIFEST_DIR`. @@ -247,7 +284,7 @@ fn new_builder(language: Language, crate_dir: &str, include_guard: &str, header: .with_crate(crate_dir) .with_include_guard(include_guard) .with_header(header) - .with_documentation(true) + .with_documentation(false) .with_define("target_family", "windows", "_WIN32") .with_define("target_arch", "x86_64", "ARCH_X86_64") .with_define("feature", "jit", JIT_FEATURE_AS_C_DEFINE) diff --git a/lib/c-api/src/wasm_c_api/wasi/mod.rs b/lib/c-api/src/wasm_c_api/wasi/mod.rs index bb85dc16cc6..9e9f3e8d72d 100644 --- a/lib/c-api/src/wasm_c_api/wasi/mod.rs +++ b/lib/c-api/src/wasm_c_api/wasi/mod.rs @@ -199,30 +199,22 @@ pub extern "C" fn wasi_env_delete(_state: Option>) {} /// This function is deprecated. You may safely remove all calls to it and everything /// will continue to work. -// Dead code: deprecate or remove -#[allow(unused_variables)] +/// +/// cbindgen:prefix=DEPRECATED("This function is no longer necessary. You may safely remove all calls to it and everything will continue to work.") #[no_mangle] -pub extern "C" fn wasi_env_set_instance(env: &mut wasi_env_t, instance: &wasm_instance_t) -> bool { - /* - let memory = if let Ok(memory) = instance.inner.exports.get_memory("memory") { - memory - } else { - return false; - }; - env.inner.set_memory(memory.clone()); - */ - +pub extern "C" fn wasi_env_set_instance( + _env: &mut wasi_env_t, + _instance: &wasm_instance_t, +) -> bool { true } /// This function is deprecated. You may safely remove all calls to it and everything /// will continue to work. -// Dead code: deprecate or remove -#[allow(unused_variables)] +/// +/// cbindgen:prefix=DEPRECATED("This function is no longer necessary. You may safely remove all calls to it and everything will continue to work.") #[no_mangle] -pub extern "C" fn wasi_env_set_memory(env: &mut wasi_env_t, memory: &wasm_memory_t) { - //env.inner.set_memory(memory.inner.clone()); -} +pub extern "C" fn wasi_env_set_memory(_env: &mut wasi_env_t, _memory: &wasm_memory_t) {} #[no_mangle] pub unsafe extern "C" fn wasi_env_read_stdout( diff --git a/lib/c-api/wasmer_wasm.h b/lib/c-api/wasmer_wasm.h index d3ae2b7636c..a53fddbae39 100644 --- a/lib/c-api/wasmer_wasm.h +++ b/lib/c-api/wasmer_wasm.h @@ -1,5 +1,38 @@ -// The Wasmer C/C++ header file compatible with the `wasm-c-api` standard API. -// This file is generated by lib/c-api/build.rs. +// The Wasmer C/C++ header file compatible with the [`wasm-c-api`] +// standard API, as `wasm.h` (included here). +// +// This file is automatically generated by `lib/c-api/build.rs` of the +// [`wasmer-c-api`] Rust crate. +// +// # Stability +// +// The [`wasm-c-api`] standard API is a _living_ standard. There is no +// commitment for stability yet. We (Wasmer) will try our best to keep +// backward compatibility as much as possible. Nonetheless, some +// necessary API aren't yet standardized, and as such, we provide a +// custom API, e.g. `wasi_*` types and functions. +// +// The documentation makes it clear whether a function is unstable. +// +// When a type or a function will be deprecated, it will be marked as +// such with the appropriated compiler warning, and will be removed at +// the next release round. +// +// # Documentation +// +// At the time of writing, the [`wasm-c-api`] standard has no +// documentation. This file also does not include inline +// documentation. However, we have made (and we continue to make) an +// important effort to document everything. [See the documentation +// online][documentation]. Please refer to this page for the real +// canonical documentation. It also contains numerous examples. +// +// To generate the documentation locally, run `cargo doc --open` from +// within the [`wasmer-c-api`] Rust crate. +// +// [`wasm-c-api`]: https://github.com/WebAssembly/wasm-c-api +// [`wasmer-c-api`]: https://github.com/wasmerio/wasmer/tree/master/lib/c-api +// [documentation]: https://wasmerio.github.io/wasmer/crates/wasmer_c_api/ #if !defined(WASMER_WASM_H_PRELUDE) @@ -63,94 +96,33 @@ #include "wasm.h" #if defined(WASMER_WASI_ENABLED) -/** - * The version of WASI. This is determined by the imports namespace - * string. - */ typedef enum { #if defined(WASMER_WASI_ENABLED) - /** - * An invalid version. - */ INVALID_VERSION = -1, #endif #if defined(WASMER_WASI_ENABLED) - /** - * Latest version. - * - * It's a “floating” version, i.e. it's an alias to the latest - * version (for the moment, `Snapshot1`). Using this version is a - * way to ensure that modules will run only if they come with the - * latest WASI version (in case of security issues for instance), - * by just updating the runtime. - * - * Note that this version is never returned by an API. It is - * provided only by the user. - */ LATEST = 0, #endif #if defined(WASMER_WASI_ENABLED) - /** - * `wasi_unstable`. - */ SNAPSHOT0 = 1, #endif #if defined(WASMER_WASI_ENABLED) - /** - * `wasi_snapshot_preview1`. - */ SNAPSHOT1 = 2, #endif } wasi_version_t; #endif #if defined(WASMER_COMPILER_ENABLED) -/** - * Kind of compilers that can be used by the engines. - * - * This is a Wasmer-specific type with Wasmer-specific functions for - * manipulating it. - */ typedef enum { - /** - * Variant to represent the Cranelift compiler. See the - * [`wasmer_compiler_cranelift`] Rust crate. - */ CRANELIFT = 0, - /** - * Variant to represent the LLVM compiler. See the - * [`wasmer_compiler_llvm`] Rust crate. - */ LLVM = 1, - /** - * Variant to represent the Singlepass compiler. See the - * [`wasmer_compiler_singlepass`] Rust crate. - */ SINGLEPASS = 2, } wasmer_compiler_t; #endif -/** - * Kind of engines that can be used by the store. - * - * This is a Wasmer-specific type with Wasmer-specific functions for - * manipulating it. - */ typedef enum { - /** - * Variant to represent the JIT engine. See the - * [`wasmer_engine_jit`] Rust crate. - */ JIT = 0, - /** - * Variant to represent the Native engine. See the - * [`wasmer_engine_native`] Rust crate. - */ NATIVE = 1, - /** - * Variant to represent the Object File engine. See the - * [`wasmer_engine_object_file`] Rust crate. - */ OBJECT_FILE = 2, } wasmer_engine_t; @@ -211,9 +183,6 @@ void wasi_env_delete(wasi_env_t *_state); #endif #if defined(WASMER_WASI_ENABLED) -/** - * Takes ownership over the `wasi_config_t`. - */ wasi_env_t *wasi_env_new(wasi_config_t *config); #endif @@ -226,25 +195,18 @@ intptr_t wasi_env_read_stdout(wasi_env_t *env, char *buffer, uintptr_t buffer_le #endif #if defined(WASMER_WASI_ENABLED) -/** - * This function is deprecated. You may safely remove all calls to it and everything - * will continue to work. - */ -bool wasi_env_set_instance(wasi_env_t *env, const wasm_instance_t *instance); +DEPRECATED("This function is longer necessary. You may safely remove all calls to it and everything will continue to work.") +bool wasi_env_set_instance(wasi_env_t *_env, + const wasm_instance_t *_instance); #endif #if defined(WASMER_WASI_ENABLED) -/** - * This function is deprecated. You may safely remove all calls to it and everything - * will continue to work. - */ -void wasi_env_set_memory(wasi_env_t *env, const wasm_memory_t *memory); +DEPRECATED("This function is no longer necessary. You may safely remove all calls to it and everything will continue to work.") +void wasi_env_set_memory(wasi_env_t *_env, + const wasm_memory_t *_memory); #endif #if defined(WASMER_WASI_ENABLED) -/** - * Takes ownership of `wasi_env_t`. - */ bool wasi_get_imports(const wasm_store_t *store, const wasm_module_t *module, const wasi_env_t *wasi_env, @@ -260,354 +222,29 @@ wasi_version_t wasi_get_wasi_version(const wasm_module_t *module); #endif #if defined(WASMER_COMPILER_ENABLED) -/** - * Updates the configuration to specify a particular compiler to use. - * - * This is a Wasmer-specific function. - * - * # Example - * - * ```rust,no_run - * # use inline_c::assert_c; - * # fn main() { - * # (assert_c! { - * # #include "tests/wasmer_wasm.h" - * # - * int main() { - * // Create the configuration. - * wasm_config_t* config = wasm_config_new(); - * - * // Use the Cranelift compiler. - * wasm_config_set_compiler(config, CRANELIFT); - * - * // Create the engine. - * wasm_engine_t* engine = wasm_engine_new_with_config(config); - * - * // Check we have an engine! - * assert(engine); - * - * // Free everything. - * wasm_engine_delete(engine); - * - * return 0; - * } - * # }) - * # .success(); - * # } - * ``` - */ void wasm_config_set_compiler(wasm_config_t *config, wasmer_compiler_t compiler); #endif -/** - * Updates the configuration to specify a particular engine to use. - * - * This is a Wasmer-specific function. - * - * # Example - * - * ```rust,no_run - * # use inline_c::assert_c; - * # fn main() { - * # (assert_c! { - * # #include "tests/wasmer_wasm.h" - * # - * int main() { - * // Create the configuration. - * wasm_config_t* config = wasm_config_new(); - * - * // Use the JIT engine. - * wasm_config_set_engine(config, JIT); - * - * // Create the engine. - * wasm_engine_t* engine = wasm_engine_new_with_config(config); - * - * // Check we have an engine! - * assert(engine); - * - * // Free everything. - * wasm_engine_delete(engine); - * - * return 0; - * } - * # }) - * # .success(); - * # } - * ``` - */ void wasm_config_set_engine(wasm_config_t *config, wasmer_engine_t engine); -/** - * Unstable non-standard Wasmer-specific API to get the module's - * name, otherwise `out->size` is set to `0` and `out->data` to - * `NULL`. - * - * # Example - * - * ```rust - * # use inline_c::assert_c; - * # fn main() { - * # (assert_c! { - * # #include "tests/wasmer_wasm.h" - * # - * int main() { - * // Create the engine and the store. - * wasm_engine_t* engine = wasm_engine_new(); - * wasm_store_t* store = wasm_store_new(engine); - * - * // Create a WebAssembly module from a WAT definition. - * wasm_byte_vec_t wat; - * wasmer_byte_vec_new_from_string(&wat, "(module $moduleName)"); - * // ^~~~~~~~~~~ that's the name! - * wasm_byte_vec_t wasm; - * wat2wasm(&wat, &wasm); - * - * // Create the module. - * wasm_module_t* module = wasm_module_new(store, &wasm); - * - * // Read the module's name. - * wasm_name_t name; - * wasm_module_name(module, &name); - * - * // It works! - * wasmer_assert_name(&name, "moduleName"); - * - * // Free everything. - * wasm_byte_vec_delete(&name); - * wasm_module_delete(module); - * wasm_byte_vec_delete(&wasm); - * wasm_byte_vec_delete(&wat); - * wasm_store_delete(store); - * wasm_engine_delete(engine); - * - * return 0; - * } - * # }) - * # .success(); - * # } - * ``` - */ void wasm_module_name(const wasm_module_t *module, wasm_name_t *out); -/** - * Unstable non-standard Wasmer-specific API to set the module's - * name. The function returns `true` if the name has been updated, - * `false` otherwise. - * - * # Example - * - * ```rust - * # use inline_c::assert_c; - * # fn main() { - * # (assert_c! { - * # #include "tests/wasmer_wasm.h" - * # - * int main() { - * // Create the engine and the store. - * wasm_engine_t* engine = wasm_engine_new(); - * wasm_store_t* store = wasm_store_new(engine); - * - * // Create a WebAssembly module from a WAT definition. - * wasm_byte_vec_t wat; - * wasmer_byte_vec_new_from_string(&wat, "(module)"); - * wasm_byte_vec_t wasm; - * wat2wasm(&wat, &wasm); - * - * // Create the module. - * wasm_module_t* module = wasm_module_new(store, &wasm); - * - * // Read the module's name. There is none for the moment. - * { - * wasm_name_t name; - * wasm_module_name(module, &name); - * - * assert(name.size == 0); - * } - * - * // So, let's set a new name. - * { - * wasm_name_t name; - * wasmer_byte_vec_new_from_string(&name, "hello"); - * wasm_module_set_name(module, &name); - * } - * - * // And now, let's see the new name. - * { - * wasm_name_t name; - * wasm_module_name(module, &name); - * - * // It works! - * wasmer_assert_name(&name, "hello"); - * - * wasm_byte_vec_delete(&name); - * } - * - * // Free everything. - * wasm_module_delete(module); - * wasm_byte_vec_delete(&wasm); - * wasm_byte_vec_delete(&wat); - * wasm_store_delete(store); - * wasm_engine_delete(engine); - * - * return 0; - * } - * # }) - * # .success(); - * # } - * ``` - */ bool wasm_module_set_name(wasm_module_t *module, const wasm_name_t *name); -/** - * Gets the length in bytes of the last error if any, zero otherwise. - * - * This can be used to dynamically allocate a buffer with the correct number of - * bytes needed to store a message. - * - * # Example - * - * See this module's documentation to get a complete example. - */ int wasmer_last_error_length(void); -/** - * Gets the last error message if any into the provided buffer - * `buffer` up to the given `length`. - * - * The `length` parameter must be large enough to store the last - * error message. Ideally, the value should come from - * [`wasmer_last_error_length`]. - * - * The function returns the length of the string in bytes, `-1` if an - * error occurs. Potential errors are: - * - * * The `buffer` is a null pointer, - * * The `buffer` is too small to hold the error message. - * - * Note: The error message always has a trailing NUL character. - * - * Important note: If the provided `buffer` is non-null, once this - * function has been called, regardless whether it fails or succeeds, - * the error is cleared. - * - * # Example - * - * See this module's documentation to get a complete example. - */ int wasmer_last_error_message(char *buffer, int length); -/** - * Get the version of the Wasmer C API. - * - * The `.h` files already define variables like `WASMER_VERSION*`, - * but if this file is unreachable, one can use this function to - * retrieve the full semver version of the Wasmer C API. - * - * The returned string is statically allocated. It must _not_ be - * freed! - * - * # Example - * - * See the module's documentation. - */ const char *wasmer_version(void); -/** - * Get the major version of the Wasmer C API. - * - * See [`wasmer_version`] to learn more. - * - * # Example - * - * ```rust - * # use inline_c::assert_c; - * # fn main() { - * # (assert_c! { - * # #include "tests/wasmer_wasm.h" - * # - * int main() { - * // Get and print the version components. - * uint8_t version_major = wasmer_version_major(); - * uint8_t version_minor = wasmer_version_minor(); - * uint8_t version_patch = wasmer_version_patch(); - * - * printf("%d.%d.%d", version_major, version_minor, version_patch); - * - * return 0; - * } - * # }) - * # .success() - * # .stdout( - * # format!( - * # "{}.{}.{}", - * # env!("CARGO_PKG_VERSION_MAJOR"), - * # env!("CARGO_PKG_VERSION_MINOR"), - * # env!("CARGO_PKG_VERSION_PATCH") - * # ) - * # ); - * # } - * ``` - */ uint8_t wasmer_version_major(void); -/** - * Get the minor version of the Wasmer C API. - * - * See [`wasmer_version_major`] to learn more and get an example. - */ uint8_t wasmer_version_minor(void); -/** - * Get the patch version of the Wasmer C API. - * - * See [`wasmer_version_major`] to learn more and get an example. - */ uint8_t wasmer_version_patch(void); -/** - * Get the minor version of the Wasmer C API. - * - * See [`wasmer_version_major`] to learn more. - * - * The returned string is statically allocated. It must _not_ be - * freed! - * - * # Example - * - * ```rust - * # use inline_c::assert_c; - * # fn main() { - * # (assert_c! { - * # #include "tests/wasmer_wasm.h" - * # - * int main() { - * // Get and print the pre version. - * const char* version_pre = wasmer_version_pre(); - * printf("%s", version_pre); - * - * // No need to free the string. It's statically allocated on - * // the Rust side. - * - * return 0; - * } - * # }) - * # .success() - * # .stdout(env!("CARGO_PKG_VERSION_PRE")); - * # } - * ``` - */ const char *wasmer_version_pre(void); -/** - * Parses in-memory bytes as either the WAT format, or a binary Wasm - * module. This is wasmer-specific. - * - * In case of failure, `wat2wasm` sets the `out->data = NULL` and `out->size = 0`. - * - * # Example - * - * See the module's documentation. - */ void wat2wasm(const wasm_byte_vec_t *wat, wasm_byte_vec_t *out); #ifdef __cplusplus