doc: split foreign.rst (ocaml#10718)

Signed-off-by: Etienne Millon <[email protected]>

doc/concepts/variables.rst

@@ -30,8 +30,8 @@ Dune supports the following variables:
   the value of ``workspace_root`` isn't constant and depends on
   whether your project is vendored or not.
 -  ``cc`` is the C compiler command line (list made of the compiler
-   name followed by its flags) that will be used to compile foreign code.
-   For more details about its content, please see :ref:`this section <flags-flow>`.
+   name followed by its flags) that will be used to compile foreign code. For
+   more details about its content, please see :doc:`/reference/foreign-flags`.
 -  ``cxx`` is the C++ compiler command line being used in the
    current build context.
 -  ``ocaml_bin`` is the path where ``ocamlc`` lives.

doc/foreign-code.rst

@@ -31,7 +31,8 @@ Adding C/C++ Stubs to an OCaml Library
 ======================================
 
 To add C stubs to an OCaml library, simply list the C files without the ``.c``
-extension in the :ref:`foreign-stubs` field. For instance:
+extension in the :doc:`(foreign_stubs) </reference/foreign-stubs>` field. For
+instance:
 
 .. code:: dune
 
@@ -322,7 +323,8 @@ To do that, follow the following procedure:
     should appear, otherwise the dynamic linking of the C library will be
     attempted. However, this usually fails because the ``libfoo.so`` isn't available at
     the time of the execution.
-- *Attach* the C archive files to an OCaml library via :ref:`foreign-archives`.
+- *Attach* the C archive files to an OCaml library via
+  :doc:`/reference/foreign-archives`.
 
 For instance, let's assume that you want to build a C library
 ``libfoo`` using ``libfoo``'s own build system and attach it to an

doc/reference/dune-project/use_standard_c_and_cxx_flags.rst

@@ -22,3 +22,5 @@ use_standard_c_and_cxx_flags
    completed or overridden using the :doc:`/reference/ordered-set-language`.
 
    This is the default in the language version 3.0.
+
+   .. seealso:: :doc:`/reference/foreign-flags`

doc/reference/dune/executable.rst

@@ -114,11 +114,11 @@ files for executables. See
 
 - ``(foreign_stubs <foreign-stubs-spec>)`` specifies foreign source files, e.g.,
   C or C++ stubs, to be linked into the executable. See
-  :doc:`/reference/foreign` for more details.
+  :doc:`/reference/foreign-stubs` for more details.
 
 - ``(foreign_archives <foreign-archives-list>)`` specifies archives of foreign
   object files to be linked into the executable. See the section
-  :ref:`foreign-archives` for more details.
+  :doc:`/reference/foreign-archives` for more details.
 
 - ``(forbidden_libraries <libraries>)`` ensures that the given libraries are not
   linked in the resulting executable. If they end up being pulled in, either

doc/reference/dune/foreign_library.rst

@@ -3,4 +3,5 @@ foreign_library
 
 The ``foreign_library`` stanza describes archives of separately compiled foreign
 object files that can be packaged with an OCaml library or linked into an OCaml
-executable. See :doc:`/reference/foreign` for further details and examples.
+executable. See :doc:`/reference/foreign-archives` for further details and
+examples.

doc/reference/dune/library.rst

@@ -126,7 +126,7 @@ order to declare a multi-directory library, you need to use the
    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` for more details.
+   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``.
@@ -135,8 +135,8 @@ order to declare a multi-directory library, you need to use the
 
    Specifies archives of foreign object files to be packaged with the library.
 
-   See the section :ref:`foreign-archives` for more details. This field
-   replaces the now-deleted field ``self_build_stubs_archive``.
+   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>))
 

doc/reference/extra-objects.rst

@@ -0,0 +1,30 @@
+Extra Objects
+-------------
+
+It's possible to specify native object files to be packaged with OCaml
+libraries or linked into OCaml executables. Do this by using the
+``extra_objects`` field of the ``library`` or ``executable`` stanzas.
+For example:
+
+.. code:: dune
+
+    (executable
+     (public_name main)
+     (extra_objects foo bar))
+
+    (rule
+     (targets foo.o bar.o)
+     (deps foo.c bar.c)
+     (action (run ocamlopt %{deps})))
+
+This example builds an executable which is linked against a pair of native
+object files, ``foo.o`` and ``bar.o``. The ``extra_objects`` field takes a list
+of object names, which correspond to the object file names with their path and
+extension omitted (in contrast, ``(rule)`` manipulates file names, so the
+extension needs to be provided).
+
+In this example, the sources corresponding to the objects (``foo.c`` and
+``bar.c``)  are assumed to be present in the same directory as the OCaml source
+code, and a custom ``rule`` is used to compile the C source code into object
+files using ``ocamlopt``. This is not necessary; one can instead compile foreign
+object files manually and place them next to the OCaml source code.

doc/reference/foreign-archives.rst

@@ -0,0 +1,49 @@
+Foreign Archives
+----------------
+
+Foreign archives are a way to link archives that are separately compiled.
+
+They are particularly useful when embedding a library written in a foreign
+language and/or built with another build system. See :ref:`foreign-sandboxing`
+for more details.
+
+To use this feature, use the ``foreign_archives`` field of the corresponding
+``library`` or ``executable`` stanza. For example:
+
+.. code:: dune
+
+    (library
+     (name lib)
+     (foreign_stubs (language c) (names src1 src2))
+     (foreign_stubs (language cxx) (names src3) (flags -O2))
+     (foreign_archives arch1 some/dir/arch2))
+
+Here, in addition to :doc:`foreign-stubs`, we also specify foreign archives
+``arch1`` and ``arch2``, where the latter is stored in a subdirectory
+``some/dir``.
+
+You can build a foreign archive manually, e.g., using a custom ``rule`` as
+described in :ref:`foreign-sandboxing`, or ask Dune to build it via the
+``foreign_library`` stanza:
+
+.. code:: dune
+
+    (foreign_library
+     (archive_name arch1)
+     (language c)
+     (enabled_if true)
+     (names src4 src5)
+     (include_dir headers))
+
+This asks Dune to compile C source files ``src4`` and ``src5`` with
+headers tracked in the ``headers`` directory and put the resulting
+object files into an archive ``arch1``, whose full name is typically
+``libarch1.a`` for static linking and ``dllarch1.so`` for dynamic
+linking.
+
+The ``foreign_library`` stanza supports all :doc:`foreign-stubs` fields.
+The ``archive_name`` field specifies the archive's name. You can refer
+to the same archive name from multiple OCaml libraries and executables, so a
+foreign archive is a bit like a foreign library, hence the name of the stanza.
+The ``enabled_if`` field has the same meaning as in the :doc:`dune/library`
+stanza.

doc/reference/foreign-flags.rst

@@ -0,0 +1,22 @@
+Flags in Foreign Code
+---------------------
+
+Depending on the :doc:`dune-project/use_standard_c_and_cxx_flags` option,
+the base ``:standard`` set of flags for C will contain only ``ocamlc_cflags`` or
+both ``ocamlc_cflags`` and ``ocamlc_cppflags``.
+
+There are multiple levels where one can declare custom flags (using the
+:doc:`ordered-set-language`), and each level inherits the flags of the previous
+one in its `:standard` set:
+
+- In the global :doc:`dune-workspace/env` definition of a
+  :doc:`dune-workspace/index` file
+- In the :doc:`per-context env <dune-workspace/context>` definitions in a
+  :doc:`dune-workspace/index` file
+- In the :doc:`dune/env` definition of a :doc:`dune/index` file
+- In a :doc:`foreign_stubs <foreign-stubs>`, :doc:`foreign_library
+  <foreign-archives>` or :doc:`extra_objects <extra-objects>` field of an
+  executable or a library.
+
+The ``%{cc}`` :doc:`variable <../concepts/variables>` will contain the flags
+from the first three levels only.

doc/reference/foreign.rst → doc/reference/foreign-stubs.rst

@@ -1,13 +1,3 @@
-Foreign Sources, Archives, and Objects
-======================================
-
-Dune provides basic support for including foreign source files as well
-as archives of foreign object files into OCaml projects via the
-``foreign_stubs`` and ``foreign_archives`` fields. Individual object
-files can also be included via the ``extra_objects`` field.
-
-.. _foreign-stubs:
-
 Foreign Stubs
 -------------
 
@@ -38,7 +28,7 @@ Here is a complete list of supported subfields:
   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 :ref:`foreign-archives` via the
+  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``.
@@ -106,109 +96,3 @@ from which the stubs are built.
                         ; specific to native builds
 
 Note that, as of version ``0.1`` of this extension, this mechanism does not work for ``foreign_archives``.
-
-.. _foreign-archives:
-
-Foreign Archives
-----------------
-
-You can also specify archives of separately compiled foreign object files
-that need to be packaged with an OCaml library or linked into an OCaml
-executable. To do that, use the ``foreign_archives`` field of the
-corresponding ``library`` or ``executable`` stanza. For example:
-
-.. code:: dune
-
-    (library
-     (name lib)
-     (foreign_stubs (language c) (names src1 src2))
-     (foreign_stubs (language cxx) (names src3) (flags -O2))
-     (foreign_archives arch1 some/dir/arch2))
-
-Here, in addition to :ref:`foreign-stubs`, we also specify foreign archives
-``arch1`` and ``arch2``, where the latter is stored in a subdirectory
-``some/dir``.
-
-You can build a foreign archive manually, e.g., using a custom ``rule`` as
-described in :ref:`foreign-sandboxing`, or ask Dune to build it via the
-``foreign_library`` stanza:
-
-.. code:: dune
-
-    (foreign_library
-     (archive_name arch1)
-     (language c)
-     (enabled_if true)
-     (names src4 src5)
-     (include_dir headers))
-
-This asks Dune to compile C source files ``src4`` and ``src5`` with
-headers tracked in the ``headers`` directory and put the resulting
-object files into an archive ``arch1``, whose full name is typically
-``libarch1.a`` for static linking and ``dllarch1.so`` for dynamic
-linking.
-
-The ``foreign_library`` stanza supports all :ref:`foreign-stubs` fields.
-The ``archive_name`` field specifies the archive's name. You can refer
-to the same archive name from multiple OCaml libraries and executables, so a
-foreign archive is a bit like a foreign library, hence the name of the stanza.
-The ``enabled_if`` field has the same meaning as in the :doc:`dune/library`
-stanza.
-
-Foreign archives are particularly useful when embedding a library written in
-a foreign language and/or built with another build system. See
-:ref:`foreign-sandboxing` for more details.
-
-
-.. _extra-objects:
-
-Extra Objects
--------------
-
-It's possible to specify native object files to be packaged with OCaml
-libraries or linked into OCaml executables. Do this by using the
-``extra_objects`` field of the ``library`` or ``executable`` stanzas.
-For example:
-
-.. code:: dune
-
-    (executable
-     (public_name main)
-     (extra_objects foo bar))
-
-    (rule
-     (targets foo.o bar.o)
-     (deps foo.c bar.c)
-     (action (run ocamlopt %{deps})))
-
-This example builds an executable which is linked against a pair of native
-object files, ``foo.o`` and ``bar.o``. The ``extra_objects`` field takes a
-list of object names, which correspond to the object file names with their path
-and extension omitted.
-
-In this example, the sources corresponding to the objects (``foo.c`` and
-``bar.c``)  are assumed to be present in the same directory as the OCaml source
-code, and a custom ``rule`` is used to compile the C source code into object
-files using ``ocamlopt``. This is not necessary; one can instead compile foreign
-object files manually and place them next to the OCaml source code.
-
-.. _flags-flow:
-
-Flags
------
-
-Depending on the :doc:`dune-project/use_standard_c_and_cxx_flags` option,
-the base `:standard` set of flags for C will contain only ``ocamlc_cflags`` or
-both ``ocamlc_cflags`` and ``ocamlc_cppflags``.
-
-There are multiple levels where one can declare custom flags (using the
-:doc:`ordered-set-language`), and each level inherits the flags of the previous
-one in its `:standard` set:
-
-- In the global ``env`` definition of a ``dune-workspace`` file
-- In the per-context `env` definitions in a `dune-workspace` file
-- In the env definition of a `dune` file
-- In a `foreign_` field of an executable or a library
-
-The ``%{cc}`` :doc:`variable <../concepts/variables>` will contain the flags
-from the first three levels only.

doc/reference/index.rst

@@ -46,7 +46,18 @@ These documents specify the various features and languages present in Dune.
        ../concepts/promotion
        ../concepts/package-spec
        aliases
-       foreign
+
+  .. grid-item::
+
+    .. toctree::
+       :maxdepth: 1
+       :caption: Foreign Code
+
+       foreign-stubs
+       foreign-archives
+       extra-objects
+       foreign-flags
+
 
   .. grid-item::