| 1 |
name: shared_module |
| 2 |
returns: build_tgt |
| 3 |
since: 0.37.0 |
| 4 |
description: | |
| 5 |
Builds a shared module with the given sources. |
| 6 |
|
| 7 |
This is useful for building modules that will be `dlopen()`ed and |
| 8 |
hence may contain undefined symbols that will be provided by the |
| 9 |
library that is loading it. |
| 10 |
|
| 11 |
If you want the shared module to be able to refer to functions and |
| 12 |
variables defined in the [[executable]] it is loaded by, |
| 13 |
you will need to set the `export_dynamic` argument of the executable to |
| 14 |
`true`. |
| 15 |
|
| 16 |
notes: |
| 17 |
- | |
| 18 |
*Linking to a shared module on platforms other than Android is deprecated, and will be an error |
| 19 |
in the future*. |
| 20 |
It was previously allowed because it was the only way to have a shared-library-like target that |
| 21 |
contained references to undefined symbols. However, since 0.40.0, the `override_options:` |
| 22 |
[[build_target]] keyword argument can be used to create such a [[shared_library]] by passing |
| 23 |
`override_options: 'b_lundef=false'`. Shared modules have other characteristics that make |
| 24 |
them incompatible with linking, such as a lack of SONAME. |
| 25 |
On macOS and iOS, linking to shared modules is disallowed by the linker, so we disallow it at |
| 26 |
configure time. |
| 27 |
On Android, if a shared module `foo` uses symbols from another shared module `bar`, `foo` must |
| 28 |
also be linked to `bar`. Hence, linking one shared module to another will always be allowed when |
| 29 |
building for Android. |
| 30 |
|
| 31 |
posargs_inherit: _build_target_base |
| 32 |
varargs_inherit: _build_target_base |
| 33 |
kwargs_inherit: _build_target_base |
| 34 |
|
| 35 |
kwargs: |
| 36 |
vs_module_defs: |
| 37 |
type: str | file | custom_tgt | custom_idx |
| 38 |
since: 0.52.0 |
| 39 |
description: | |
| 40 |
Specify a Microsoft module definition file for controlling symbol exports, |
| 41 |
etc., on platforms where that is possible (e.g. Windows). |
| 42 |
|
| 43 |
*(Since 1.3.0)* [[@custom_idx]] are supported |
| 44 |
|
| 45 |
rust_abi: |
| 46 |
type: str |
| 47 |
since: 1.3.0 |
| 48 |
description: | |
| 49 |
Set the specific ABI to compile (when compiling rust). |
| 50 |
- 'rust' (default): Create a "dylib" crate. |
| 51 |
- 'c': Create a "cdylib" crate. |