diff --git a/doc/reference/cli.rst b/doc/reference/cli.rst index 9b52e1a0489..c2329b3870a 100644 --- a/doc/reference/cli.rst +++ b/doc/reference/cli.rst @@ -221,6 +221,34 @@ documentation for each command is available through ``dune COMMAND --help``. Substitute watermarks in source files. +.. describe:: dune tools + + .. versionadded:: 3.17 + + 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. + + .. 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 developer 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..8022b16d12b --- /dev/null +++ b/doc/reference/dune-tools.rst @@ -0,0 +1,184 @@ +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 `_ 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 separate from the +project. + +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 (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. As with ``utop``, ``odoc`` must be installed + before use. + +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