More docs and tests for installing source_trees

Signed-off-by: Stephen Sherratt <stephen@sherra.tt>

doc/stanzas/install.rst

@@ -106,6 +106,15 @@ installed with mode ``0o644`` (``rw-r--r--``).
 Note that all files in the install stanza must be specified by relative paths
 only. It is an error to specify files by absolute paths.
 
+Also note that as of Dune 3.11 it is deprecated to use the ``as`` keyword to
+specify a destination beginning with ``..``. Dune intends for files associated
+with a package to only be installed under specific directories in the file
+system implied by the installation section (e.g. ``share``, ``bin``, ``doc``,
+etc.) and the package name. Starting destination paths with ``..`` allows
+packages to install files to arbitrary locations on the file system. In 3.11
+this behaviour is still supported (as some projects may depend on it) but will
+generate a warning and will be removed in a future version of Dune.
+
 Including Files in the Install Stanza
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -187,4 +196,34 @@ To install entire source directories, the ``source_tree`` field can be used:
 
    (install
     (section doc)
-    (source_trees doc))
+    (source_trees manual))
+
+This example results in the contents of the ``manual`` directory being installed
+under ``<prefix>/doc/<package>/manual/``.
+
+As with ``(files ...)`` the destination can be changed with the ``as`` keyword.
+For example if you want to install all the files in the ``manual`` directory
+directly into ``<prefix>/doc/<package/`` you can write:
+
+.. code:: dune
+
+   (install
+    (section doc)
+    (source_trees (manual as .)))
+
+It's also possible to specify multiple directories:
+
+.. code:: dune
+
+   (install
+    (section doc)
+    (source_trees manual examples))
+
+This would result in the local directories ``manual`` and ``examples`` being
+installed to ``<prefix>/doc/<package>/manual/`` and
+``<prefix>/doc/<package>/examples/`` respectively.
+
+Unlike with ``(files ...)`` it is an error to begin the destination (the
+right-hand side of ``as``) with ``..``. (This is because support for installing
+source directories was added to Dune after destinations beginning with ``..``
+were deprecated.)

test/blackbox-tests/test-cases/install/install-source-tree.t

@@ -72,3 +72,37 @@ It is an error for the destination path to start with "..".
   Destinations in install stanzas may not begin with .. to prevent a package's
   installed files from escaping that package's install directories.
   [1]
+
+Install docs directly into docs/<pkg>/:
+  $ test "(mydocs as .)"
+  lib: [
+    "_build/install/default/lib/mypkg/META"
+    "_build/install/default/lib/mypkg/dune-package"
+  ]
+  doc: [
+    "_build/install/default/doc/mypkg/baz.md" {"./baz.md"}
+    "_build/install/default/doc/mypkg/foo.md" {"./foo.md"}
+    "_build/install/default/doc/mypkg/foo/bar.md" {"./foo/bar.md"}
+  ]
+
+Install multiple source trees at once:
+  $ mkdir otherdocs
+  $ touch otherdocs/help.txt
+  $ test "mydocs otherdocs"
+  lib: [
+    "_build/install/default/lib/mypkg/META"
+    "_build/install/default/lib/mypkg/dune-package"
+  ]
+  doc: [
+    "_build/install/default/doc/mypkg/mydocs/baz.md" {"mydocs/baz.md"}
+    "_build/install/default/doc/mypkg/mydocs/foo.md" {"mydocs/foo.md"}
+    "_build/install/default/doc/mypkg/mydocs/foo/bar.md" {"mydocs/foo/bar.md"}
+    "_build/install/default/doc/mypkg/otherdocs/help.txt" {"otherdocs/help.txt"}
+  ]
+
+Install zero source trees:
+  $ test ""
+  lib: [
+    "_build/install/default/lib/mypkg/META"
+    "_build/install/default/lib/mypkg/dune-package"
+  ]