| name: shared_module |
| returns: build_tgt |
| since: 0.37.0 |
| description: | |
| Builds a shared module with the given sources. |
| |
| This is useful for building modules that will be `dlopen()`ed and |
| hence may contain undefined symbols that will be provided by the |
| library that is loading it. |
| |
| If you want the shared module to be able to refer to functions and |
| variables defined in the [[executable]] it is loaded by, |
| you will need to set the `export_dynamic` argument of the executable to |
| `true`. |
| |
| notes: |
| - | |
| *Linking to a shared module on platforms other than Android is deprecated, and will be an error |
| in the future*. |
| It was previously allowed because it was the only way to have a shared-library-like target that |
| contained references to undefined symbols. However, since 0.40.0, the `override_options:` |
| [[build_target]] keyword argument can be used to create such a [[shared_library]] by passing |
| `override_options: 'b_lundef=false'`. Shared modules have other characteristics that make |
| them incompatible with linking, such as a lack of SONAME. |
| On macOS and iOS, linking to shared modules is disallowed by the linker, so we disallow it at |
| configure time. |
| On Android, if a shared module `foo` uses symbols from another shared module `bar`, `foo` must |
| also be linked to `bar`. Hence, linking one shared module to another will always be allowed when |
| building for Android. |
| |
| posargs_inherit: _build_target_base |
| varargs_inherit: _build_target_base |
| kwargs_inherit: _build_target_base |
| |
| kwargs: |
| vs_module_defs: |
| type: str | file | custom_tgt | custom_idx |
| since: 0.52.0 |
| description: | |
| Specify a Microsoft module definition file for controlling symbol exports, |
| etc., on platforms where that is possible (e.g. Windows). |
| |
| *(Since 1.3.0)* [[@custom_idx]] are supported |
| |
| rust_abi: |
| type: str |
| since: 1.3.0 |
| description: | |
| Set the specific ABI to compile (when compiling rust). |
| - 'rust' (default): Create a "dylib" crate. |
| - 'c': Create a "cdylib" crate. |