diff --git a/doc/reference/aliases.rst b/doc/reference/aliases.rst index 504e4499611..d3ac533cd5d 100644 --- a/doc/reference/aliases.rst +++ b/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:: diff --git a/doc/reference/aliases/pkg-install.rst b/doc/reference/aliases/pkg-install.rst new file mode 100644 index 00000000000..a6c0e554fab --- /dev/null +++ b/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` diff --git a/doc/tutorials/dune-package-management/setup.md b/doc/tutorials/dune-package-management/setup.md index 4a394c3ea94..8430b176dbb 100644 --- a/doc/tutorials/dune-package-management/setup.md +++ b/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