library
-------

The ``library`` stanza must be used to describe OCaml libraries. The format of
library stanzas is as follows:

.. code:: dune

    (library
     (name <library-name>)
     <optional-fields>)

``<library-name>`` is the real name of the library. It determines the names of
the archive files generated for the library as well as the module name under
which the library will be available, unless ``(wrapped false)`` is used (see
below). It must be a valid OCaml module name, but it doesn't need to start with
an uppercase letter.

For instance, the modules of a library named ``foo`` will be available as
``Foo.XXX``, outside of ``foo`` itself; however, it is allowed to write an
explicit ``Foo`` module, which will be the library interface. You are free to
expose only the modules you want.

Please note: by default, libraries and other things that consume OCaml/Reason
modules only consume modules from the directory where the stanza appear. In
order to declare a multi-directory library, you need to use the
:doc:`include_subdirs` stanza.

``<optional-fields>`` are:

.. describe:: (public_name <name>)

   The name under which the library can be referred as a dependency when it's
   not part of the current workspace, i.e., when it's installed. Without a
   ``(public_name ...)`` field, the library won't be installed by Dune. The
   public name must start with the package name it's part of and optionally
   followed by a dot, then anything else you want. The package name must also
   be one of the packages that Dune knows about, as determined by the logic
   described in :doc:`/reference/packages`.

.. describe:: (package <package>)

   Installs a private library under the specified package. Such a library is
   now usable by public libraries defined in the same project. The Findlib name
   for this library will be ``<package>.__private__.<name>``; however, the
   library's interface will be hidden from consumers outside the project.

.. describe:: (synopsis <string>)

   A one-line description of the library. This is used by tools that list
   installed libraries.

.. describe:: (modules <modules>)

   Specifies what modules are part of the library. By default, Dune will use
   all the ``.ml/.re`` files in the same directory as the ``dune`` file. This
   includes ones present in the file system as well as ones generated by user
   rules. You can restrict this list by using a ``(modules <modules>)`` field.

   ``<modules>`` uses the :doc:`/reference/ordered-set-language`, where
   elements are module names and don't need to start with an uppercase letter.
   For instance, to exclude module ``Foo``, use ``(modules (:standard \
   foo))``.

   Starting in Dune 3.13, one can also use special forms ``(:include <file>)``
   and variables such as ``%{read-lines:<file>}`` in this field to customize
   the list of modules using Dune rules. The dependencies introduced in this
   way *must live in a different directory that the stanza making use of them*.

.. describe:: (libraries <library-dependencies>)

   Specifies the library's dependencies.

   See :doc:`/reference/library-dependencies` for more details.

.. describe:: (wrapped <boolean>)

   Specifies whether the library modules should be available only through the
   top-level library module, or if they should all be exposed at the top level.

   The default is ``true``, and it's highly recommended to keep it this way.
   Because OCaml top-level modules must all be unique when linking an
   executables, polluting the top-level namespace will make your library
   unusable with other libraries if there is a module name clash.

   This option is only intended for libraries that manually prefix all their
   modules by the library name and to ease porting of existing projects to
   Dune.

.. describe:: (wrapped (transition <message>))

   This is the same as ``(wrapped true)``, except it will also generate
   unwrapped (not prefixed by the library name) modules to preserve
   compatibility.

   This is useful for libraries that would like to transition from ``(wrapped
   false)`` to ``(wrapped true)`` without breaking compatibility for users. The
   deprecation notices for the unwrapped modules will include ``<message>``.

.. describe:: (preprocess <preprocess-spec>)

   Specifies how to preprocess files when needed.

   The default is ``no_preprocessing``, and other options are described
   in :doc:`/reference/preprocessing-spec`.

.. describe:: (preprocessor_deps (<deps-conf list>))

   Specifies extra preprocessor dependencies preprocessor, i.e., if the
   preprocessor reads a generated file.

   The specification of dependencies is described in
   :doc:`/concepts/dependency-spec`.

.. describe:: (optional)

   If present, it indicates that the library should only be built and installed
   if all the dependencies are available, either in the workspace or in the
   installed world.

   Use this to provide extra features without adding hard dependencies to your
   project.

.. describe:: (foreign_stubs <foreign-stubs-spec>)

   Specifies foreign source files, e.g., C or C++ stubs, to be compiled and
   packaged together with the library.

   See the section :doc:`/reference/foreign-stubs` for more details.

   This field replaces the now-deleted fields ``c_names``, ``c_flags``,
   ``cxx_names``, and ``cxx_flags``.

.. describe:: (foreign_archives <foreign-archives-list>)

   Specifies archives of foreign object files to be packaged with the library.

   See the section :doc:`/reference/foreign-archives` for more details. This
   field replaces the now-deleted field ``self_build_stubs_archive``.

.. describe:: (install_c_headers (<names>))

   If your library has public C header files that must be installed, you must
   list them in this field, without the ``.h`` extension.

   You should favor the ``public_headers`` field starting from 3.8.

.. describe:: (public_headers (<files>))

   If your library has public C header files that must be installed, you must
   list them in this field. This field accepts globs in the form of
   ``(glob_files_rec <glob>)`` and ``(glob_files <glob>)`` fields to specify
   multiple files.

   The advantage of this field over ``install_c_headers`` is that it preserves
   the directory structures of the headers relative to the library stanza.
   Additionally, it allows to specify the extensions of the header files, which
   allows alternative extensions such as ``.hh`` or ``.hpp``.

.. describe:: (modes <modes>)

   List modes which should be built by default.

   The most common use for this feature is to disable native compilation when
   writing libraries for the OCaml toplevel.

   The following modes are available: ``byte``, ``native`` and ``best``.
   ``best`` is ``native`` or ``byte`` when native compilation isn't available.

.. describe:: (no_dynlink)

   Disables (native) dynamic linking of the library. This means that the
   ``.cmxs`` archive of the library will neither be built nor installed.

   This is for advanced use only. By default, you shouldn't set this option.

.. describe:: (kind <kind>)

   Sets the type of library.

   The default is ``normal``, but other available choices are ``ppx_rewriter``
   and ``ppx_deriver``.

   They must be set when the library is intended to be used as a PPX rewriter
   or a ``[@@deriving ...]`` plugin. The reason ``ppx_rewriter`` and
   ``ppx_deriver`` are split is historical, and hopefully we won't need two
   options soon.

   Both PPX kinds support an optional field: ``(cookies <cookies>)``, where
   ``<cookies>`` is a list of pairs ``(<name> <value>)`` with ``<name>`` being
   the cookie name and ``<value>`` a string that supports
   :doc:`/concepts/variables` evaluated by each preprocessor invocation (note:
   libraries that share cookies with the same name should agree on their
   expanded value).

.. describe:: (ppx_runtime_libraries (<library-names>))

   This field is for when the library is a ``ppx rewriter`` or a ``[@@deriving
   ...]`` plugin, and has runtime dependencies.

   You need to specify these runtime dependencies here.

.. describe:: (virtual_deps (<opam-packages>))

   Sometimes opam packages enable a specific feature only if another package is
   installed. For instance, the case of ``ctypes`` will only install
   ``ctypes.foreign`` if the dummy ``ctypes-foreign`` package is installed.

   You can specify such virtual dependencies here, but you don't need to do so
   unless you use Dune to synthesize the ``depends`` and ``depopts`` sections
   of your opam file.

.. describe:: (implements <name>)

   ``name`` defines the name of the virtual library or the parameter library you
   are implementing.

   See :doc:`/virtual-libraries` or :doc:`/reference/dune/library_parameter`.

.. describe:: (parameters <library-parameter-names>)

   List the library parameters used by the library and its dependencies.

   This feature is experimental and requires the compiler you are using to
   support parameterised libraries.
   See :doc:`/reference/dune/library_parameter`.

.. describe:: (js_of_ocaml ...)

   Sets options for JavaScript compilation, see :ref:`jsoo-field`.

.. describe:: (wasm_of_ocaml ...)

   Sets options for JavaScript compilation, see :ref:`wasmoo-field`.

.. describe:: (flags ...)

   See :doc:`/concepts/ocaml-flags`.

.. describe:: (ocamlc_flags ...)

   See :doc:`/concepts/ocaml-flags`.

.. describe:: (ocamlopt_flags ...)

   See :doc:`/concepts/ocaml-flags`.

.. describe:: (library_flags (<flags>))

   A list of flags passed to ``ocamlc`` and ``ocamlopt`` when building the
   library archive files.

   You can use this to specify ``-linkall``, for instance.

   ``<flags>`` is a list of strings supporting :doc:`/concepts/variables`.

.. describe:: (c_library_flags <flags>)

   Specifies the flags passed to the C compiler when constructing the library
   archive file for the C stubs.

   ``<flags>`` uses the :doc:`/reference/ordered-set-language` and supports
   ``(:include ...)`` forms.

   When you write bindings for a C library named ``bar``, you should typically
   write ``-lbar`` here, or whatever flags are necessary to link against this
   library.

.. describe:: (modules_without_implementation <modules>)

   Specifies a list of modules that have only a ``.mli`` or ``.rei`` but no ``.ml`` or ``.re`` file.

   Such modules are usually referred as *mli only modules*. They are not
   officially supported by the OCaml compiler; however, they are commonly used.
   Such modules must only define types.

   Since it isn't reasonably possible for Dune to check this is the case, Dune
   requires the user to explicitly list such modules to avoid surprises.

   Note that the ``modules_without_implementation`` field isn't merged in
   ``modules``, which represents the total set of modules in a library. If a
   directory has more than one stanza, and thus a ``modules`` field must be
   specified, ``<modules>`` still needs to be added in ``modules``.

.. describe:: (private_modules <modules>)

   Specifies a list of modules that will be marked as private.

   Private modules are inaccessible from outside the libraries they are defined
   in.

   Note that the ``private_modules`` field is not merged in ``modules``, which
   represents the total set of modules in a library. If a directory has more
   than one stanza and thus a ``modules`` field must be specified,
   ``<modules>`` still need to be added in ``modules``.

.. describe:: (allow_overlapping_dependencies)

   Allows external dependencies to overlap with libraries that are present in
   the workspace.

.. describe:: (enabled_if <blang expression>)

   Conditionally disables a library.

   A disabled library cannot be built and will not be installed.

   The condition is specified using the :doc:`/reference/boolean-language`, and
   the field allows for the ``%{os_type}`` variable, which is expanded to the
   type of OS being targeted by the current build. Its value is the same as the
   value of the ``os_type`` parameter in the output of ``ocamlc -config``.

.. describe:: (inline_tests)

   Enables inline tests for this library.

   They can be configured through options using ``(inline_tests <options>)``.

   See :ref:`inline_tests` for a reference of corresponding options.

.. describe:: (root_module <module>)

   This field instructs Dune to generate a module that will contain module
   aliases for every library specified in dependencies.

   This is useful whenever a library is shadowed by a local module. The library
   may then still be accessible via this root module.

.. describe:: (ctypes <ctypes field>)

   Instructs Dune to use ctypes stubgen to process your type and function
   descriptions for binding system libraries, vendored libraries, or other
   foreign code.

   See :ref:`ctypes-stubgen` for a full reference.

   This field is available since the 3.0 version of the Dune language.

.. describe:: (empty_module_interface_if_absent)

   Causes the generation of empty interfaces for every module that does not
   have an interface file already.

   Useful when modules are used solely for their side-effects. This field is
   available since the 3.0 version of the Dune language.

Note that when binding C libraries, Dune doesn't provide special support for
tools such as ``pkg-config``; however, it integrates easily with
:ref:`configurator` by using ``(c_flags (:include ...))`` and ``(c_library_flags
(:include ...))``.
