87 lines
3 KiB
ReStructuredText
87 lines
3 KiB
ReStructuredText
How to Set up Automatic Formatting
|
|
==================================
|
|
|
|
This guide will show you how to configure Dune so that it can check the formatting
|
|
of your source code.
|
|
|
|
Formatting is defined per project. This ensures that if a project is reused
|
|
elsewhere, its formatting configuration will not interfere.
|
|
|
|
Setting Up the Environment
|
|
--------------------------
|
|
|
|
First, let's open the ``dune-project`` file. Make sure that the version
|
|
specified in ``(lang dune X.Y)`` is at least ``2.0``. Most formatting
|
|
configuration happens in that file. If you want to format OCaml sources and
|
|
``dune`` files, you don't have anything to add. Otherwise, refer to the
|
|
:doc:`/reference/dune-project/formatting` stanza.
|
|
|
|
Next we need to install some code formatting tools. For OCaml code, this means
|
|
installing OCamlFormat_ with ``opam install ocamlformat``. Formatting ``dune``
|
|
files is built into Dune and does not require any extra tools. For Reason code,
|
|
this uses the ``refmt`` tool which is already installed if you are using Reason
|
|
syntax in your project. If your project uses a :term:`dialect`, a specific tool
|
|
might be required.
|
|
|
|
.. _ocamlformat: https://github.com/ocaml-ppx/ocamlformat
|
|
|
|
Using OCamlFormat requires some configuration. Take note of the version
|
|
returned by ``ocamlformat --version`` (let's name that ``X.Y.Z``) and create an
|
|
``.ocamlformat`` file in the same directory as ``dune-project`` with the
|
|
following contents:
|
|
|
|
.. code::
|
|
|
|
version=X.Y.Z
|
|
profile=default
|
|
|
|
The ``version`` line is checked by OCamlFormat and ensures that everybody
|
|
contributing to the project uses the same version.
|
|
|
|
Note that you do not have to add ``ocamlformat`` to your opam files.
|
|
|
|
Running the Formatters
|
|
----------------------
|
|
|
|
Run the ``dune build @fmt`` command. It will format the source files in the
|
|
corresponding project and display the differences:
|
|
|
|
.. code:: console
|
|
|
|
$ dune build @fmt
|
|
--- hello.ml
|
|
+++ hello.ml.formatted
|
|
@@ -1,3 +1 @@
|
|
-let () =
|
|
- print_endline
|
|
- "hello, world"
|
|
+let () = print_endline "hello, world"
|
|
|
|
Then it's possible to accept the correction by calling ``dune promote`` to
|
|
replace the source files with the corrected versions.
|
|
|
|
.. code:: console
|
|
|
|
$ dune promote
|
|
Promoting _build/default/hello.ml.formatted to hello.ml.
|
|
|
|
As usual with promotion, it's possible to combine these two steps by running
|
|
``dune build @fmt --auto-promote``. This command can also be shortened to
|
|
``dune fmt``. See :doc:`../concepts/promotion` for more details.
|
|
|
|
Setting Up Your CI
|
|
------------------
|
|
|
|
To check formatting in CI, the precise set up depends on the CI system used,
|
|
but in general it is easier to set up a dedicated job that just installs
|
|
``dune`` and the formatting tools, rather than doing that as part of the jobs
|
|
that run tests.
|
|
|
|
If you use `ocaml-ci`_, you have nothing to do: a formatting job is set up
|
|
automatically.
|
|
|
|
If you use `setup-ocaml`_, you can use the `lint-fmt` extend listed in the
|
|
README file.
|
|
|
|
.. _ocaml-ci: https://ocaml.ci.dev/
|
|
.. _setup-ocaml: https://github.com/ocaml/setup-ocaml
|