From 9c5969ca302e73812a1312df94ef793d19a6dd23 Mon Sep 17 00:00:00 2001 From: Etienne Millon Date: Mon, 15 Jul 2024 15:06:02 +0200 Subject: [PATCH] doc: split foreign.rst (#10718) Signed-off-by: Etienne Millon --- doc/concepts/variables.rst | 4 +- doc/foreign-code.rst | 6 +- .../use_standard_c_and_cxx_flags.rst | 2 + doc/reference/dune/executable.rst | 4 +- doc/reference/dune/foreign_library.rst | 3 +- doc/reference/dune/library.rst | 6 +- doc/reference/extra-objects.rst | 30 +++++ doc/reference/foreign-archives.rst | 49 ++++++++ doc/reference/foreign-flags.rst | 22 ++++ .../{foreign.rst => foreign-stubs.rst} | 118 +----------------- doc/reference/index.rst | 13 +- 11 files changed, 129 insertions(+), 128 deletions(-) create mode 100644 doc/reference/extra-objects.rst create mode 100644 doc/reference/foreign-archives.rst create mode 100644 doc/reference/foreign-flags.rst rename doc/reference/{foreign.rst => foreign-stubs.rst} (53%) diff --git a/doc/concepts/variables.rst b/doc/concepts/variables.rst index 1fdeeebee6e..add257751e9 100644 --- a/doc/concepts/variables.rst +++ b/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 `. + 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. diff --git a/doc/foreign-code.rst b/doc/foreign-code.rst index 31f5150c81c..e33827621bc 100644 --- a/doc/foreign-code.rst +++ b/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) ` 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 diff --git a/doc/reference/dune-project/use_standard_c_and_cxx_flags.rst b/doc/reference/dune-project/use_standard_c_and_cxx_flags.rst index 1c83f943f66..d1dadec6294 100644 --- a/doc/reference/dune-project/use_standard_c_and_cxx_flags.rst +++ b/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` diff --git a/doc/reference/dune/executable.rst b/doc/reference/dune/executable.rst index 641898d8f67..b9129d0e380 100644 --- a/doc/reference/dune/executable.rst +++ b/doc/reference/dune/executable.rst @@ -114,11 +114,11 @@ files for executables. See - ``(foreign_stubs )`` 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 )`` 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 )`` ensures that the given libraries are not linked in the resulting executable. If they end up being pulled in, either diff --git a/doc/reference/dune/foreign_library.rst b/doc/reference/dune/foreign_library.rst index 37eddf9072a..b13ad7888ff 100644 --- a/doc/reference/dune/foreign_library.rst +++ b/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. diff --git a/doc/reference/dune/library.rst b/doc/reference/dune/library.rst index d2ba3a1461b..8237e6d8f86 100644 --- a/doc/reference/dune/library.rst +++ b/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 ()) diff --git a/doc/reference/extra-objects.rst b/doc/reference/extra-objects.rst new file mode 100644 index 00000000000..f782e29bab3 --- /dev/null +++ b/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. diff --git a/doc/reference/foreign-archives.rst b/doc/reference/foreign-archives.rst new file mode 100644 index 00000000000..b749b2eedb0 --- /dev/null +++ b/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. diff --git a/doc/reference/foreign-flags.rst b/doc/reference/foreign-flags.rst new file mode 100644 index 00000000000..f669046322f --- /dev/null +++ b/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 ` 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 `, :doc:`foreign_library + ` or :doc:`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. diff --git a/doc/reference/foreign.rst b/doc/reference/foreign-stubs.rst similarity index 53% rename from doc/reference/foreign.rst rename to doc/reference/foreign-stubs.rst index 143b4827762..3665f4bbcda 100644 --- a/doc/reference/foreign.rst +++ b/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. diff --git a/doc/reference/index.rst b/doc/reference/index.rst index 11bd88f9f42..abd7feb59bc 100644 --- a/doc/reference/index.rst +++ b/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::