335 lines
13 KiB
ReStructuredText
335 lines
13 KiB
ReStructuredText
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 ...))``.
|