library ------- The ``library`` stanza must be used to describe OCaml libraries. The format of library stanzas is as follows: .. code:: dune (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. ```` are: .. describe:: (public_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 ) 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 ``.__private__.``; however, the library's interface will be hidden from consumers outside the project. .. describe:: (synopsis ) A one-line description of the library. This is used by tools that list installed libraries. .. describe:: (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 )`` field. ```` 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 )`` and variables such as ``%{read-lines:}`` 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 ) Specifies the library's dependencies. See :doc:`/reference/library-dependencies` for more details. .. describe:: (wrapped ) 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 )) 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 ````. .. describe:: (preprocess ) 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 ()) 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 ) 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 ) 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 ()) 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 ()) 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 )`` and ``(glob_files )`` 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 ) 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 ) 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 )``, where ```` is a list of pairs ``( )`` with ```` being the cookie name and ```` 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 ()) 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 ()) 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 ()) A list of flags passed to ``ocamlc`` and ``ocamlopt`` when building the library archive files. You can use this to specify ``-linkall``, for instance. ```` is a list of strings supporting :doc:`/concepts/variables`. .. describe:: (c_library_flags ) Specifies the flags passed to the C compiler when constructing the library archive file for the C stubs. ```` 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 ) 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, ```` still needs to be added in ``modules``. .. describe:: (private_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, ```` 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 ) 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 )``. See :ref:`inline_tests` for a reference of corresponding options. .. describe:: (root_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 ) 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 ...))``.