Doc & CHANGES

Signed-off-by: Rudi Grinberg <me@rgrinberg.com>

CHANGES.md

@@ -32,6 +32,9 @@ Unreleased
 - `dune upgrade` will now try to upgrade projects using versions <2.0 to version
   2.0 of the dune language. (#3174, @voodoos)
 
+- Add a `(chdir ..)` stanza to allow evaluating stanzas in sub directories.
+  (#3268, @rgrinberg)
+
 2.4.0 (06/03/2020)
 ------------------
 

doc/dune-files.rst

@@ -1497,6 +1497,29 @@ run this toplevel with:
 
    $ dune exec ./tt.exe
 
+chdir
+-----
+
+The ``chdir`` stanza can be used to evaluate stanzas in sub directories. This is
+useful for generated files or to override stanzas in vendored direcotries
+without editing vendored dune files.
+
+In this example, a ``bar`` target is created in the ``foo`` directory, and a bar
+target will be created in ``a/b/bar``:
+
+.. code:: scheme
+
+   (chdir foo (rule (with-stdout-to bar (echo baz))))
+   (chdir a/b (rule (with-stdout-to bar (echo baz))))
+
+To override a dune file in a sub-directory, we set the sub directory to be data
+only and then insert dune stanzas with ``chdir``:
+
+.. code:: scheme
+
+   (data_only_dirs vendored)
+   (chdir vendored (library (name bar)))
+
 external_variant
 -----------------