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 is deprecated, and will be an error in the future*.
   It used to be 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]], and shared
   modules have other characteristics that make them incompatible with linking, such as a lack of
   SONAME. Linking to shared modules also does not work on some platforms, such as on macOS / iOS.

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).