Foreign Stubs
-------------

You can specify foreign sources using the ``foreign_stubs`` field of the
``library`` and ``executable`` stanzas. For example:

.. code:: dune

    (library
     (name lib)
     (foreign_stubs (language c) (names src1 src2))
     (foreign_stubs (language cxx) (names src3) (flags -O2)))

Here we declare an OCaml library ``lib``, which contains two C sources
``src1`` and ``src2``, and one C++ source, ``src3``, which need to be
compiled with ``-O2``. These source files will be compiled and packaged
with the library, along with the link-time flags to be used when
linking the final executables. When matching ``names`` to source files,
Dune treats ``*.c`` files as C sources, and ``*.cpp``, ``*.cc``, and
``*.cxx`` files as C++ sources.

Here is a complete list of supported subfields:

- ``language`` specifies the source language, where ``c`` means C and
  ``cxx`` means C++. In the future, more languages may be supported.
- ``names`` specifies the *names* of source files. When specifying a source
  file, omit the extension and any relative parts of the path;
  Dune will scan all library directories to find all matching files and
  raise an error if multiple source files map to the same object name.
  If you need to have multiple object files with the same name, you can
  package them into different :doc:`foreign-archives` via the
  ``foreign_archives`` field. This field uses the :doc:`ordered-set-language`
  where the ``:standard`` value corresponds to the set of names of all source
  files whose extensions match the specified ``language``.
- ``flags`` are passed when compiling source files. This field is specified
  using the :doc:`ordered-set-language`, where the ``:standard`` value comes
  from the environment settings ``c_flags`` and ``cxx_flags``, respectively.
  Note that, for C stubs, Dune unconditionally adds the flags present in the
  OCaml config fields ``ocamlc_cflags`` and ``ocamlc_cppflags`` to the compiler
  command line. This behavior can be disabled since Dune 2.8 via the
  ``dune-project`` option :doc:`dune-project/use_standard_c_and_cxx_flags`.
- ``include_dirs`` are tracked as dependencies and passed to the compiler
  via the ``-I`` flag. You can use :doc:`../concepts/variables` in this field
  and refer to a library source directory using the ``(lib library-name)``
  syntax.
  Additionally, the syntax ``(include filename)`` can be used to specify a file
  containing additional arguments to ``(include_dirs ...)``. The named file can
  either contain a single path to be added to this list of include directories,
  or an S-expression listing additional ``(include_dirs ...)`` arguments (the
  ``(lib ...)`` and ``(include ...)`` syntax is also supported in files included
  in this way).
  For example, ``(include_dirs dir1 (lib lib1) (lib lib2) (include inc1) dir2)`` specifies
  the directory ``dir1``, the source directories of ``lib1``, and ``lib2``,
  the list of directories contained in the file ``inc1``,
  and the directory ``dir2``, in this order.
  Some examples of possible contents of the file ``inc1`` are:

  - ``dir3`` which would add ``dir3`` to the list of include directories
  - ``((lib lib3) dir4 (include inc2))`` which would add the source directory of
    the library ``lib3``, the directory ``dir4``, and the result of recursively
    including the contents of the file ``inc2``.
    The contents of included directories are tracked recursively, e.g., if you
    use ``(include_dir dir)`` and have headers ``dir/base.h`` and
    ``dir/lib/lib.h``, they both will be tracked as dependencies.
- ``extra_deps`` specifies any other dependencies that should be tracked.  This
    is useful when dealing with ``#include`` statements that escape into a
    parent directory like ``#include "../a.h"``.


Mode-Dependent Stubs
^^^^^^^^^^^^^^^^^^^^

Since Dune 3.5, it is possible to use different foreign stubs when building in
`native` or `byte` mode. This feature needs to be activated by adding ``(using
mode_specific_stubs 0.1)`` in the ``dune-project`` file.

Then it is allowed to use the ``mode`` field when describing ``foreign_stubs``.
If the same stub is defined twice, Dune will automatically chose the correct one.
This allows the use of different sets of flags or even different source files
from which the stubs are built.

.. code:: dune

  (executable
   (name main)
   (modes native byte_complete)
   (foreign_stubs
     (language c)
     (mode byte)
     (names c_stubs))
   (foreign_stubs
     (language c)
     (mode native)
     (flags :standard -DNATIVE_CODE) ; A flag specific to native builds
     (names c_stubs)))  ; This could be the name of an implementation
                        ; specific to native builds

Note that, as of version ``0.1`` of this extension, this mechanism does not work for ``foreign_archives``.