Update documentation to reflect cross compilation
Describes how to setup targets and toolchains and the changes to the workspace syntax.
This commit is contained in:
parent
1ff8a7989c
commit
2b49123ae1
|
@ -102,6 +102,99 @@ set of predicates:
|
||||||
it is linked as part of a driver or meant to add a ``-ppx`` argument
|
it is linked as part of a driver or meant to add a ``-ppx`` argument
|
||||||
to the compiler, choose the former behavior
|
to the compiler, choose the former behavior
|
||||||
|
|
||||||
|
Cross Compilation
|
||||||
|
=================
|
||||||
|
|
||||||
|
Jbuilder allows for cross compilation by defining build contexts with
|
||||||
|
multiple targets. Targets are specified by adding a ``targets`` field
|
||||||
|
to the definition of a build context.
|
||||||
|
|
||||||
|
``targets`` takes a list of target name. It can be either:
|
||||||
|
|
||||||
|
- ``native`` which means using the native tools that can build
|
||||||
|
binaries that run on the machine doing the build
|
||||||
|
|
||||||
|
- the name of an alternative toolchain
|
||||||
|
|
||||||
|
Note that at the moment, there is no official support for
|
||||||
|
cross-compilation in OCaml. Jbuilder supports the two following
|
||||||
|
opam-cross-x repositories:
|
||||||
|
|
||||||
|
- `opam-cross-windows <https://github.com/whitequark/opam-cross-windows>`_
|
||||||
|
- `opam-cross-android <https://github.com/whitequark/opam-cross-android>`_
|
||||||
|
|
||||||
|
To build Windows binaries using opam-cross-windows, write ``windows``
|
||||||
|
in the list of targets. To build Android binaries using
|
||||||
|
opam-cross-android, write ``android`` in the list of targets.
|
||||||
|
|
||||||
|
For example, the following workspace file defines three different
|
||||||
|
targets for the ``default`` build context:
|
||||||
|
|
||||||
|
.. code:: scheme
|
||||||
|
|
||||||
|
(context (default (targets (native windows android))))
|
||||||
|
|
||||||
|
This configuration defines three build contexts:
|
||||||
|
|
||||||
|
- ``default``
|
||||||
|
- ``default.windows``
|
||||||
|
- ``default.android``
|
||||||
|
|
||||||
|
Note that the ``native`` target is always implicitly added when not
|
||||||
|
present. However, when implicitly added ``jbuilder build @install``
|
||||||
|
will skip this context, i.e. ``default`` will only be used for
|
||||||
|
building executables needed by the other contexts.
|
||||||
|
|
||||||
|
With such a setup, calling ``jbuilder build @install`` will build all
|
||||||
|
the packages three times.
|
||||||
|
|
||||||
|
Note that instead of writing a ``jbuild-workspace`` file, you can also
|
||||||
|
use the ``-x`` command line option. Passing ``-x foo`` to ``jbuilder``
|
||||||
|
without having a ``jbuild-workspace`` file is the same as writing the
|
||||||
|
following ``jbuild-workspace`` file:
|
||||||
|
|
||||||
|
.. code:: scheme
|
||||||
|
|
||||||
|
(context (default (targets (foo))))
|
||||||
|
|
||||||
|
If you have a ``jbuild-workspace`` and pass a ``-x foo`` option,
|
||||||
|
``foo`` will be added as target of all context stanzas.
|
||||||
|
|
||||||
|
How does it work?
|
||||||
|
-----------------
|
||||||
|
|
||||||
|
In such a setup, binaries that need to be built and executed in the
|
||||||
|
``default.windows`` or ``default.android`` contexts as part of the
|
||||||
|
build, will no longer be executed. Instead, all the binaries that will
|
||||||
|
be executed will come from the ``default`` context. One consequence of
|
||||||
|
this is that all preprocessing (ppx or otherwise) will be done using
|
||||||
|
binaries built in the ``default`` context.
|
||||||
|
|
||||||
|
To clarify this with an example, let's assume that you have the
|
||||||
|
following ``src/jbuild`` file:
|
||||||
|
|
||||||
|
.. code:: scheme
|
||||||
|
|
||||||
|
(executable ((name foo)))
|
||||||
|
(rule (with-stdout-to blah (run ./foo.exe)))
|
||||||
|
|
||||||
|
When building ``_build/default/src/blah``, jbuilder will resolve ``./foo.exe`` to
|
||||||
|
``_build/default/src/foo.exe`` as expected. However, for
|
||||||
|
``_build/default.windows/src/blah`` jbuilder will resolve ``./foo.exe`` to
|
||||||
|
``_build/default/src/foo.exe``
|
||||||
|
|
||||||
|
Assuming that the right packages are installed or that your workspace
|
||||||
|
has no external dependencies, jbuilder will be able to cross-compile a
|
||||||
|
given package without doing anything special.
|
||||||
|
|
||||||
|
Some packages might still have to be updated to support cross-compilation. For
|
||||||
|
instance if the ``foo.exe`` program in the previous example was using
|
||||||
|
``Sys.os_type``, it should instead take it as a command line argument:
|
||||||
|
|
||||||
|
.. code:: scheme
|
||||||
|
|
||||||
|
(rule (with-stdout-to blah (run ./foo.exe -os-type ${os_type})))
|
||||||
|
|
||||||
Classical ppx
|
Classical ppx
|
||||||
=============
|
=============
|
||||||
|
|
||||||
|
|
|
@ -334,9 +334,9 @@ a typical ``jbuild-workspace`` file looks like:
|
||||||
|
|
||||||
.. code:: scheme
|
.. code:: scheme
|
||||||
|
|
||||||
(context ((switch 4.02.3)))
|
(context (opam (switch 4.02.3)))
|
||||||
(context ((switch 4.03.0)))
|
(context (opam (switch 4.03.0)))
|
||||||
(context ((switch 4.04.0)))
|
(context (opam (switch 4.04.0)))
|
||||||
|
|
||||||
The rest of this section describe the stanzas available.
|
The rest of this section describe the stanzas available.
|
||||||
|
|
||||||
|
@ -354,13 +354,13 @@ context
|
||||||
~~~~~~~
|
~~~~~~~
|
||||||
|
|
||||||
The ``(context ...)`` stanza declares a build context. The argument
|
The ``(context ...)`` stanza declares a build context. The argument
|
||||||
can be either ``default`` for the default build context or can be the
|
can be either ``default`` or ``(default)`` for the default build
|
||||||
description of an opam switch, as follows:
|
context or can be the description of an opam switch, as follows:
|
||||||
|
|
||||||
.. code:: scheme
|
.. code:: scheme
|
||||||
|
|
||||||
(context ((switch <opam-switch-name>)
|
(context (opam (switch <opam-switch-name>)
|
||||||
<optional-fields>))
|
<optional-fields>))
|
||||||
|
|
||||||
``<optional-fields>`` are:
|
``<optional-fields>`` are:
|
||||||
|
|
||||||
|
@ -374,6 +374,10 @@ description of an opam switch, as follows:
|
||||||
- ``(merlin)`` instructs Jbuilder to use this build context for
|
- ``(merlin)`` instructs Jbuilder to use this build context for
|
||||||
merlin
|
merlin
|
||||||
|
|
||||||
|
Both ``(default ...)`` and ``(opam ...)`` accept a ``targets`` field
|
||||||
|
in order to setup cross compilation. See `Cross Compilation`_ for more
|
||||||
|
information.
|
||||||
|
|
||||||
Merlin reads compilation artifacts and it can only read the
|
Merlin reads compilation artifacts and it can only read the
|
||||||
compilation artifacts of a single context. Usually, you should use
|
compilation artifacts of a single context. Usually, you should use
|
||||||
the artifacts from the ``default`` context, and if you have the
|
the artifacts from the ``default`` context, and if you have the
|
||||||
|
@ -384,6 +388,15 @@ For rare cases where this is not what you want, you can force Jbuilder
|
||||||
to use a different build contexts for merlin by adding the field
|
to use a different build contexts for merlin by adding the field
|
||||||
``(merlin)`` to this context.
|
``(merlin)`` to this context.
|
||||||
|
|
||||||
|
Note that the following syntax is still accepted but is deprecated:
|
||||||
|
|
||||||
|
.. code:: scheme
|
||||||
|
|
||||||
|
(context ((switch <opam-switch-name>)
|
||||||
|
<optional-fields>))
|
||||||
|
|
||||||
|
it is interpreted the same as ``(context (opam (switch ...) ...))``.
|
||||||
|
|
||||||
Building JavaScript with js_of_ocaml
|
Building JavaScript with js_of_ocaml
|
||||||
====================================
|
====================================
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue