Update the doc

CHANGES.md

@@ -19,13 +19,19 @@ next
   absolute path but with the context's environment set appropriately. Lastly,
   `jbuilder exec` will change the root as to which paths are relative using the
   `-root` option. (#286)
-  
+
 - Fix `jbuilder rules` printing rules when some binaries are missing (#292)
 
 - Build documentation for non public libraries (#306)
 
 - Fix doc generation when several private libraries have the same name (#369)
 
+- Add support for cross-compilation. Currently we are supporting the
+  opam-cross-x repositories such as
+  [opam-cross-windows](https://github.com/whitequark/opam-cross-windows)
+  (#355)
+
+
 1.0+beta16 (05/11/2017)
 -----------------------
 

doc/advanced-topics.rst

@@ -105,42 +105,87 @@ set of predicates:
 Cross Compilation
 =================
 
-Jbuilder allows for cross compilation by defining a workspace with multiple
-contexts and defining a host-target relationship between the contexts.
+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.
 
-For example, the following defines a workspace where the target context is the
-switch ``4.05.0+mingw``, while the host switch is ``4.05.0``:
+``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 ((switch 4.05.0)))
-    (context ((switch 4.05.0+mingw) (host 4.05.0)))
+   (context (default (targets (foo))))
 
-In such a setup, binaries that need to be built and executed in the target
-context as part of the build, will no longer be executed. Instead, all the
-binaries that will be executed will come from the host context. One consequence
-of this is that all preprocessing (ppx or otherwise) will be done using binaries
-built on the host context.
+If you have a ``jbuild-workspace`` and pass a ``-x foo`` option,
+``foo`` will be added as target of all context stanzas.
 
-To clarify this with an example, let's assume that you have the following
-``src/jbuild`` file:
+How does it work?
+-----------------
 
-... code:: scheme
+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.
 
-  (executable ((name foo)))
-  (rule (with-stdout-to blah (run ./foo.exe)))
+To clarify this with an example, let's assume that you have the
+following ``src/jbuild`` file:
+
+.. code:: scheme
 
-When building ``_build/4.05.0/src/blah``, jbuilder will resolve ``./foo.exe`` to
-``_build/4.05.0/src/foo.exe`` as expected. However, for
-``_build/4.05.0+mingw/src/blah`` jbuilder will resolve ``./foo.exe`` to
-``_build/4.05.0/src/foo.exe`` since it knows 4.05.0 is the host context for
-``4.05.0+mingw``.
+    (executable ((name foo)))
+    (rule (with-stdout-to blah (run ./foo.exe)))
 
-We should never end up trying to call ``mingw-ocamlrun``, so there is no need for
-it.
+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 in both opam switches, jbuilder
-will be able to cross-compile a given package without doing anything special.
+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

doc/usage.rst

@@ -334,9 +334,9 @@ a typical ``jbuild-workspace`` file looks like:
 
 .. code:: scheme
 
-    (context ((switch 4.02.3)))
-    (context ((switch 4.03.0)))
-    (context ((switch 4.04.0)))
+    (context (opam (switch 4.02.3)))
+    (context (opam (switch 4.03.0)))
+    (context (opam (switch 4.04.0)))
 
 The rest of this section describe the stanzas available.
 
@@ -354,13 +354,13 @@ context
 ~~~~~~~
 
 The ``(context ...)`` stanza declares a build context. The argument
-can be either ``default`` for the default build context or can be the
-description of an opam switch, as follows:
+can be either ``default`` or ``(default)`` for the default build
+context or can be the description of an opam switch, as follows:
 
 .. code:: scheme
 
-    (context ((switch <opam-switch-name>)
-              <optional-fields>))
+    (context (opam (switch <opam-switch-name>)
+                   <optional-fields>))
 
 ``<optional-fields>`` are:
 
@@ -374,6 +374,10 @@ description of an opam switch, as follows:
 - ``(merlin)`` instructs Jbuilder to use this build context for
    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
 compilation artifacts of a single context.  Usually, you should use
 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
 ``(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
 ====================================
 

jbuild-workspace.dev

@@ -1,7 +1,7 @@
 ;; This file is used by `make all-supported-ocaml-versions`
-(context ((switch 4.02.3)))
-(context ((switch 4.03.0)))
-(context ((switch 4.04.2)))
-(context ((switch 4.05.0)))
-(context ((switch 4.06.0)))
-(context ((switch 4.07.0+trunk)))
+(context (opam (switch 4.02.3)))
+(context (opam (switch 4.03.0)))
+(context (opam (switch 4.04.2)))
+(context (opam (switch 4.05.0)))
+(context (opam (switch 4.06.0)))
+(context (opam (switch 4.07.0+trunk)))