diff --git a/doc/advanced-topics.rst b/doc/advanced-topics.rst index a3b40d01..6d045c20 100644 --- a/doc/advanced-topics.rst +++ b/doc/advanced-topics.rst @@ -95,6 +95,8 @@ set of predicates: it is linked as part of a driver or meant to add a ``-ppx`` argument to the compiler, choose the former behavior +.. _advanced-cross-compilation: + Cross Compilation ================= diff --git a/doc/documentation.rst b/doc/documentation.rst index 6559929f..7061124b 100644 --- a/doc/documentation.rst +++ b/doc/documentation.rst @@ -1,3 +1,5 @@ +.. _documentation: + ************************ Generating Documentation ************************ @@ -53,7 +55,7 @@ belong to any particular package. But the generated html will still be found in .. _doc-stanza: Documentation Stanza -=================== +==================== Documentation pages will be automatically generated for from .ml and .mli files that include ocamldoc fragments. Additional manual pages may be attached to diff --git a/doc/faq.rst b/doc/faq.rst index e20f9621..93f85c24 100644 --- a/doc/faq.rst +++ b/doc/faq.rst @@ -20,22 +20,24 @@ convenience, for the following reasons: How to add a configure step to a jbuilder project? ================================================== -`example/sample-projects/with-configure-step https://github.com/ocaml/dune/tree/master/example/sample-projects/with-configure-step`__ -shows one way to do it which preserves composability; i.e. it doesn't require -manually running `./configure` script when working on multiple projects at the -same time. +The with-configure-step_ example shows one way to do it which +preserves composability; i.e. it doesn't require manually running `./configure` +script when working on multiple projects at the same time. + +.. _with-configure-step: https://github.com/ocaml/dune/tree/master/example/sample-projects/with-configure-step Can I use topkg with jbuilder? ============================== -Yes, have a look at the `topkg-jbuilder https://github.com/samoht/topkg-jbuilder`__ project for -more details. +Yes, have a look at the topkg-jbuilder_ project for more details. + +.. _topkg-jbuilder: https://github.com/samoht/topkg-jbuilder here can I find some examples of projects using Jbuilder? ========================================================= -The `dune-universe https://github.com/dune-universe/dune-universe`__ -repository contains a snapshot of the latest versions of all opam -packages depending on jbuilder. It is therefore a useful reference to -search through to find different approaches to constructing build -rules. +The dune-universe_ repository contains a snapshot of the latest versions of all +opam packages depending on jbuilder. It is therefore a useful reference to +search through to find different approaches to constructing build rules. + +.. _dune-universe: https://github.com/dune-universe/dune-universe diff --git a/doc/jbuild.rst b/doc/jbuild.rst index aee53121..0319a580 100644 --- a/doc/jbuild.rst +++ b/doc/jbuild.rst @@ -184,9 +184,10 @@ modules you want. overlap with libraries that are present in the workspace Note that when binding C libraries, Jbuilder doesn't provide special support for -tools such as ``pkg-config``, however it integrates easily with `configurator -`__ by using ``(c_flags (:include -...))`` and ``(c_library_flags (:include ...))``. +tools such as ``pkg-config``, however it integrates easily with configurator_ by +using ``(c_flags (:include ...))`` and ``(c_library_flags (:include ...))``. + +.. _configurator: https://github.com/janestreet/configurator executable ---------- @@ -640,6 +641,8 @@ where ```` describe how the file will be installed. For instance, to install a file ``mylib.el`` as ``emacs/site-lisp/mylib.el`` in the ``share_root`` section: +.. code:: scheme + (install ((section share_root) (files ((mylib.el as emacs/site-lisp/mylib.el))))) @@ -711,6 +714,8 @@ With this jbuild file, running jbuilder as follow will replace the $ jbuilder build @runtest --auto-promote +.. _jbuild-env: + env --- @@ -732,6 +737,8 @@ directory. You can use ``_`` to match any build profile. Currently ```` can be any OCaml flags field, see `OCaml flags`_ for more details. +.. _jbuild-ignored_subdirs: + ignored_subdirs --------------- @@ -791,7 +798,7 @@ Jbuilder supports the following variables: the toplevel directory of your project and as long as you have at least one ``.opam`` file there, ``SCOPE_ROOT`` is independent of the workspace configuration -- ``CC`` is the C compiler command line (list made of the compiler +- ``CC`` is the C compiler command line (list made of the compiler name followed by its flags) that was used to compile OCaml in the current build context - ``CXX`` is the C++ compiler command line being used in the @@ -806,7 +813,7 @@ Jbuilder supports the following variables: - ``ARCH_SIXTYFOUR`` is ``true`` if using a compiler targeting a 64 bit architecture and ``false`` otherwise - ``null`` is ``/dev/null`` on Unix or ``nul`` on Windows -- ``ext_obj``, ``ext_asm``, ``ext_lib``, ``ext_dll`` and ``ext_exe`` +- ``ext_obj``, ``ext_asm``, ``ext_lib``, ``ext_dll`` and ``ext_exe`` are the file extension used for various artifacts - ``ocaml-config:v`` for every variable ``v`` in the output of ``ocamlc -config``. Note that output Jbuilder processes the output @@ -1152,6 +1159,8 @@ follows: (flags (:standard )) +.. _jbuild-jsoo: + js_of_ocaml ----------- @@ -1166,7 +1175,7 @@ using ``(js_of_ocaml ())``. - ``(javascript_files ())`` to specify ``js_of_ocaml`` JavaScript runtime files. -== is specified in the `Ordered set language`_. +```` is specified in the `Ordered set language`_. The default value for ``(flags ...)`` depends on whether ``--dev`` is passed to Jbuilder. ``--dev`` will enable sourcemap and the pretty JavaScript output. @@ -1191,7 +1200,7 @@ automatically handled by Jbuilder. The DSL is currently quite limited, so if you want to do something complicated it is recommended to write a small OCaml program and use the DSL to invoke it. You can use `shexp `__ to write portable -scripts or `Configurator`_ for configuration related tasks. +scripts or configurator_ for configuration related tasks. The following constructions are available: diff --git a/doc/project-layout-specification.rst b/doc/project-layout-specification.rst index 37654185..487a2718 100644 --- a/doc/project-layout-specification.rst +++ b/doc/project-layout-specification.rst @@ -225,4 +225,4 @@ jbuild-ignore (deprecated) ========================== ``jbuild-ignore`` files are deprecated and replaced by -`ignored_subdirs`_ stanzas in ``dune`` files. +:ref:`jbuild-ignored_subdirs` stanzas in ``dune`` files. diff --git a/doc/terminology.rst b/doc/terminology.rst index 842effe7..5339c962 100644 --- a/doc/terminology.rst +++ b/doc/terminology.rst @@ -53,14 +53,14 @@ Terminology - ``runtest`` which runs user defined tests - ``install`` which depends on everything that should be installed - ``doc`` which depends on the generated HTML - documentation. See :ref:`apidoc` for details + documentation. See :ref:`documentation` for details. - **environment**: in Jbuilder, each directory has an environment attached to it. The environment determines the default values of various parameters, such as the compilation flags. Inside a scope, each directory inherit the environment from its parent. At the root of every scope, a default environment is used. At any point, the - environment can be altered using an `env`_ stanza. + environment can be altered using an :ref:`jbuild-env` stanza. - **build profile**: a global setting that influence various defaults. It can be set from the command line using ``--profile diff --git a/doc/usage.rst b/doc/usage.rst index 40f1786f..49dd92d6 100644 --- a/doc/usage.rst +++ b/doc/usage.rst @@ -59,7 +59,7 @@ in ancestor directories. For instance ``jbuild-workspace.dev``. If such a file is found, it will mark the root of the workspace. ``jbuilder`` will however not read its contents. - The rationale for this rule is that it is good practice to have a +The rationale for this rule is that it is good practice to have a ``jbuild-workspace.dev`` file at the root of your project. For quick experiments, simply do this to mark the root: @@ -391,15 +391,15 @@ context or can be the description of an opam switch, as follows: run which is usually ``~/.opam`` - ``(merlin)`` instructs Jbuilder to use this build context for - merlin + merlin - ``(profile )`` to set a different profile for a build context. This has precedence over the command line option ``--profile`` Both ``(default ...)`` and ``(opam ...)`` accept a ``targets`` field -in order to setup cross compilation. See `Cross Compilation`_ for more -information. +in order to setup cross compilation. See :ref:`advanced-cross-compilation` +for more information. Merlin reads compilation artifacts and it can only read the compilation artifacts of a single context. Usually, you should use @@ -476,7 +476,7 @@ And that if your project contains several packages, then all the package names must be prefixed by the shortest one. Watermarking -~~~~~~~~~~~~ +============ One of the feature topkg provides is watermarking; it replaces various strings of the form ``%%ID%%`` in all files of your project before @@ -498,7 +498,7 @@ watermarks when the package is pinned by the user. To help with this, jbuilder provides the ``subst`` sub-command. jbuilder subst -~~~~~~~~~~~~~~ +============== ``jbuilder subst`` performs the same substitution ``topkg`` does with the default configuration. i.e. calling ``jbuilder subst`` at the root