doc: add @pkg-install alias documentation (#11137)

Signed-off-by: Etienne Marais <[email protected]>
Signed-off-by: Christine Rose <[email protected]>
Co-authored-by: Christine Rose <[email protected]>

doc/reference/aliases.rst

@@ -69,6 +69,7 @@ Some aliases are defined and managed by Dune itself:
        aliases/all
        aliases/default
        aliases/install
+       aliases/pkg-install
 
   .. grid-item::
 

doc/reference/aliases/pkg-install.rst

@@ -0,0 +1,23 @@
+@pkg-install
+============
+
+This alias is only relevant when using Dune with *package management* (see
+:doc:`/tutorials/dune-package-management/index`). Running ``dune build
+@pkg-install`` will fetch the dependencies described in the ``depends`` field
+of your ``dune-project`` (see :doc:`/reference/dune-project/package`) and build
+them. It will not build your project.
+
+Indeed, if you need to build the project, you need to use the regular ``dune
+build`` command. Note that if the dependencies have not been already fetch and
+downloaded, ``dune build`` will **also** take care of getting and building them.
+
+.. note::
+    ``dune build @pkg-install`` is particularly useful when you are building
+    projects using per-layer caching systems, e.g., Docker images. Using this
+    alias, you will be able to cache the dependencies building stage as they
+    change less regularly.
+
+If you are building the ``@pkg-install`` alias in a repository where package
+management is not activated, the command has no effect.
+
+.. seealso:: :doc:`/explanation/package-management`

doc/tutorials/dune-package-management/setup.md

@@ -100,6 +100,17 @@ $ dune exec ./test.exe
 Hello, OCaml, Rust!
 ```
 
+:::{note}
+If you want to only build and fetch the project dependencies, you can use
+the `@pkg-install` alias like so
+
+```shell
+$ dune build @pkg-install
+```
+
+See {doc}`/reference/aliases/pkg-install` for more information.
+:::
+
 ## Conclusion
 
 In this section we learned how to set up a Dune project that picks a compiler