unikernel/duniverse/dune_/doc/reference/dune/library.rst

@@ -0,0 +1,335 @@
+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:: (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 ...))``.