Variables
=========

.. TODO(diataxis)
   - reference: variables
   - explanation: rule loading

Some fields can contains variables that are expanded by Dune.
The syntax of variables is as follows:

.. code::

   %{var}

or, for more complex forms that take an argument:

.. code::

   %{fun:arg}

In order to write a plain ``%{``, you need to write ``\%{`` in a
string.

Dune supports the following variables:

- ``project_root`` is the root of the current project. It is typically the root
  of your project, and as long as you have a ``dune-project`` file there,
  ``project_root`` is independent of the workspace configuration.
- ``workspace_root`` is the root of the current workspace. Note that
  the value of ``workspace_root`` isn't constant and depends on
  whether your project is vendored or not.
-  ``cc`` is the C compiler command line (list made of the compiler
   name followed by its flags) that will be used to compile foreign code. For
   more details about its content, please see :doc:`/reference/foreign-flags`.
-  ``cxx`` is the C++ compiler command line being used in the
   current build context.
-  ``ocaml_bin`` is the path where ``ocamlc`` lives.
-  ``ocaml`` is the ``ocaml`` binary.
-  ``ocamlc`` is the ``ocamlc`` binary.
-  ``ocamlopt`` is the ``ocamlopt`` binary.
-  ``ocaml_version`` is the version of the compiler used in the
   current build context.
-  ``ocaml_where`` is the output of ``ocamlc -where``.
-  ``arch_sixtyfour`` is ``true`` if using a compiler that targets a
   64-bit architecture and ``false`` otherwise.
-  ``null`` is ``/dev/null`` on Unix or ``nul`` on Windows.
-  ``ext_obj``, ``ext_asm``, ``ext_lib``, ``ext_dll``, and ``ext_exe``
   are the file extensions used for various artifacts.
- ``ext_plugin`` is ``.cmxs`` if ``natdynlink`` is supported and
  ``.cma`` otherwise.
- ``ocaml-config:v`` is for every variable ``v`` in the output of
  ``ocamlc -config``. Note that Dune processes the output
  of ``ocamlc -config`` in order to make it a bit more stable across
  versions, so the exact set of variables accessible this way might
  not be exactly the same as what you can see in the output of
  ``ocamlc -config``. In particular, variables added in new OCaml versions
  need to be registered in Dune before they can be used.
- ``profile`` is the profile selected via ``--profile``.
- ``context_name`` is the name of the context (``default``, or defined in the
  workspace file)
- ``os_type`` is the type of the OS the build is targeting. This is
  the same as ``ocaml-config:os_type``.
- ``architecture`` is the type of the architecture the build is targeting. This
  is the same as ``ocaml-config:architecture``.
- ``model`` is the type of the CPU the build is targeting. This is
  the same as ``ocaml-config:model``.
- ``system`` is the name of the OS the build is targeting. This is the same as
  ``ocaml-config:system``.
- ``ignoring_promoted_rules`` is ``true`` if
  ``--ignore-promoted-rules`` was passed on the command line and
  ``false`` otherwise.
- ``<ext>:<path>`` where ``<ext>`` is one of ``cmo``, ``cmi``, ``cma``,
  ``cmx``, or ``cmxa``. See :ref:`variables-for-artifacts`.
- ``env:<var>=<default`` expands to the value of the environment
  variable ``<var>``, or ``<default>`` if it does not exist.
  For example, ``%{env:BIN=/usr/bin}``.
  Available since Dune 1.4.0.
- There are some Coq-specific variables detailed in :ref:`coq-variables`.

In addition, ``(action ...)`` fields support the following special variables:

- ``target`` expands to the one target.
- ``targets`` expands to the list of target.
- ``deps`` expands to the list of dependencies.
- ``^`` expands to the list of dependencies, separated by spaces.
- ``dep:<path>`` expands to ``<path>`` (and adds ``<path>`` as a dependency of
  the action).
- ``exe:<path>`` is the same as ``<path>``, except when cross-compiling, in
  which case it will expand to ``<path>`` from the host build context.
- ``bin:<program>`` expands ``<path>`` to ``program``. If ``program``
  is installed by a workspace package (see :doc:`/reference/dune/install`
  stanzas), the locally built binary will be used, otherwise it will be
  searched in the ``<path>`` of the current build context. Note that ``(run
  %{bin:program} ...)`` and ``(run program ...)`` behave in the same way.
  ``%{bin:...}`` is only necessary when you are using ``(bash ...)`` or
  ``(system ...)``.
- ``bin-available:<program>`` expands to ``true`` or ``false``, depending
  on whether ``<program>`` is available or not.
- ``file-available:<path>`` expands to ``true`` or ``false``, depending on
  whether the file at ``<path>`` is available in the current workspace.
- ``lib:<public-library-name>:<file>`` expands to the file's installation path
  ``<file>`` in the library ``<public-library-name>``. If
  ``<public-library-name>`` is available in the current workspace, the local
  file will be used, otherwise the one from the :term:`installed world` will be
  used.
- ``lib-private:<library-name>:<file>`` expands to the file's build path
  ``<file>`` in the library ``<library-name>``. Both public and private library
  names are allowed as long as they refer to libraries within the same project.
- ``libexec:<public-library-name>:<file>`` is the same as ``lib:...``, except
  when cross-compiling, in which case it will expand to the file from the host
  build context.
- ``libexec-private:<library-name>:<file>`` is the same as ``lib-private:...``
  except when cross-compiling, in which case it will expand to the file from the
  host build context.
- ``lib-available:<library-name>`` expands to ``true`` or ``false`` depending on
  whether the library is available or not. A library is available if at least
  one of the following conditions holds:

  -  It's part the :term:`installed world`.
  -  It's available locally and is not optional.
  -  It's available locally, and all its library dependencies are
     available.

- ``version:<package>`` expands to the version of the given
  package. Packages defined in the current scope have priority over the
  public packages. Public packages that don't install any libraries
  will not be detected. How Dune determines the version
  of a package is described :doc:`here <../advanced/package-version>`.
- ``read:<path>`` expands to the contents of the given file.
- ``read-lines:<path>`` expands to the list of lines in the given
  file.
- ``read-strings:<path>`` expands to the list of lines in the given
  file, unescaped using OCaml lexical convention.

The ``%{<kind>:...}`` forms are what allows you to write custom rules that work
transparently, whether things are installed or not.

Note that aliases are ignored by ``%{deps}``

The intent of this last form is to reliably read a list of strings
generated by an OCaml program via:

.. code:: ocaml

    List.iter (fun s -> print_string (String.escaped s)) l

#. Dealing with circular dependencies introduced by variables

If you ever see Dune reporting a dependency cycle that involves a
variable such as `%{read:<path>}`, try to move `<path>` to a different
directory.

The reason you might see such dependency cycle is because Dune is
trying to evaluate the `%{read:<path>}` too early. For instance, let's
consider the following example:

.. code:: dune

    (rule
     (targets x)
     (enabled_if %{read:y})
     (action ...))

    (rule
     (with-stdout-to y (...)))

When Dune loads and interprets this file, it decides whether the
first rule is enabled by evaluating ``%{read:y}``. To
evaluate ``%{read:y}``, it must build ``y``. To build ``y``, it must
figure out the build rule that produces ``y``, and in order to do that, it must
first load and evaluate the above ``dune`` file. You can see how this
creates a cycle.

Some cycles might be more complex. In any case, when you see such an
error, the easiest thing to do is move the file that's being read
to a different directory, preferably a standalone one. You can use the
:doc:`/reference/dune/subdir` stanza to keep the logic self-contained in
the same ``dune`` file:

.. code:: dune

    (rule
     (targets x)
     (enabled_if %{read:dir-for-y/y})
     (action ...))

    (subdir
     dir-for-y
     (rule
      (with-stdout-to y (...))))

Expansion of Lists
------------------

Forms that expand to a list of items, such as ``%{cc}``, ``%{deps}``,
``%{targets}``, or ``%{read-lines:...}``, are suitable to be used in
``(run <prog> <arguments>)``. For instance in:

.. code:: dune

    (run foo %{deps})

If there are two dependencies, ``a`` and ``b``, the produced command
will be equivalent to the shell command:

.. code:: console

    $ foo "a" "b"

If you want both dependencies to be passed as a single argument,
you must quote the variable:

.. code:: dune

    (run foo "%{deps}")

which is equivalent to the following shell command:

.. code:: console

    $ foo "a b"

(The items of the list are concatenated with space.)
Please note: since ``%{deps}`` is a list of items, the first one may be
used as a program name. For instance:

.. code:: dune

    (rule
     (targets result.txt)
     (deps    foo.exe (glob_files *.txt))
     (action  (run %{deps})))

Here is another example:

.. code:: dune

    (rule
     (target foo.exe)
     (deps   foo.c)
     (action (run %{cc} -o %{target} %{deps} -lfoolib)))