shared_module()

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.

Signature

(since 0.37.0)

# Builds a shared module with the given sources
build_tgt shared_module(
  str                                                   target_name,     # The *unique* name of the build target
  str | file | custom_tgt | custom_idx | generated_list source...,       # Input source to compile

  # Keyword arguments:
  <lang>_args                  : array[str]                                                              # compiler flags to use for the given language;
  <lang>_pch                   : str                                                                     # precompiled header file to use for the given language
  build_by_default             : bool                                                                    # Causes, when set to `true`, to have this target be built by default
  build_rpath                  : str                                                                     # A string to add to target's rpath definition in the build dir,
  build_subdir                 : str                                                                     # Places the build results in a subdirectory of the given name rather than directly into the build directory
  d_debug                      : array[str]                                                              # The [D version identifiers](https://dlang
  d_import_dirs                : array[inc | str]                                                        # the directories to add to the string search path (i
  d_module_versions            : array[str | int]                                                        # List of module version identifiers set when compiling D sources
  d_unittest                   : bool                                                                    # When set to true, the D modules are compiled in debug mode
  dependencies                 : array[dep]                                                              # one or more dependency objects
  extra_files                  : str | file                                                              # Not used for the build itself but are shown as source files in IDEs
  gnu_symbol_visibility        : str                                                                     # Specifies how symbols should be exported, see
  gui_app                      : bool                                                                    # When set to true flags this target as a GUI application
  implicit_include_directories : bool                                                                    # Controls whether Meson adds the current source and build directories to the include path
  include_directories          : array[inc | str]                                                        # one or more objects created with the include_directories() function,
  install                      : bool                                                                    # When set to true, this executable should be installed
  install_dir                  : str                                                                     # override install directory for this file
  install_mode                 : array[str | int]                                                        # Specify the file mode in symbolic format
  install_rpath                : str                                                                     # A string to set the target's rpath to after install
  install_tag                  : str                                                                     # A string used by the `meson install --tags` command
  link_args                    : array[str]                                                              # Flags to use during linking
  link_depends                 : str | file | custom_tgt | custom_idx                                    # Strings, files, or custom targets the link step depends on
  link_language                : str                                                                     # Makes the linker for this target be for the specified language
  link_whole                   : array[lib | custom_tgt | custom_idx]                                    # Links all contents of the given static libraries whether they are used or
  link_with                    : array[lib | custom_tgt | custom_idx]                                    # One or more shared or static libraries
  name_prefix                  : str | array[void]                                                       # The string that will be used as the prefix for the
  name_suffix                  : str | array[void]                                                       # The string that will be used as the extension for the
  native                       : bool                                                                    # Controls whether the target is compiled for the build or host machines
  objects                      : array[extracted_obj | file | str]                                       # List of object files that should be linked in this target
  override_options             : array[str] | dict[str | bool | int | array[str]]                          # takes an array of strings in the same format as `project`'s `default_options`
  rust_abi                     : str                                                                     # Set the specific ABI to compile (when compiling rust)
  rust_crate_type              : str                                                                     # Set the specific type of rust crate to compile (when compiling rust)
  rust_dependency_map          : dict[str]                                                               # On rust targets this allows giving custom names to the crates that are
  sources                      : str | file | custom_tgt | custom_idx | generated_list | structured_src  # Additional source files
  vala_args                    : array[str | file]                                                       # Compiler flags for Vala
  vala_gir                     : str                                                                     # If set, generates a GIR file with the given name
  vala_header                  : str                                                                     # On Vala targets, this provides a way to override the name of the generated
  vala_vapi                    : str                                                                     # On Vala targets, this provides a way to override the name of the generated
  vs_module_defs               : str | file | custom_tgt | custom_idx                                    # Specify a Microsoft module definition file for controlling symbol exports,
  win_subsystem                : str                                                                     # Specifies the subsystem type to use
)

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.

Arguments

The function shared_module() accepts the following positional arguments:

Name	Type	Description	Tags
`target_name`	`str`	The unique name of the build target

Additionally, the function accepts between 0 and infinity variadic arguments (source...) of type str | file | custom_tgt | custom_idx | generated_list.

Input source to compile. The following types are supported:

Strings relative to the current source directory
file objects defined in any preceding build file
The return value of configure-time generators such as configure_file()
The return value of build-time generators such as custom_target() or generator.process()

These input files can be sources, objects, libraries, or any other file. Meson will automatically categorize them based on the extension and use them accordingly. For instance, sources (.c, .cpp, .vala, .rs, etc) will be compiled and objects (.o, .obj) and libraries (.so, .dll, etc) will be linked.

With the Ninja backend, Meson will create a build-time order-only dependency on all generated input files, including unknown files. This is needed to bootstrap the generation of the real dependencies in the depfile generated by your compiler to determine when to rebuild sources. Ninja relies on this dependency file for all input files, generated and non-generated. The behavior is similar for other backends.

Finally, shared_module() accepts the following keyword arguments:

Name	Type	Description	Tags
`<lang>_args`	`array`[`str`]	compiler flags to use for the given language; eg: `cpp_args` for C++
`<lang>_pch`	`str`	precompiled header file to use for the given language
`build_by_default`	`bool`	Causes, when set to `true`, to have this target be built by default. This means it will be built when `meson compile` is called without any arguments. The default value is `true` for all built target types.	(since 0.38.0) `default = true`
`build_rpath`	`str`	A string to add to target's rpath definition in the build dir, but which will be removed on install	(since 0.42.0)
`build_subdir`	`str`	Places the build results in a subdirectory of the given name rather than directly into the build directory. This does not affect the install directory, which uses install_dir. This allows inserting a directory name into the build path, either when needed to use the build result while building other targets or as a way to support multiple targets with the same basename by using unique build_subdir values for each one. To prevent collisions within the build directory, build_subdir is not allowed to match a file or directory in the source directory, nor contain '..' to refer to the parent of the build directory.	(since 1.10.0)
`d_debug`	`array`[`str`]	The D version identifiers to add during the compilation of D source files.
`d_import_dirs`	`array`[`inc` \| `str`]	the directories to add to the string search path (i.e. `-J` switch for DMD). Must be `inc` objects or plain strings.	(since 0.62.0)
`d_module_versions`	`array`[`str` \| `int`]	List of module version identifiers set when compiling D sources.
`d_unittest`	`bool`	When set to true, the D modules are compiled in debug mode.	`default = false`
`dependencies`	`array`[`dep`]	one or more dependency objects created with `dependency()` or `compiler.find_library()` (for external deps) or `declare_dependency()` (for deps built by the project)
`extra_files`	`str` \| `file`	Not used for the build itself but are shown as source files in IDEs that group files by targets (such as Visual Studio). These may only be static sources.
`gnu_symbol_visibility`	`str`	Specifies how symbols should be exported, see e.g the GCC Wiki for more information. This value can either be an empty string or one of `default`, `internal`, `hidden`, `protected` or `inlineshidden`, which is the same as `hidden` but also includes things like C++ implicit constructors as specified in the GCC manual. Ignored on compilers that do not support GNU visibility arguments. See also `snippets.symbol_visibility_header()` method to help with defining public API.	(since 0.48.0)
`gui_app`	`bool`	When set to true flags this target as a GUI application on platforms where this makes a difference, deprecated since 0.56.0, use `win_subsystem` instead.	DEPRECATED in 0.56.0 `default = false`
`implicit_include_directories`	`bool`	Controls whether Meson adds the current source and build directories to the include path	(since 0.42.0) `default = true`
`include_directories`	`array`[`inc` \| `str`]	one or more objects created with the `include_directories()` function, or (since 0.50.0) strings, which will be transparently expanded to include directory objects
`install`	`bool`	When set to true, this executable should be installed.	`default = false`
`install_dir`	`str`	override install directory for this file. If the value is a relative path, it will be considered relative the `prefix` option. For example, if you want to install plugins into a subdir, you'd use something like this: `install_dir : get_option('libdir') / 'projectname-1.0'`.
`install_mode`	`array`[`str` \| `int`]	Specify the file mode in symbolic format and optionally the owner/uid and group/gid for the installed files. See the `install_mode` kwarg of `install_data()` for more information.	(since 0.47.0)
`install_rpath`	`str`	A string to set the target's rpath to after install (but not before that). On Windows, this argument has no effect.
`install_tag`	`str`	A string used by the `meson install --tags` command to install only a subset of the files. By default all build targets have the tag `runtime` except for static libraries that have the `devel` tag.	(since 0.60.0)
`link_args`	`array`[`str`]	Flags to use during linking. You can use UNIX-style flags here for all platforms.
`link_depends`	`str` \| `file` \| `custom_tgt` \| `custom_idx`	Strings, files, or custom targets the link step depends on such as a symbol visibility map. The purpose is to automatically trigger a re-link (but not a re-compile) of the target when this file changes.
`link_language`	`str`	Makes the linker for this target be for the specified language. It is generally unnecessary to set this, as Meson will detect the right linker to use in most cases. There are only two cases where this is needed. One, your main function in an executable is not in the language Meson picked, or second you want to force a library to use only one ABI. (broken until 0.55.0)	(since 0.51.0)
`link_whole`	`array`[`lib` \| `custom_tgt` \| `custom_idx`]	Links all contents of the given static libraries whether they are used or not, equivalent to the `-Wl,--whole-archive` argument flag of GCC, or the '/WHOLEARCHIVE' MSVC linker option. This allows the linked target to re-export symbols from all objects in the static libraries. (since 0.41.0) If passed an array that array will be flattened. (since 0.51.0) This argument also accepts outputs produced by custom targets. The user must ensure that the output is a library in the correct format.	(since 0.40.0)
`link_with`	`array`[`lib` \| `custom_tgt` \| `custom_idx`]	One or more shared or static libraries (built by this project) that this target should be linked with. (since 0.41.0) If passed an array that array will be flattened. (since 0.51.0) The arguments can also be custom targets. In this case Meson will assume that merely adding the output file in the linker command line is sufficient to make linking work. If this is not sufficient, then the build system writer must write all other steps manually.
`name_prefix`	`str` \| `array`[`void`]	The string that will be used as the prefix for the target output filename by overriding the default (only used for libraries). By default this is `lib` on all platforms and compilers, except for MSVC shared libraries where it is omitted to follow convention, and Cygwin shared libraries where it is `cyg`. Set this to `[]`, or omit the keyword argument for the default behaviour.
`name_suffix`	`str` \| `array`[`void`]	The string that will be used as the extension for the target by overriding the default. By default on Windows this is `exe` for executables and on other platforms it is omitted. For shared libraries, the default value is `dylib` on macOS, `dll` on Windows, and `so` everywhere else. For static libraries, it is `a` everywhere. By convention MSVC static libraries use the `lib` suffix, but we use `a` to avoid a potential name clash with shared libraries which also generate import libraries with a `lib` suffix. Set this to `[]`, or omit the keyword argument for the default behaviour.
`native`	`bool`	Controls whether the target is compiled for the build or host machines.	`default = false`
`objects`	`array`[`extracted_obj` \| `file` \| `str`]	List of object files that should be linked in this target. Since 1.1.0 this can include generated files in addition to object files that you don't have source to or that object files produced by other build targets. In earlier release, generated object files had to be placed in `sources`.
`override_options`	`array`[`str`] \| `dict`[`str` \| `bool` \| `int` \| `array`[`str`]]	takes an array of strings in the same format as `project`'s `default_options` overriding the values of these options for this target only. (since 1.2.0): A dictionary may now be passed.	(since 0.40.0)
`rust_abi`	`str`	Set the specific ABI to compile (when compiling rust). 'rust' (default): Create a "dylib" crate. 'c': Create a "cdylib" crate.	(since 1.3.0)
`rust_crate_type`	`str`	Set the specific type of rust crate to compile (when compiling rust). If the target is an `executable()` this defaults to "bin", the only allowed value. If it is a `static_library()` it defaults to "lib", and may be "lib", "staticlib", or "rlib". If "lib" then Rustc will pick a default, "staticlib" means a C ABI library, "rlib" means a Rust ABI. If it is a `shared_library()` it defaults to "lib", and may be "lib", "dylib", "cdylib", or "proc-macro". If "lib" then Rustc will pick a default, "cdylib" means a C ABI library, "dylib" means a Rust ABI, and "proc-macro" is a special rust procedural macro crate. "proc-macro" is new in 0.62.0. Since 1.3.0 this is deprecated and replaced by "rust_abi" keyword argument. `proc_macro` crates are now handled by the `rust.proc_macro()` method.	(since 0.42.0) DEPRECATED in 1.3.0
`rust_dependency_map`	`dict`[`str`]	On rust targets this allows giving custom names to the crates that are linked into the target. For example, passing a dependency map of `{ 'gtk4': 'gtk' }` has the same effect of writing `gtk.package = "gtk4"` in the `dependencies` section of a Cargo.toml file, or `extern crate gtk4 as gtk` inside Rust code. Since 1.10.0, the keys can be either crate names or target names.	(since 1.2.0)
`sources`	`str` \| `file` \| `custom_tgt` \| `custom_idx` \| `generated_list` \| `structured_src`	Additional source files. Same as the source varargs.
`vala_args`	`array`[`str` \| `file`]	Compiler flags for Vala. Unlike other languages this may contain Files
`vala_gir`	`str`	If set, generates a GIR file with the given name. If this is unset then no GIR file will be generated.
`vala_header`	`str`	On Vala targets, this provides a way to override the name of the generated C compatible header for targets that generate them. If it is not set the default will be calculated from the target's name.
`vala_vapi`	`str`	On Vala targets, this provides a way to override the name of the generated VAPI file. If it is not set the default will be calculated from the target's name.
`vs_module_defs`	`str` \| `file` \| `custom_tgt` \| `custom_idx`	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	(since 0.52.0)
`win_subsystem`	`str`	Specifies the subsystem type to use on the Windows platform. Typical values include `console` for text mode programs and `windows` for gui apps. The value can also contain version specification such as `windows,6.0`. See MSDN documentation for the full list.	(since 0.56.0) `default = 'console'`

The results of the search are

Edit on GitHub