<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Project Layout and Metadata Specification — dune documentation</title>
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="dune files" href="dune-files.html" />
<link rel="prev" title="Terminology" href="terminology.html" />
<script src="_static/js/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search">
<a href="index.html" class="icon icon-home"> dune
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="quick-start.html">Quickstart</a></li>
<li class="toctree-l1"><a class="reference internal" href="overview.html">Overview</a></li>
<li class="toctree-l1"><a class="reference internal" href="terminology.html">Terminology</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Project Layout and Metadata Specification</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#metadata-format">Metadata format</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#comments">Comments</a></li>
<li class="toctree-l3"><a class="reference internal" href="#atoms">Atoms</a></li>
<li class="toctree-l3"><a class="reference internal" href="#strings">Strings</a></li>
<li class="toctree-l3"><a class="reference internal" href="#end-of-line-strings">End of line strings</a></li>
<li class="toctree-l3"><a class="reference internal" href="#lists">Lists</a></li>
<li class="toctree-l3"><a class="reference internal" href="#variables">Variables</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#dune-project-files">dune-project files</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#name">name</a></li>
<li class="toctree-l3"><a class="reference internal" href="#version">version</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#package-opam-files"><package>.opam files</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#scopes">Scopes</a></li>
<li class="toctree-l3"><a class="reference internal" href="#package-version">Package version</a></li>
<li class="toctree-l3"><a class="reference internal" href="#odig-conventions">Odig conventions</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#jbuild-ignore-deprecated">jbuild-ignore (deprecated)</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="dune-files.html">dune files</a></li>
<li class="toctree-l1"><a class="reference internal" href="tests.html">Writing and running tests</a></li>
<li class="toctree-l1"><a class="reference internal" href="documentation.html">Generating Documentation</a></li>
<li class="toctree-l1"><a class="reference internal" href="usage.html">Usage</a></li>
<li class="toctree-l1"><a class="reference internal" href="advanced-topics.html">Advanced topics</a></li>
<li class="toctree-l1"><a class="reference internal" href="configurator.html">Configurator</a></li>
<li class="toctree-l1"><a class="reference internal" href="menhir.html">Menhir</a></li>
<li class="toctree-l1"><a class="reference internal" href="faq.html">FAQ</a></li>
<li class="toctree-l1"><a class="reference internal" href="known-issues.html">Known Issues</a></li>
<li class="toctree-l1"><a class="reference internal" href="migration.html">Migration</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">dune</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html">Docs</a> »</li>
<li>Project Layout and Metadata Specification</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/project-layout-specification.rst.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="project-layout-and-metadata-specification">
<h1>Project Layout and Metadata Specification<a class="headerlink" href="#project-layout-and-metadata-specification" title="Permalink to this headline">¶</a></h1>
<p>A typical dune project will have a <code class="docutils literal notranslate"><span class="pre">`dune-project</span></code> and one or more
<code class="docutils literal notranslate"><span class="pre"><package>.opam</span></code> file at toplevel as well as <code class="docutils literal notranslate"><span class="pre">dune</span></code> files wherever
interesting things are: libraries, executables, tests, documents to install,
etc…</p>
<p>It is recommended to organize your project so that you have exactly one library
per directory. You can have several executables in the same directory, as long
as they share the same build configuration. If you’d like to have multiple
executables with different configurations in the same directory, you will have
to make an explicit module list for every executable using <code class="docutils literal notranslate"><span class="pre">modules</span></code>.</p>
<p>The next sections describe the format of dune metadata files.</p>
<p>Note that the dune metadata format is versioned in order to ensure forward
compatibility. There is currently only one version available, but to be future
proof, you should still specify it in your <code class="docutils literal notranslate"><span class="pre">dune</span></code> files. If no version is
specified, the latest one will be used.</p>
<div class="section" id="metadata-format">
<span id="id1"></span><h2>Metadata format<a class="headerlink" href="#metadata-format" title="Permalink to this headline">¶</a></h2>
<p>All configuration files read by Dune are using a syntax similar to the
one of S-expressions, which is very simple. The Dune language can
represent three kinds of values: atoms, strings and lists. By
combining these, it is possible to construct arbitrarily complex
project descriptions.</p>
<p>A Dune configuration file is a sequence of atoms, strings or lists
separated by spaces, newlines and comments. The other sections of this
manual describe how each configuration file is interpreted. We
describe below the syntax of the language.</p>
<div class="section" id="comments">
<h3>Comments<a class="headerlink" href="#comments" title="Permalink to this headline">¶</a></h3>
<p>The Dune language only has end of line comments. End of line comments
are introduced with a semicolon and span up to the end of the end of
the current line. Everything from the semicolon to the end of the line
is ignored. For instance:</p>
<div class="code highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">;</span> <span class="n">This</span> <span class="ow">is</span> <span class="n">a</span> <span class="n">comment</span>
</pre></div>
</div>
</div>
<div class="section" id="atoms">
<h3>Atoms<a class="headerlink" href="#atoms" title="Permalink to this headline">¶</a></h3>
<p>An atom is a non-empty contiguous sequences of character other than
special characters. Special characters are:</p>
<ul class="simple">
<li>spaces, horizontal tabs, newlines and form feed</li>
<li>opening and closing parenthesis</li>
<li>double quotes</li>
<li>semicolons</li>
</ul>
<p>For instance <code class="docutils literal notranslate"><span class="pre">hello</span></code> or <code class="docutils literal notranslate"><span class="pre">+</span></code> are valid atoms.</p>
<p>Note that backslashes inside atoms have no special meaning are always
interpreted as plain backslashes characters.</p>
</div>
<div class="section" id="strings">
<h3>Strings<a class="headerlink" href="#strings" title="Permalink to this headline">¶</a></h3>
<p>A string is a sequence of characters surrounded by double quotes. A
string represent the exact text between the double quotes, except for
escape sequences. Escape sequence are introduced by the a backslash
character. Dune recognizes and interprets the following escape
sequences:</p>
<ul class="simple">
<li><code class="docutils literal notranslate"><span class="pre">\n</span></code> to represent a newline character</li>
<li><code class="docutils literal notranslate"><span class="pre">\r</span></code> to represent a carriage return (character with ASCII code 13)</li>
<li><code class="docutils literal notranslate"><span class="pre">\b</span></code> to represent ASCII character 8</li>
<li><code class="docutils literal notranslate"><span class="pre">\t</span></code> to represent a horizontal tab</li>
<li><code class="docutils literal notranslate"><span class="pre">\NNN</span></code>, a backslash followed by three decimal characters to
represent the character with ASCII code <code class="docutils literal notranslate"><span class="pre">NNN</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">\xHH</span></code>, a backslash followed by two hexadecimal characters to
represent the character with ASCII code <code class="docutils literal notranslate"><span class="pre">HH</span></code> in hexadecimal</li>
<li><code class="docutils literal notranslate"><span class="pre">\\</span></code>, a double backslash to represent a single backslash</li>
<li><code class="docutils literal notranslate"><span class="pre">\%{</span></code> to represent <code class="docutils literal notranslate"><span class="pre">%{</span></code> (see <a class="reference internal" href="#variables"><span class="std std-ref">Variables</span></a>)</li>
</ul>
<p>Additionally, a backslash that comes just before the end of the line
is used to skip the newline up to the next non-space character. For
instance the following two strings represent the same text:</p>
<div class="code highlight-default notranslate"><div class="highlight"><pre><span></span><span class="s2">"abcdef"</span>
<span class="s2">"abc</span><span class="se">\</span>
<span class="s2"> def"</span>
</pre></div>
</div>
<p>In most places where Dune expect a string, it will also accept an
atom. As a result it possible to write most Dune configuration file
using very few double quotes. This is very convenient in practice.</p>
</div>
<div class="section" id="end-of-line-strings">
<h3>End of line strings<a class="headerlink" href="#end-of-line-strings" title="Permalink to this headline">¶</a></h3>
<p>End of line strings are another way to write strings. The are a
convenient way to write blocks of text inside a Dune file.</p>
<p>End of line strings are introduced by <code class="docutils literal notranslate"><span class="pre">"\|</span></code> or <code class="docutils literal notranslate"><span class="pre">"\></span></code> and span up
the end of the current line. If the next line starts as well by
<code class="docutils literal notranslate"><span class="pre">"\|</span></code> or <code class="docutils literal notranslate"><span class="pre">"\></span></code> it is the continuation of the same string. For
readability, it is necessary that the text that follows the delimiter
is either empty or starts with a space that is ignored.</p>
<p>For instance:</p>
<div class="code highlight-default notranslate"><div class="highlight"><pre><span></span><span class="s2">"\| this is a block</span>
<span class="s2">"\| of text</span>
</pre></div>
</div>
<p>represent the same text as the string <code class="docutils literal notranslate"><span class="pre">"this</span> <span class="pre">is</span> <span class="pre">a</span> <span class="pre">block\nof</span> <span class="pre">text"</span></code>.</p>
<p>Escape sequences are interpreted in text that follows <code class="docutils literal notranslate"><span class="pre">"\|</span></code> but not
in text that follows <code class="docutils literal notranslate"><span class="pre">"\></span></code>. Both delimiters can be mixed inside the
same block of text.</p>
</div>
<div class="section" id="lists">
<h3>Lists<a class="headerlink" href="#lists" title="Permalink to this headline">¶</a></h3>
<p>Lists are sequences of values enclosed by parentheses. For instance
<code class="docutils literal notranslate"><span class="pre">(x</span> <span class="pre">y</span> <span class="pre">z)</span></code> is a list containing the three atoms <code class="docutils literal notranslate"><span class="pre">x</span></code>, <code class="docutils literal notranslate"><span class="pre">y</span></code> and
<code class="docutils literal notranslate"><span class="pre">z</span></code>. Lists can be empty, for instance: <code class="docutils literal notranslate"><span class="pre">()</span></code>.</p>
<p>Lists can be nested, allowing to represent arbitrarily complex
descriptions. For instance:</p>
<div class="code highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="n">html</span>
<span class="p">(</span><span class="n">head</span> <span class="p">(</span><span class="n">title</span> <span class="s2">"Hello world!"</span><span class="p">))</span>
<span class="p">(</span><span class="n">body</span>
<span class="n">This</span> <span class="ow">is</span> <span class="n">a</span> <span class="n">simple</span> <span class="n">example</span> <span class="n">of</span> <span class="n">using</span> <span class="n">S</span><span class="o">-</span><span class="n">expressions</span><span class="p">))</span>
</pre></div>
</div>
</div>
<div class="section" id="variables">
<span id="id2"></span><h3>Variables<a class="headerlink" href="#variables" title="Permalink to this headline">¶</a></h3>
<p>Dune allows variables in a few places. Their interpretation often
depend on the context in which they appear.</p>
<p>The syntax of variables is as follow:</p>
<div class="code highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">%</span><span class="p">{</span><span class="n">var</span><span class="p">}</span>
</pre></div>
</div>
<p>or, for more complex forms that take an argument:</p>
<div class="code highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">%</span><span class="p">{</span><span class="n">fun</span><span class="p">:</span><span class="n">arg</span><span class="p">}</span>
</pre></div>
</div>
<p>In order to write a plain <code class="docutils literal notranslate"><span class="pre">%{</span></code>, you need to write <code class="docutils literal notranslate"><span class="pre">\%{</span></code> in a
string.</p>
</div>
</div>
<div class="section" id="dune-project-files">
<span id="opam-files"></span><h2>dune-project files<a class="headerlink" href="#dune-project-files" title="Permalink to this headline">¶</a></h2>
<p>These files are used to mark the root of projects as well as define project-wide
parameters. These files are required to have a <code class="docutils literal notranslate"><span class="pre">lang</span></code> which controls the names
and contents of all configuration files read by Dune. The <code class="docutils literal notranslate"><span class="pre">lang</span></code> stanza looks
like:</p>
<div class="code scheme highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="n">lang</span> <span class="n">dune</span> <span class="mf">0.1</span><span class="p">)</span>
</pre></div>
</div>
<p>The 0.1 version of the language is exactly the same as the Jbuilder language. So
to convert a Jbuilder project to Dune, simply write this file at the root of
your project.</p>
<p>Additionally, they can contains the following stanzas.</p>
<div class="section" id="name">
<h3>name<a class="headerlink" href="#name" title="Permalink to this headline">¶</a></h3>
<p>Sets the name of the project:</p>
<div class="code scheme highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="n">name</span> <span class="o"><</span><span class="n">name</span><span class="o">></span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="version">
<h3>version<a class="headerlink" href="#version" title="Permalink to this headline">¶</a></h3>
<p>Sets the version of the project:</p>
<div class="code scheme highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="n">version</span> <span class="o"><</span><span class="n">version</span><span class="o">></span><span class="p">)</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="package-opam-files">
<h2><package>.opam files<a class="headerlink" href="#package-opam-files" title="Permalink to this headline">¶</a></h2>
<p>When a <code class="docutils literal notranslate"><span class="pre"><package>.opam</span></code> file is present, dune will know that the
package named <code class="docutils literal notranslate"><span class="pre"><package></span></code> exists. It will know how to construct a
<code class="docutils literal notranslate"><span class="pre"><package>.install</span></code> file in the same directory to handle installation
via <a class="reference external" href="https://opam.ocaml.org/">opam</a>. Dune also defines the
recursive <code class="docutils literal notranslate"><span class="pre">install</span></code> alias, which depends on all the buildable
<code class="docutils literal notranslate"><span class="pre"><package>.install</span></code> files in the workspace. So for instance to build
everything that is installable in a workspace, run at the root:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ dune build @install
</pre></div>
</div>
<p>Declaring a package this way will allow you to add elements such as libraries,
executables, documentation, … to your package by declaring them in <code class="docutils literal notranslate"><span class="pre">dune</span></code>
files.</p>
<p>Such elements can only be declared in the scope defined by the
corresponding <code class="docutils literal notranslate"><span class="pre"><package>.opam</span></code> file. Typically, your
<code class="docutils literal notranslate"><span class="pre"><package>.opam</span></code> files should be at the root of your project, since
this is where <code class="docutils literal notranslate"><span class="pre">opam</span> <span class="pre">pin</span> <span class="pre">...</span></code> will look for them.</p>
<p>Note that <code class="docutils literal notranslate"><span class="pre"><package></span></code> must be non-empty, so in particular <code class="docutils literal notranslate"><span class="pre">.opam</span></code>
files are ignored.</p>
<div class="section" id="scopes">
<span id="id3"></span><h3>Scopes<a class="headerlink" href="#scopes" title="Permalink to this headline">¶</a></h3>
<p>Any directory containing at least one <code class="docutils literal notranslate"><span class="pre"><package>.opam</span></code> file defines
a scope. This scope is the sub-tree starting from this directory,
excluding any other scopes rooted in sub-direcotries.</p>
<p>Typically, any given project will define a single scope. Libraries and
executables that are not meant to be installed will be visible inside
this scope only.</p>
<p>Because scopes are exclusive, if you wish to include the dependencies
of the project you are currently working on into your workspace, you
may copy them in a <code class="docutils literal notranslate"><span class="pre">vendor</span></code> directory, or any other name of your
choice. Dune will look for them there rather than in the installed
world and there will be no overlap between the various scopes.</p>
</div>
<div class="section" id="package-version">
<h3>Package version<a class="headerlink" href="#package-version" title="Permalink to this headline">¶</a></h3>
<p>Note that dune will try to determine the version number of packages
defined in the workspace. While dune itself makes no use of version
numbers, it can be use by external tools such as
<a class="reference external" href="http://projects.camlcity.org/projects/findlib.html">ocamlfind</a>.</p>
<p>Dune determines the version of a package by trying the following
methods in order:</p>
<ul class="simple">
<li>it looks in the <code class="docutils literal notranslate"><span class="pre"><package>.opam</span></code> file for a <code class="docutils literal notranslate"><span class="pre">version</span></code> variable</li>
<li>it looks for a <code class="docutils literal notranslate"><span class="pre"><package>.version</span></code> file in the same directory and
reads the first line</li>
<li>it looks for the version specified in the <code class="docutils literal notranslate"><span class="pre">dune-project</span></code> if present</li>
<li>it looks for a <code class="docutils literal notranslate"><span class="pre">version</span></code> file and reads the first line</li>
<li>it looks for a <code class="docutils literal notranslate"><span class="pre">VERSION</span></code> file and reads the first line</li>
</ul>
<p><code class="docutils literal notranslate"><span class="pre"><package>.version</span></code>, <code class="docutils literal notranslate"><span class="pre">version</span></code> and <code class="docutils literal notranslate"><span class="pre">VERSION</span></code> files may be
generated.</p>
<p>If the version can’t be determined, dune just won’t assign one.</p>
</div>
<div class="section" id="odig-conventions">
<h3>Odig conventions<a class="headerlink" href="#odig-conventions" title="Permalink to this headline">¶</a></h3>
<p>Dune follows the <a class="reference external" href="http://erratique.ch/software/odig">odig</a>
conventions and automatically installs any README*, CHANGE*, HISTORY*
and LICENSE* files in the same directory as the <code class="docutils literal notranslate"><span class="pre"><package>.opam</span></code> file
to a location where odig will find them.</p>
<p>Note that this includes files present in the source tree as well as
generated files. So for instance a changelog generated by a user rule
will be automatically installed as well.</p>
</div>
</div>
<div class="section" id="jbuild-ignore-deprecated">
<h2>jbuild-ignore (deprecated)<a class="headerlink" href="#jbuild-ignore-deprecated" title="Permalink to this headline">¶</a></h2>
<p><code class="docutils literal notranslate"><span class="pre">jbuild-ignore</span></code> files are deprecated and replaced by
<a class="reference internal" href="dune-files.html#dune-ignored-subdirs"><span class="std std-ref">ignored_subdirs</span></a> stanzas in <code class="docutils literal notranslate"><span class="pre">dune</span></code> files.</p>
</div>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="dune-files.html" class="btn btn-neutral float-right" title="dune files" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="terminology.html" class="btn btn-neutral" title="Terminology" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>
© Copyright 2017, Jérémie Dimino
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/rtfd/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'./',
VERSION:'',
LANGUAGE:'None',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>
distrib
>
Mageia
>
7
>
armv7hl
>
media
>
core-release
>
by-pkgid
>
f068986ecc5d051850d4ea04085e7314
>
files
>
89
