From 992aff211a3de24f0f0e23259fb091630f4b27ac Mon Sep 17 00:00:00 2001 From: Sudha Parimala Date: Thu, 16 Apr 2026 16:04:49 +0200 Subject: [PATCH 1/3] Add reference docs for `dune tools` Adds reference docs for `dune tools` as stated in #14184. The implementation of dev tools is subject to change, as being discussed in #13457. But parts of the user facing commands might stay and we might want to update the docs as the implementation is being fleshed out. Signed-off-by: Sudha Parimala --- doc/reference/cli.rst | 21 ++++ doc/reference/dune-tools.rst | 180 +++++++++++++++++++++++++++++++++++ doc/reference/index.rst | 1 + 3 files changed, 202 insertions(+) create mode 100644 doc/reference/dune-tools.rst diff --git a/doc/reference/cli.rst b/doc/reference/cli.rst index 9b52e1a0489..d990e40744c 100644 --- a/doc/reference/cli.rst +++ b/doc/reference/cli.rst @@ -221,6 +221,27 @@ documentation for each command is available through ``dune COMMAND --help``. Substitute watermarks in source files. +.. describe:: dune tools + + Command group for managing developer tools. See :doc:`dune-tools` for + details. + + .. describe:: dune tools exec + + Run a developer tool, automatically building it if needed. + + .. describe:: dune tools install + + Install a developer tool without running it. + + .. describe:: dune tools which + + Print the path to a developer tool's executable. + + .. describe:: dune tools env + + Print a command to add dev tool directories to your ``PATH``. + .. describe:: dune top Print a list of toplevel directives for including directories and loading diff --git a/doc/reference/dune-tools.rst b/doc/reference/dune-tools.rst new file mode 100644 index 00000000000..0e3584cb12c --- /dev/null +++ b/doc/reference/dune-tools.rst @@ -0,0 +1,180 @@ +dune tools +========== + +.. warning:: + + The ``dune tools`` command group is **experimental**. Its subcommands, + flags, and behavior may change in future versions of Dune without notice. + The internal APIs that power these commands are also subject to change. + + If you encounter issues, please `open an issue + `_ in the Dune issue tracker. + +``dune tools`` is a command group for managing developer tools. Developer tools +are programs that are useful for working on a project's source code but are not +required for building or deploying the project itself. Examples include +`ocamlformat `_, +`ocaml-lsp-server `_, and +`utop `_. + +Dune can automatically resolve, lock, build, and run these tools using package +management. Each tool is managed in its own lock directory under +``_build/.dev-tools.locks/``. + +Supported Tools +--------------- + +The following developer tools are currently supported: + +.. list-table:: + :header-rows: 1 + :widths: 20 20 20 + + * - Tool + - Executable + - Package + * - ocamlformat + - ``ocamlformat`` + - ``ocamlformat`` + * - odoc + - ``odoc`` + - ``odoc`` + * - ocaml-lsp-server + - ``ocamllsp`` + - ``ocaml-lsp-server`` + * - utop + - ``utop`` + - ``utop`` + * - ocamlearlybird + - ``ocamlearlybird`` + - ``earlybird`` + * - odig + - ``odig`` + - ``odig`` + * - opam-publish + - ``opam-publish`` + - ``opam-publish`` + * - dune-release + - ``dune-release`` + - ``dune-release`` + * - ocaml-index + - ``ocaml-index`` + - ``ocaml-index`` + * - merlin + - ``ocamlmerlin`` + - ``merlin`` + +.. note:: + + ``dune tools exec`` supports all tools above except ``odoc`` and ``utop``. + The ``install`` and ``which`` subcommands support all listed tools. + + ``odoc`` and ``utop`` have their own dedicated commands to execute: + + - ``utop`` is run via ``dune utop DIR``, which discovers libraries in the + given directory, configures library search paths, and generates a custom + ``findlib.conf`` so that utop can find dependencies within ``_build``. + - ``odoc`` is invoked via ``dune ocaml doc``, which builds documentation + using the ``@doc`` alias. + +Subcommands +----------- + +dune tools exec +~~~~~~~~~~~~~~~ + +.. code-block:: console + + $ dune tools exec [-- ...] + +Run a developer tool. Dune will automatically resolve, lock, and build the +tool if it has not been installed yet, then execute it. This is intended to be +called by text editors and other tooling that needs to invoke a dev tool. + +All positional arguments are forwarded to the tool's executable. +.. code-block:: console + + $ dune tools exec ocamlformat + $ dune tools exec --help + +dune tools install +~~~~~~~~~~~~~~~~~~ + +.. code-block:: console + + $ dune tools install + +Install a developer tool without running it. Dune will resolve dependencies, +create a separate lock directory, and build the tool. This is also useful for +pre-installing tools so that later ``exec`` or ``which`` calls are fast. + +.. code-block:: console + + $ dune tools install ocamlformat + $ dune tools install ocamllsp + +dune tools which +~~~~~~~~~~~~~~~~ + +.. code-block:: console + + $ dune tools which [--allow-not-installed] + +Print the path to a developer tool's executable. By default, this errors if +the tool has not been installed yet. + +Flags: + +* ``--allow-not-installed`` + Print the path where the tool would be installed, even if it does not + exist yet. + +.. code-block:: console + + $ dune tools which ocamlformat + _build/.dev-tools.locks/ocamlformat/ocamlformat/target/bin/ocamlformat + + $ dune tools which merlin --allow-not-installed + _build/.dev-tools.locks/merlin/merlin/target/bin/ocamlmerlin + +dune tools env +~~~~~~~~~~~~~~ + +.. code-block:: console + + $ dune tools env [--fish] + +Print a shell command that, when evaluated, adds all dev tool binary +directories to your ``PATH``. This allows running dev tools directly as +commands without going through ``dune tools exec``. + +Flags: + +* ``--fish`` + Emit a ``fish_add_path`` command suitable for the fish shell instead of + the default POSIX ``export PATH=...`` form. + + +For POSIX-compatible shells (bash, zsh, etc.): + +.. code-block:: console + + $ eval $(dune tools env) + +For the fish shell: + +.. code-block:: console + + $ eval (dune tools env --fish) + +.. note:: + + The design of ``dune tools`` is still being fleshed out and may be + reworked. See `dune#13457 `_ for + ongoing discussion. + +See Also +-------- + +- :doc:`/howto/customize-dev-tools-lock-directories` for customizing the lock + directory configuration of developer tools. diff --git a/doc/reference/index.rst b/doc/reference/index.rst index de2136e1c8b..e7ca41ab23c 100644 --- a/doc/reference/index.rst +++ b/doc/reference/index.rst @@ -65,6 +65,7 @@ These documents specify the various features and languages present in Dune. :caption: Dune Components cli + dune-tools ../dune-libs caches From e3a192d000c0029cda34df3ce7f3fbede095e104 Mon Sep 17 00:00:00 2001 From: Sudha Parimala Date: Mon, 20 Apr 2026 11:50:58 +0200 Subject: [PATCH 2/3] Address review comments Expand the note about utop and odoc. Add a warning in the cli reference. Signed-off-by: Sudha Parimala --- doc/reference/cli.rst | 5 +++++ doc/reference/dune-tools.rst | 11 +++++++---- 2 files changed, 12 insertions(+), 4 deletions(-) diff --git a/doc/reference/cli.rst b/doc/reference/cli.rst index d990e40744c..5a9657a87a0 100644 --- a/doc/reference/cli.rst +++ b/doc/reference/cli.rst @@ -226,6 +226,11 @@ documentation for each command is available through ``dune COMMAND --help``. Command group for managing developer tools. See :doc:`dune-tools` for details. + .. warning:: + + The ``dune tools`` command group is **experimental**. Its subcommands, + flags, and behavior may change in future versions of Dune without notice. + .. describe:: dune tools exec Run a developer tool, automatically building it if needed. diff --git a/doc/reference/dune-tools.rst b/doc/reference/dune-tools.rst index 0e3584cb12c..3605a083d01 100644 --- a/doc/reference/dune-tools.rst +++ b/doc/reference/dune-tools.rst @@ -71,11 +71,14 @@ The following developer tools are currently supported: ``odoc`` and ``utop`` have their own dedicated commands to execute: - - ``utop`` is run via ``dune utop DIR``, which discovers libraries in the - given directory, configures library search paths, and generates a custom - ``findlib.conf`` so that utop can find dependencies within ``_build``. + - ``utop`` is run via ``dune utop [DIR]``, which discovers libraries in the + given directory (defaults to working directory), configures library search + paths, and generates a custom ``findlib.conf`` so that utop can find + dependencies within ``_build``. ``utop`` needs to be installed via ``opam`` + or ``dune tools install utop`` before invoking this command. - ``odoc`` is invoked via ``dune ocaml doc``, which builds documentation - using the ``@doc`` alias. + using the ``@doc`` alias. As with ``utop``, ``odoc`` must be installed + before use. Subcommands ----------- From 24da09688bd76f09e80739444aa38ec461d0a002 Mon Sep 17 00:00:00 2001 From: Sudha Parimala Date: Tue, 21 Apr 2026 11:41:13 +0200 Subject: [PATCH 3/3] Address review comments Signed-off-by: Sudha Parimala --- doc/reference/cli.rst | 4 +++- doc/reference/dune-tools.rst | 27 ++++++++++++++------------- 2 files changed, 17 insertions(+), 14 deletions(-) diff --git a/doc/reference/cli.rst b/doc/reference/cli.rst index 5a9657a87a0..c2329b3870a 100644 --- a/doc/reference/cli.rst +++ b/doc/reference/cli.rst @@ -223,6 +223,8 @@ documentation for each command is available through ``dune COMMAND --help``. .. describe:: dune tools + .. versionadded:: 3.17 + Command group for managing developer tools. See :doc:`dune-tools` for details. @@ -245,7 +247,7 @@ documentation for each command is available through ``dune COMMAND --help``. .. describe:: dune tools env - Print a command to add dev tool directories to your ``PATH``. + Print a command to add developer tool directories to your ``PATH``. .. describe:: dune top diff --git a/doc/reference/dune-tools.rst b/doc/reference/dune-tools.rst index 3605a083d01..8022b16d12b 100644 --- a/doc/reference/dune-tools.rst +++ b/doc/reference/dune-tools.rst @@ -13,13 +13,14 @@ dune tools ``dune tools`` is a command group for managing developer tools. Developer tools are programs that are useful for working on a project's source code but are not required for building or deploying the project itself. Examples include -`ocamlformat `_, -`ocaml-lsp-server `_, and -`utop `_. +`ocamlformat `_ for formatting your +source code, `ocaml-lsp-server `_ which +provides a Language Server Protocol implementation for OCaml, and `utop +`_ an improved toplevel (REPL). Dune can automatically resolve, lock, build, and run these tools using package -management. Each tool is managed in its own lock directory under -``_build/.dev-tools.locks/``. +management. Each tool is managed in its own lock directory separate from the +project. Supported Tools --------------- @@ -83,8 +84,8 @@ The following developer tools are currently supported: Subcommands ----------- -dune tools exec -~~~~~~~~~~~~~~~ +``dune tools exec`` +~~~~~~~~~~~~~~~~~~~ .. code-block:: console @@ -100,8 +101,8 @@ All positional arguments are forwarded to the tool's executable. $ dune tools exec ocamlformat $ dune tools exec --help -dune tools install -~~~~~~~~~~~~~~~~~~ +``dune tools install`` +~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: console @@ -116,8 +117,8 @@ pre-installing tools so that later ``exec`` or ``which`` calls are fast. $ dune tools install ocamlformat $ dune tools install ocamllsp -dune tools which -~~~~~~~~~~~~~~~~ +``dune tools which`` +~~~~~~~~~~~~~~~~~~~~ .. code-block:: console @@ -140,8 +141,8 @@ Flags: $ dune tools which merlin --allow-not-installed _build/.dev-tools.locks/merlin/merlin/target/bin/ocamlmerlin -dune tools env -~~~~~~~~~~~~~~ +``dune tools env`` +~~~~~~~~~~~~~~~~~~ .. code-block:: console