diff --git a/doc/advanced-topics.rst b/doc/advanced-topics.rst index 28461e62..7c7e65b4 100644 --- a/doc/advanced-topics.rst +++ b/doc/advanced-topics.rst @@ -37,6 +37,8 @@ just write or generate a ``META..template`` file containing a line of the form ``# JBUILDER_GEN``. Jbuilder will automatically insert its generated ``META`` contents in place of this line. +.. _custom-driver: + Using a custom ppx driver ========================= diff --git a/doc/jbuild.rst b/doc/jbuild.rst index b14a2a20..c9e72f1b 100644 --- a/doc/jbuild.rst +++ b/doc/jbuild.rst @@ -64,7 +64,7 @@ modules you want. will not be installed by Jbuilder. The public name must start by the package name it is part of and optionally followed by a dot and anything else you want. The package name must be one of the packages that Jbuilder knows about, - as determined by the *.opam files* + as determined by the :ref:`opam-files` - ``(synopsis )`` should give a one-line description of the library. This is used by tools that list installed libraries @@ -73,13 +73,14 @@ modules you want. default Jbuilder will use all the .ml/.re files in the same directory as the ``jbuild`` file. This include ones that are 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 *ordered set language* + ``(modules )`` field. ```` uses the `Ordered set language`_ where elements are module names and don't need to start with a uppercase letter. For instance to exclude module ``Foo``: ``(modules (:standard \ foo))`` - ``(libraries ())`` is used to specify the dependencies - of the library. See the *section about library dependencies* for more details + of the library. See the section about `Library dependencies`_ for more + details - ``(wrapped )`` specifies whether the modules of the library should be available only through the top-level library module, or should all be exposed @@ -92,12 +93,12 @@ modules you want. - ``(preprocess )`` specifies how to preprocess files if needed. The default is ``no_processing``. Other options are described in the - *preprocessing specification section* + `Preprocessing specification`_ section - ``(preprocessor_deps ())`` specifies extra dependencies of the preprocessor, for instance if the preprocessor reads a generated file. The - specification of dependencies is described in the *dependency specification - section* + specification of dependencies is described in the `Dependency specification`_ + section - ``(optional)``, if present it indicates that the library should only be built and installed if all the dependencies are available, either in the workspace @@ -136,18 +137,18 @@ modules you want. dependencies here. You don't need to do so unless you use Jbuilder to synthesize the ``depends`` and ``depopts`` sections of your opam file -- ``js_of_ocaml``. See the *section about js_of_ocaml* +- ``js_of_ocaml``. See the section about :ref:`jbuild-jsoo` -- ``flags``, ``ocamlc_flags`` and ``ocamlopt_flags``. See the - *section about specifying OCaml flags* +- ``flags``, ``ocamlc_flags`` and ``ocamlopt_flags``. See the section about + `OCaml flags`_ - ``(library_flags ())`` is a list of flags that are passed as it 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 *variables expansion* + strings supporting `Variables expansion`_ - ``(c_flags )`` specifies the compilation flags for C stubs, - using the *ordered set language*. This field supports + using the `Ordered set language`_. This field supports ``(:include ...)`` forms - ``(cxx_flags )`` is the same as ``c_flags`` but for C++ @@ -155,7 +156,7 @@ modules you want. - ``(c_library_flags )`` specifies the flags to pass to the C compiler when constructing the library archive file for the C stubs. ```` uses - the *ordered set language* and supports ``(:include ...)`` forms. When you + the `Ordered set language`_ and supports ``(:include ...)`` forms. When you are writing bindings for a C library named ``bar``, you should typically write ``-lbar`` here, or whatever flags are necessary to to link against this library @@ -215,26 +216,25 @@ such you can always rely on ``.exe`` being available. - ``(package )`` if there is a ``(public_name ...)`` field, this specifies the package the executables are part of -- ``(libraries ())`` specifies the library - dependencies. See the *section about library dependencies* for - more details +- ``(libraries ())`` specifies the library dependencies. + See the section about `Library dependencies`_ for more details -- ``(modules )`` specifies which modules in the current - directory Jbuilder should consider when building this executable. - Modules not listed here will be ignored and cannot be used inside - the executable described by the current stanza. It is interpreted - in the same way as the ``(modules ...)`` field of *libraries* +- ``(modules )`` specifies which modules in the current directory + Jbuilder should consider when building this executable. Modules not listed + here will be ignored and cannot be used inside the executable described by + the current stanza. It is interpreted in the same way as the ``(modules + ...)`` field of `library`_ -- ``(preprocess )`` is the same as the - ``(preprocess ...)`` field of *libraries* +- ``(preprocess )`` is the same as the ``(preprocess ...)`` + field of `library`_ -- ``(preprocessor_deps ())`` is the same as the - ``(preprocessor_deps ...)`` field of *libraries* +- ``(preprocessor_deps ())`` is the same as the + ``(preprocessor_deps ...)`` field of `library`_ -- ``js_of_ocaml``. See the *section about js_of_ocaml* +- ``js_of_ocaml``. See the section about `js_of_ocaml`_ -- ``flags``, ``ocamlc_flags`` and ``ocamlopt_flags``. See the - *section about specifying OCaml flags* +- ``flags``, ``ocamlc_flags`` and ``ocamlopt_flags``. See the section about + specifying `OCaml flags`_ executables ----------- @@ -274,11 +274,11 @@ The syntax is as follows: ```` is a list of file names. Note that currently Jbuilder only support user rules with targets in the current directory. -```` specifies the dependencies of the rule. See the -*dependency specification section* for more details. +```` specifies the dependencies of the rule. See the `Dependency +specification`_ section for more details. -```` is the action to run to produce the targets from the -dependencies. See the *actions section* for more details. +```` is the action to run to produce the targets from the dependencies. +See the `User actions`_ section for more details. Note that contrary to makefiles or other build systems, user rules currently don't support patterns, such as a rule to produce ``%.y`` @@ -356,12 +356,12 @@ The syntax is as follows: ```` is an alias name such as ``runtest``. ```` specifies the dependencies of the alias. See the -*dependency specification section* for more details. +`Dependency specification`_ section for more details. ```` are: - ````, an action to run when constructing the alias. See - the *actions section* for more details. + the `User actions`_ section for more details. - ``(package )`` indicates that this alias stanza is part of package ```` and should be filtered out if ```` is @@ -376,7 +376,7 @@ The typical use of the ``alias`` stanza is to define tests: ((name runtest) (action (run ${exe:my-test-program.exe} blah)))) -See the *section about running tests* for details. +See the section about :ref:`running-tests` for details. Note that if your project contains several packages and you run test the tests from the opam file using a ``build-test`` field, then all your ``runtest`` alias @@ -451,7 +451,7 @@ syntax ``(:include )``. This is useful for instance when you need to run a script to figure out some compilation flags. ```` is expected to contain a single S-expression and cannot contain ``(:include ...)`` forms. -Most fields using the ordered set language also support *variables expansion*. +Most fields using the ordered set language also support `Variables expansion`_. Variables are expanded after the set language is interpreted. Variables expansion @@ -480,31 +480,27 @@ Jbuilder supports the following variables: In addition, ``(action ...)`` fields support the following special variables: -- ``@`` expands to the list of target, separated by spaces -- ``<`` expands to the first dependency, or the empty string if - there are no dependencies +- ``@`` expands to the list of target, separated by spaces +- ``<`` expands to the first dependency, or the empty string if there are no + dependencies - ``^`` expands to the list of dependencies, separated by spaces - ``path:`` expands to ```` -- ``exe:`` is the same as ````, except when - cross-compiling, in which case it will expand to ```` - from the host build context -- ``bin:`` expands to a path to ``program``. If - ``program`` is installed by a package in the workspace (see - *install stanzas*), the locally built binary will be used, - otherwise it will be searched in the ``PATH`` of the current - build context -- ``lib::`` expands to a path to file - ```` of library ````. If - ```` is available in the current - workspace, the local file will be used, otherwise the one from +- ``exe:`` is the same as ````, except when cross-compiling, in + which case it will expand to ```` from the host build context +- ``bin:`` expands to a path to ``program``. If ``program`` is + installed by a package in the workspace (see `install`_ stanzas), the locally + built binary will be used, otherwise it will be searched in the ``PATH`` of + the current build context +- ``lib::`` expands to a path to file ```` of + library ````. If ```` is available + in the current workspace, the local file will be used, otherwise the one from the installed world will be used -- ``libexec::`` is the same as - ``lib:...`` except when cross-compiling, in which case it will - expand to the file from the host build context -- ``lib-available:`` expands to ``true`` or - ``false`` depending on wether the library is available or not. - A library is available iff at least one of the following - condition holds: +- ``libexec::`` is the same as ``lib:...`` except + when cross-compiling, in which case it will expand to the file from the host + build context +- ``lib-available:`` expands to ``true`` or ``false`` depending on + wether the library is available or not. A library is available iff at least + one of the following condition holds: - it is part the installed worlds - it is available locally and is not optional @@ -521,51 +517,48 @@ transparently whether things are installed or not. Library dependencies -------------------- -Dependencies on libraries are specified using ``(libraries ...)`` -fields in ``library`` and ``executables`` stanzas. +Dependencies on libraries are specified using ``(libraries ...)`` fields in +``library`` and ``executables`` stanzas. -For libraries that are present in the workspace, you can use -either the real name (with some restrictions, see below) or the -public name. For libraries that are part of the installed world, -you need to use the public name. For instance: +For libraries that are present in the workspace, you can use either the real +name (with some restrictions, see below) or the public name. For libraries that +are part of the installed world, you need to use the public name. For instance: ``(libraries (base re))``. -When resolving libraries, libraries that are part of the workspace -are always prefered to ones that are part of the installed world. +When resolving libraries, libraries that are part of the workspace are always +prefered to ones that are part of the installed world. #. Scope of internal library names - The scope of internal library names is not the whole workspace. - It is restricted to the subtree starting from the closest - parent containing a ``.opam`` file, or the whole - workspace if no such directory exist. Moreover, a subtree - containing ``.opam`` doesn' t inherit the internal - names available in its parent scope. + The scope of internal library names is not the whole workspace. It is + restricted to the subtree starting from the closest parent containing a + ``.opam`` file, or the whole workspace if no such directory exist. + Moreover, a subtree containing ``.opam`` doesn' t inherit the + internal names available in its parent scope. - The idea behing this rule is that public library names must be - universally unique, but internal ones don't need to. In - particular you might have private libraries that are only used - for tests or building an executable. + The idea behing this rule is that public library names must be universally + unique, but internal ones don't need to. In particular you might have private + libraries that are only used for tests or building an executable. - As a result, when you create a workspace including several - projects there might be a name clash between internal library - names. + As a result, when you create a workspace including several projects there + might be a name clash between internal library names. This scoping rule ensure that this won't be a problem. +.. _alternative-deps: + #. Alternative dependencies - In addition to direct dependencies you can specify alternative - dependencies. This is described in the *alternative - dependencies section* + In addition to direct dependencies you can specify alternative dependencies. + This is described in the :ref:`Alternative dependencies ` + section - It is sometimes the case that one wants to not depend on a - specific library, but instead on whatever is already installed. - For instance to use a different backend depending on the - target. + It is sometimes the case that one wants to not depend on a specific library, + but instead on whatever is already installed. For instance to use a different + backend depending on the target. - Jbuilder allows this by using a ``(select ... from ...)`` form - inside the list of library dependencies. + Jbuilder allows this by using a ``(select ... from ...)`` form inside the + list of library dependencies. Select forms are specified as follows: @@ -610,12 +603,11 @@ doesn't use the ``-pp`` or ``-ppx`` of the various OCaml tools. #. Preprocessing with actions - ```` uses the same DSL as described in the *user - actions section*, and for the same reason given in that - section, it will be executed from the root of the current build - context. It is expected to be an action that reads the file - given as only dependency and outputs the preprocessed file on - its standard output. + ```` uses the same DSL as described in the `User actions`_ section, + and for the same reason given in that section, it will be executed from the + root of the current build context. It is expected to be an action that reads + the file given as only dependency and outputs the preprocessed file on its + standard output. More precisely, ``(preprocess (action ))`` acts as if you had setup a rule for every file of the form: @@ -645,22 +637,19 @@ doesn't use the ``-pp`` or ``-ppx`` of the various OCaml tools. The list of libraries will be ``ppx1`` and ``ppx2`` and the command line arguments will be: ``-foo -bar 42``. - Libraries listed here should be libraries implementing an OCaml - AST rewriter and registering themselves using the - `ocaml-migrate-parsetree.driver - API `__. + Libraries listed here should be libraries implementing an OCaml AST rewriter + and registering themselves using the `ocaml-migrate-parsetree.driver API + `__. - Jbuilder will build a single executable by linking all these - libraries and their dependencies. Note that it is important - that all these libraries are linked with ``-linkall``. Jbuilder - automatically uses ``-linkall`` when the ``(kind ...)`` field - is set to ``ppx_rewriter`` or ``ppx_deriver``. + Jbuilder will build a single executable by linking all these libraries and + their dependencies. Note that it is important that all these libraries are + linked with ``-linkall``. Jbuilder automatically uses ``-linkall`` when the + ``(kind ...)`` field is set to ``ppx_rewriter`` or ``ppx_deriver``. - It is guaranteed that the last library in the list will be - linked last. You can use this feature to use a custom ppx - driver. By default Jbuilder will use - ``ocaml-migrate-parsetree.driver-main``. See the *section about - using a custom ppx driver* for more details. + It is guaranteed that the last library in the list will be linked last. You + can use this feature to use a custom ppx driver. By default Jbuilder will use + ``ocaml-migrate-parsetree.driver-main``. See the section about + :ref:`custom-driver` for more details. #. Per module preprocessing specification @@ -696,16 +685,17 @@ Dependency specification Dependencies in ``jbuild`` files can be specified using one of the following syntax: -- ``(file )`` or simply ````: depend on this - file -- ``(alias )``: depend on the construction of this - alias, for instance: ``(alias src/runtest)`` -- ``(glob_files )``: depend on all files matched by - ````, see the *glob section* for details -- ``(files_recursively_in )``: depend on all files in the - subtree with root ```` +- ``(file )`` or simply ````: depend on this file +- ``(alias )``: depend on the construction of this alias, for + instance: ``(alias src/runtest)`` +- ``(glob_files )``: depend on all files matched by ````, see the + :ref:`glob ` for details +- ``(files_recursively_in )``: depend on all files in the subtree with root + ```` -In all these cases, the argument supports *variables expansion*. +In all these cases, the argument supports `Variables expansion`_. + +.. _glob: #. Glob @@ -752,8 +742,7 @@ compilation flags using the following fields: - ``(ocamlopt_flags )`` to specify flags passed to ``ocamlopt`` only -For all these fields, ```` is specified in the *ordered set -language*. +For all these fields, ```` is specified in the `Ordered set language`_. The default value for ``(flags ...)`` includes some ``-w`` options to set warnings. The exact set depends on whether ``--dev`` is @@ -764,6 +753,8 @@ passed to Jbuilder. As a result it is recommended to write (flags (:standard )) +.. _jbuild-jsoo: + js_of_ocaml ----------- @@ -777,7 +768,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. @@ -793,7 +784,7 @@ context as the jbuild they are defined in. So for instance an action defined in The argument of ``(action ...)`` fields is a small DSL that is interpreted by jbuilder directly and doesn't require an external shell. All atoms in the DSL -support *variables expansion*. Moreover, you don't need to specify dependencies +support `Variables expansion`_. Moreover, you don't need to specify dependencies explicitly for the special ``${:...}`` forms, these are recognized and automatically handled by Jbuilder. @@ -871,6 +862,8 @@ of your project. What you should write instead is: (deps (blah.mll)) (action (chdir ${ROOT} (run ocamllex -o ${@} ${<}))))) +.. _ocaml-syntax: + OCaml syntax ============ diff --git a/doc/project-layout-specification.rst b/doc/project-layout-specification.rst index ebce0b07..ad5b42a3 100644 --- a/doc/project-layout-specification.rst +++ b/doc/project-layout-specification.rst @@ -37,7 +37,9 @@ documentation of the `parsexp `__ library. Note that the format is completely static. However you can do -meta-programming on jbuilds files by writing them in *OCaml syntax*. +meta-programming on jbuilds files by writing them in :ref:`ocaml-syntax`. + +.. _opam-files: .opam files ==================== @@ -92,7 +94,7 @@ If the version can't be determined, Jbuilder just won't assign one. Note that if you are using `Topkg `__ as well in your project, you shouldn't manually set a version in your ``.opam`` file or write/generate on of the file listed above. -See *the section about using topkg with jbuilder* for more details. +See the section about :ref:`using-topkg` for more details. Odig conventions ---------------- diff --git a/doc/terminology.rst b/doc/terminology.rst index 3e624cd4..be2e6481 100644 --- a/doc/terminology.rst +++ b/doc/terminology.rst @@ -12,7 +12,7 @@ Terminology things. Jbuilder knows how to build targets that are descendents of the root. Anything outside of the tree starting from the root is considered part of the **installed world**. How the root is - determined is explained in *this section*. + determined is explained in :ref:`finding-root`. - **workspace**: the workspace is the subtree starting from the root. It can contain any number of projects that will be built @@ -27,7 +27,7 @@ Terminology specific configuration from the user, there is always a ``default`` build context, which corresponds to the environment in which Jbuilder is executed. Build contexts can be specified by writing a - *jbuild-workspace* file + :ref:`jbuild-workspace` file - **build context root**: the root of a build context named ``foo`` is ``/_build/`` diff --git a/doc/usage.rst b/doc/usage.rst index c2674759..e4fc7004 100644 --- a/doc/usage.rst +++ b/doc/usage.rst @@ -4,9 +4,13 @@ Usage This section describe usage of Jbuilder from the shell. +.. _finding-root: + Finding the root ================ +.. _jbuild-workspace: + jbuild-workspace ---------------- @@ -36,10 +40,10 @@ The first entry to match in this list will determine the root. In practice this means that if you nest your workspaces, Jbuilder will always use the outermost one. -In addition to determining the root, ``jbuilder`` will read this file as -to setup the configuration of the workspace unless the ``--workspace`` -command line option is used. See the *section about workspace -configuration* for the syntax of this file. +In addition to determining the root, ``jbuilder`` will read this file as to +setup the configuration of the workspace unless the ``--workspace`` command line +option is used. See the section `Workspace configuration`_ for the syntax of +this file. jbuild-workspace\* ------------------ @@ -152,6 +156,8 @@ determined as follow: ``../lib`` to it. For instance if ``ocamlc`` is found in ``/usr/bin``, use ``/usr/lib`` +.. _running-tests: + Running tests ------------- @@ -335,8 +341,10 @@ It supports two modes of compilation: The separate compilation mode will be selected when passing ``--dev`` to jbuilder. There is currently no other way to control this behaviour. -See the *section about js_of_ocalm* for passing custom flags to the js_of_ocaml -compiler +See the section about :ref:`jbuild-jsoo` for passing custom flags to the +js_of_ocaml compiler + +.. _using-topkg: Using topkg with jbuilder =========================