<!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>Usage — 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="Advanced topics" href="advanced-topics.html" />
<link rel="prev" title="Generating Documentation" href="documentation.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"><a class="reference internal" href="project-layout-specification.html">Project Layout and Metadata Specification</a></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 current"><a class="current reference internal" href="#">Usage</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#finding-the-root">Finding the root</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#dune-workspace">dune-workspace</a></li>
<li class="toctree-l3"><a class="reference internal" href="#current-directory">Current directory</a></li>
<li class="toctree-l3"><a class="reference internal" href="#forcing-the-root-for-scripts">Forcing the root (for scripts)</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#interpretation-of-targets">Interpretation of targets</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#resolution">Resolution</a></li>
<li class="toctree-l3"><a class="reference internal" href="#aliases">Aliases</a></li>
<li class="toctree-l3"><a class="reference internal" href="#default-alias">Default alias</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#finding-external-libraries">Finding external libraries</a></li>
<li class="toctree-l2"><a class="reference internal" href="#running-tests">Running tests</a></li>
<li class="toctree-l2"><a class="reference internal" href="#launching-the-toplevel-repl">Launching the Toplevel (REPL)</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#requirements-limitations">Requirements & Limitations</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#restricting-the-set-of-packages">Restricting the set of packages</a></li>
<li class="toctree-l2"><a class="reference internal" href="#invocation-from-opam">Invocation from opam</a></li>
<li class="toctree-l2"><a class="reference internal" href="#tests">Tests</a></li>
<li class="toctree-l2"><a class="reference internal" href="#installation">Installation</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#destination">Destination</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#workspace-configuration">Workspace configuration</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#id4">dune-workspace</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#profile">profile</a></li>
<li class="toctree-l4"><a class="reference internal" href="#context">context</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#building-javascript-with-js-of-ocaml">Building JavaScript with js_of_ocaml</a></li>
<li class="toctree-l2"><a class="reference internal" href="#distributing-projects">Distributing Projects</a></li>
<li class="toctree-l2"><a class="reference internal" href="#watermarking">Watermarking</a></li>
<li class="toctree-l2"><a class="reference internal" href="#dune-subst">dune subst</a></li>
<li class="toctree-l2"><a class="reference internal" href="#custom-build-directory">Custom Build Directory</a></li>
</ul>
</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>Usage</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/usage.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="usage">
<h1>Usage<a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h1>
<p>This section describe usage of dune from the shell.</p>
<div class="section" id="finding-the-root">
<span id="finding-root"></span><h2>Finding the root<a class="headerlink" href="#finding-the-root" title="Permalink to this headline">¶</a></h2>
<div class="section" id="dune-workspace">
<span id="id1"></span><h3>dune-workspace<a class="headerlink" href="#dune-workspace" title="Permalink to this headline">¶</a></h3>
<p>The root of the current workspace is determined by looking up a
<code class="docutils literal notranslate"><span class="pre">dune-workspace</span></code> or <code class="docutils literal notranslate"><span class="pre">dune-project</span></code> file in the current directory
and parent directories.</p>
<p><code class="docutils literal notranslate"><span class="pre">dune</span></code> prints out the root when starting if it is not the current
directory:</p>
<div class="code bash highlight-default notranslate"><div class="highlight"><pre><span></span>$ dune runtest
Entering directory '/home/jdimino/code/dune'
...
</pre></div>
</div>
<p>More precisely, it will choose the outermost ancestor directory containing a
<code class="docutils literal notranslate"><span class="pre">dune-workspace</span></code> file as root. For instance if you are in
<code class="docutils literal notranslate"><span class="pre">/home/me/code/myproject/src</span></code>, then dune will look for all these files in
order:</p>
<ul class="simple">
<li><code class="docutils literal notranslate"><span class="pre">/dune-workspace</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">/home/dune-workspace</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">/home/me/dune-workspace</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">/home/me/code/dune-workspace</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">/home/me/code/myproject/dune-workspace</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">/home/me/code/myproject/src/dune-workspace</span></code></li>
</ul>
<p>The first entry to match in this list will determine the root. In
practice this means that if you nest your workspaces, dune will
always use the outermost one.</p>
<p>In addition to determining the root, <code class="docutils literal notranslate"><span class="pre">dune</span></code> will read this file as
to setup the configuration of the workspace unless the <code class="docutils literal notranslate"><span class="pre">--workspace</span></code>
command line option is used. See the section <a class="reference internal" href="#workspace-configuration">Workspace
configuration</a> for the syntax of this file.</p>
</div>
<div class="section" id="current-directory">
<h3>Current directory<a class="headerlink" href="#current-directory" title="Permalink to this headline">¶</a></h3>
<p>If the previous rule doesn’t apply, i.e. no ancestor directory has a
file named <code class="docutils literal notranslate"><span class="pre">dune-workspace</span></code>, then the current directory will be used
as root.</p>
</div>
<div class="section" id="forcing-the-root-for-scripts">
<h3>Forcing the root (for scripts)<a class="headerlink" href="#forcing-the-root-for-scripts" title="Permalink to this headline">¶</a></h3>
<p>You can pass the <code class="docutils literal notranslate"><span class="pre">--root</span></code> option to <code class="docutils literal notranslate"><span class="pre">dune</span></code> to select the root
explicitly. This option is intended for scripts to disable the automatic lookup.</p>
<p>Note that when using the <code class="docutils literal notranslate"><span class="pre">--root</span></code> option, targets given on the command line
will be interpreted relative to the given root, not relative to the current
directory as this is normally the case.</p>
</div>
</div>
<div class="section" id="interpretation-of-targets">
<h2>Interpretation of targets<a class="headerlink" href="#interpretation-of-targets" title="Permalink to this headline">¶</a></h2>
<p>This section describes how <code class="docutils literal notranslate"><span class="pre">dune</span></code> interprets the targets given on
the command line. When no targets are specified, <code class="docutils literal notranslate"><span class="pre">dune</span></code> builds the
<code class="docutils literal notranslate"><span class="pre">default</span></code> alias, see <a class="reference internal" href="#default-alias"><span class="std std-ref">Default alias</span></a> for more details.</p>
<div class="section" id="resolution">
<h3>Resolution<a class="headerlink" href="#resolution" title="Permalink to this headline">¶</a></h3>
<p>All targets that dune knows how to build live in the <code class="docutils literal notranslate"><span class="pre">_build</span></code>
directory. Although, some are sometimes copied to the source tree for
the need of external tools. These includes:</p>
<ul class="simple">
<li><code class="docutils literal notranslate"><span class="pre">.merlin</span></code> files</li>
<li><code class="docutils literal notranslate"><span class="pre"><package>.install</span></code> files</li>
</ul>
<p>As a result, if you want to ask <code class="docutils literal notranslate"><span class="pre">dune</span></code> to produce a particular <code class="docutils literal notranslate"><span class="pre">.exe</span></code>
file you would have to type:</p>
<div class="code bash highlight-default notranslate"><div class="highlight"><pre><span></span>$ dune build _build/default/bin/prog.exe
</pre></div>
</div>
<p>However, for convenience when a target on the command line doesn’t
start with <code class="docutils literal notranslate"><span class="pre">_build</span></code>, <code class="docutils literal notranslate"><span class="pre">dune</span></code> will expand it to the
corresponding target in all the build contexts where it knows how to
build it. When using <code class="docutils literal notranslate"><span class="pre">--verbose</span></code>, It prints out the actual set of
targets when starting:</p>
<div class="code bash highlight-default notranslate"><div class="highlight"><pre><span></span>$ dune build bin/prog.exe --verbose
...
Actual targets:
- _build/default/bin/prog.exe
- _build/4.03.0/bin/prog.exe
- _build/4.04.0/bin/prog.exe
</pre></div>
</div>
</div>
<div class="section" id="aliases">
<h3>Aliases<a class="headerlink" href="#aliases" title="Permalink to this headline">¶</a></h3>
<p>Targets starting with a <code class="docutils literal notranslate"><span class="pre">@</span></code> are interpreted as aliases. For instance
<code class="docutils literal notranslate"><span class="pre">@src/runtest</span></code> means the alias <code class="docutils literal notranslate"><span class="pre">runtest</span></code> in all descendant of
<code class="docutils literal notranslate"><span class="pre">src</span></code> in all build contexts where it is defined. If you want to
refer to a target starting with a <code class="docutils literal notranslate"><span class="pre">@</span></code>, simply write: <code class="docutils literal notranslate"><span class="pre">./@foo</span></code>.</p>
<p>To build and run the tests for a particular build context, use
<code class="docutils literal notranslate"><span class="pre">@_build/default/runtest</span></code> instead.</p>
<p>So for instance:</p>
<ul class="simple">
<li><code class="docutils literal notranslate"><span class="pre">dune</span> <span class="pre">build</span> <span class="pre">@_build/foo/runtest</span></code> will run the tests only for
the <code class="docutils literal notranslate"><span class="pre">foo</span></code> build context</li>
<li><code class="docutils literal notranslate"><span class="pre">dune</span> <span class="pre">build</span> <span class="pre">@runtest</span></code> will run the tests for all build contexts</li>
</ul>
<p>You can also build an alias non-recursively by using <code class="docutils literal notranslate"><span class="pre">@@</span></code> instead of
<code class="docutils literal notranslate"><span class="pre">@</span></code>. For instance to run tests only from the current directory:</p>
<div class="code highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">dune</span> <span class="n">build</span> <span class="o">@</span><span class="nd">@runtest</span>
</pre></div>
</div>
</div>
<div class="section" id="default-alias">
<span id="id2"></span><h3>Default alias<a class="headerlink" href="#default-alias" title="Permalink to this headline">¶</a></h3>
<p>When no targets are given to <code class="docutils literal notranslate"><span class="pre">dune</span> <span class="pre">build</span></code>, it builds the special
<code class="docutils literal notranslate"><span class="pre">default</span></code> alias. Effectively <code class="docutils literal notranslate"><span class="pre">dune</span> <span class="pre">build</span></code> is equivalent to:</p>
<div class="code highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">dune</span> <span class="n">build</span> <span class="o">@</span><span class="nd">@default</span>
</pre></div>
</div>
<p>When a directory doesn’t explicitly define what the <code class="docutils literal notranslate"><span class="pre">default</span></code> alias
means via an <a class="reference internal" href="dune-files.html#alias-stanza"><span class="std std-ref">alias</span></a> stanza, the following implicit
definition is assumed:</p>
<div class="code highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="n">alias</span>
<span class="p">(</span><span class="n">name</span> <span class="n">default</span><span class="p">)</span>
<span class="p">(</span><span class="n">deps</span> <span class="p">(</span><span class="n">alias_rec</span> <span class="n">install</span><span class="p">)))</span>
</pre></div>
</div>
<p>Which means that by default <code class="docutils literal notranslate"><span class="pre">dune</span> <span class="pre">build</span></code> will build everything that
is installable.</p>
</div>
</div>
<div class="section" id="finding-external-libraries">
<h2>Finding external libraries<a class="headerlink" href="#finding-external-libraries" title="Permalink to this headline">¶</a></h2>
<p>When a library is not available in the workspace, dune will look it
up in the installed world, and expect it to be already compiled.</p>
<p>It looks up external libraries using a specific list of search paths. A
list of search paths is specific to a given build context and is
determined as follow:</p>
<ol class="arabic simple">
<li>if the <code class="docutils literal notranslate"><span class="pre">ocamlfind</span></code> is present in the <code class="docutils literal notranslate"><span class="pre">PATH</span></code> of the context, use each line
in the output of <code class="docutils literal notranslate"><span class="pre">ocamlfind</span> <span class="pre">printconf</span> <span class="pre">path</span></code> as a search path</li>
<li>otherwise, if <code class="docutils literal notranslate"><span class="pre">opam</span></code> is present in the <code class="docutils literal notranslate"><span class="pre">PATH</span></code>, use the outout of <code class="docutils literal notranslate"><span class="pre">opam</span>
<span class="pre">config</span> <span class="pre">var</span> <span class="pre">lib</span></code></li>
<li>otherwise, take the directory where <code class="docutils literal notranslate"><span class="pre">ocamlc</span></code> was found, and append
<code class="docutils literal notranslate"><span class="pre">../lib</span></code> to it. For instance if <code class="docutils literal notranslate"><span class="pre">ocamlc</span></code> is found in <code class="docutils literal notranslate"><span class="pre">/usr/bin</span></code>, use
<code class="docutils literal notranslate"><span class="pre">/usr/lib</span></code></li>
</ol>
</div>
<div class="section" id="running-tests">
<span id="id3"></span><h2>Running tests<a class="headerlink" href="#running-tests" title="Permalink to this headline">¶</a></h2>
<p>There are two ways to run tests:</p>
<ul class="simple">
<li><code class="docutils literal notranslate"><span class="pre">dune</span> <span class="pre">build</span> <span class="pre">@runtest</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">dune</span> <span class="pre">runtest</span></code></li>
</ul>
<p>The two commands are equivalent. They will run all the tests defined in the
current directory and its children recursively. You can also run the tests in a
specific sub-directory and its children by using:</p>
<ul class="simple">
<li><code class="docutils literal notranslate"><span class="pre">dune</span> <span class="pre">build</span> <span class="pre">@foo/bar/runtest</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">dune</span> <span class="pre">runtest</span> <span class="pre">foo/bar</span></code></li>
</ul>
</div>
<div class="section" id="launching-the-toplevel-repl">
<h2>Launching the Toplevel (REPL)<a class="headerlink" href="#launching-the-toplevel-repl" title="Permalink to this headline">¶</a></h2>
<p>Dune supports launching a <a class="reference external" href="https://github.com/diml/utop">utop</a> instance
with locally defined libraries loaded.</p>
<div class="code bash highlight-default notranslate"><div class="highlight"><pre><span></span>$ dune utop <dir> -- <args>
</pre></div>
</div>
<p>Where <code class="docutils literal notranslate"><span class="pre"><dir></span></code> is a directory containing a <code class="docutils literal notranslate"><span class="pre">dune</span></code> file defining all the
libraries that will be loaded (using the <code class="docutils literal notranslate"><span class="pre">library</span></code> stanza). <code class="docutils literal notranslate"><span class="pre"><args></span></code> will be
passed as arguments to the utop command itself. For example, <code class="docutils literal notranslate"><span class="pre">dune</span> <span class="pre">utop</span> <span class="pre">lib</span> <span class="pre">--</span>
<span class="pre">-implicit-bindings</span></code> will start <code class="docutils literal notranslate"><span class="pre">utop</span></code> with the libraries defined in <code class="docutils literal notranslate"><span class="pre">lib</span></code>
and implicit bindings for toplevel expressions.</p>
<div class="section" id="requirements-limitations">
<h3>Requirements & Limitations<a class="headerlink" href="#requirements-limitations" title="Permalink to this headline">¶</a></h3>
<ul class="simple">
<li>utop version >= 2.0 is required for this to work.</li>
<li>This subcommand only supports loading libraries. Executables aren’t supported.</li>
<li>Libraries that are dependencies of utop itself cannot be loaded. For example
<a class="reference external" href="https://github.com/yoriyuki/Camomile">Camomile</a>.</li>
<li>Loading libraries that are defined in different directories into one utop
instance isn’t possible.</li>
</ul>
</div>
</div>
<div class="section" id="restricting-the-set-of-packages">
<h2>Restricting the set of packages<a class="headerlink" href="#restricting-the-set-of-packages" title="Permalink to this headline">¶</a></h2>
<p>You can restrict the set of packages from your workspace that dune can see with
the <code class="docutils literal notranslate"><span class="pre">--only-packages</span></code> option:</p>
<div class="code bash highlight-default notranslate"><div class="highlight"><pre><span></span>$ dune build --only-packages pkg1,pkg2,... @install
</pre></div>
</div>
<p>This option acts as if you went through all the dune files and
commented out the stanzas refering to a package that is not in the list
given to <code class="docutils literal notranslate"><span class="pre">dune</span></code>.</p>
</div>
<div class="section" id="invocation-from-opam">
<h2>Invocation from opam<a class="headerlink" href="#invocation-from-opam" title="Permalink to this headline">¶</a></h2>
<p>You should set the <code class="docutils literal notranslate"><span class="pre">build:</span></code> field of your <code class="docutils literal notranslate"><span class="pre"><package>.opam</span></code> file as
follows:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">build</span><span class="p">:</span> <span class="p">[[</span><span class="s2">"dune"</span> <span class="s2">"build"</span> <span class="s2">"-p"</span> <span class="n">name</span> <span class="s2">"-j"</span> <span class="n">jobs</span><span class="p">]]</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">-p</span> <span class="pre">pkg</span></code> is a shorthand for <code class="docutils literal notranslate"><span class="pre">--root</span> <span class="pre">.</span> <span class="pre">--only-packages</span> <span class="pre">pkg</span> <span class="pre">--profile</span>
<span class="pre">release</span> <span class="pre">--default-target</span> <span class="pre">@install</span></code>. <code class="docutils literal notranslate"><span class="pre">-p</span></code> is the short version of
<code class="docutils literal notranslate"><span class="pre">--for-release-of-packages</span></code>.</p>
<p>This has the following effects:</p>
<ul class="simple">
<li>it tells dune to build everything that is installable and to
ignore packages other than <code class="docutils literal notranslate"><span class="pre">name</span></code> defined in your project</li>
<li>it sets the root to prevent dune from looking it up</li>
<li>it sets the build profile to <code class="docutils literal notranslate"><span class="pre">release</span></code></li>
<li>it uses whatever concurrency option opam provides</li>
<li>it sets the default target to <code class="docutils literal notranslate"><span class="pre">@install</span></code> rather than <code class="docutils literal notranslate"><span class="pre">@@default</span></code></li>
</ul>
<p>Note that <code class="docutils literal notranslate"><span class="pre">name</span></code> and <code class="docutils literal notranslate"><span class="pre">jobs</span></code> are variables expanded by opam. <code class="docutils literal notranslate"><span class="pre">name</span></code> expands
to the package name and <code class="docutils literal notranslate"><span class="pre">jobs</span></code> to the number of jobs available to build the
package.</p>
</div>
<div class="section" id="tests">
<h2>Tests<a class="headerlink" href="#tests" title="Permalink to this headline">¶</a></h2>
<p>To setup the building and running of tests in opam, add this line to your
<code class="docutils literal notranslate"><span class="pre"><package>.opam</span></code> file:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">build</span><span class="o">-</span><span class="n">test</span><span class="p">:</span> <span class="p">[[</span><span class="s2">"dune"</span> <span class="s2">"runtest"</span> <span class="s2">"-p"</span> <span class="n">name</span> <span class="s2">"-j"</span> <span class="n">jobs</span><span class="p">]]</span>
</pre></div>
</div>
</div>
<div class="section" id="installation">
<h2>Installation<a class="headerlink" href="#installation" title="Permalink to this headline">¶</a></h2>
<p>Installing a package means copying the build artifacts from the build directory
to the installed word.</p>
<p>When installing via opam, you don’t need to worry about this step: dune
generates a <code class="docutils literal notranslate"><span class="pre"><package>.install</span></code> file that opam will automatically read to
handle installation.</p>
<p>However, when not using opam or doing local development, you can use dune to
install the artifacts by hands. To do that, use the <code class="docutils literal notranslate"><span class="pre">install</span></code> command:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ dune install [PACKAGE]...
</pre></div>
</div>
<p>without an argument, it will install all the packages available in the
workspace. With a specific list of packages, it will only install these
packages. If several build contexts are configured, the installation will be
performed for all of them.</p>
<p>Note that <code class="docutils literal notranslate"><span class="pre">dune</span> <span class="pre">install</span></code> is a thin wrapper around the <code class="docutils literal notranslate"><span class="pre">opam-installer</span></code> tool,
so you will need to install this tool in order to be able to use <code class="docutils literal notranslate"><span class="pre">dune</span>
<span class="pre">install</span></code>.</p>
<div class="section" id="destination">
<h3>Destination<a class="headerlink" href="#destination" title="Permalink to this headline">¶</a></h3>
<p>The place where the build artifacts are copied, usually referred as <strong>prefix</strong>,
is determined as follow for a given build context:</p>
<ol class="arabic simple">
<li>if an explicit <code class="docutils literal notranslate"><span class="pre">--prefix</span> <span class="pre"><path></span></code> argument is passed, use this path</li>
<li>if <code class="docutils literal notranslate"><span class="pre">opam</span></code> is present in the <code class="docutils literal notranslate"><span class="pre">PATH</span></code> and is configured, use the
output of <code class="docutils literal notranslate"><span class="pre">opam</span> <span class="pre">config</span> <span class="pre">var</span> <span class="pre">prefix</span></code></li>
<li>otherwise, take the parent of the directory where <code class="docutils literal notranslate"><span class="pre">ocamlc</span></code> was found.</li>
</ol>
<p>As an exception to this rule, library files might be copied to a different
location. The reason for this is that they often need to be copied to a
particular location for the various build system used in OCaml projects to find
them and this location might be different from <code class="docutils literal notranslate"><span class="pre"><prefix>/lib</span></code> on some systems.</p>
<p>Historically, the location where to store OCaml library files was configured
through <a class="reference external" href="http://projects.camlcity.org/projects/findlib.html">findlib</a> and the
<code class="docutils literal notranslate"><span class="pre">ocamlfind</span></code> command line tool was used to both install these files and locate
them. Many Linux distributions or other packaging systems are using this
mechanism to setup where OCaml library files should be copied.</p>
<p>As a result, if none of <code class="docutils literal notranslate"><span class="pre">--libdir</span></code> and <code class="docutils literal notranslate"><span class="pre">--prefix</span></code> is passed to <code class="docutils literal notranslate"><span class="pre">dune</span>
<span class="pre">install</span></code> and <code class="docutils literal notranslate"><span class="pre">ocamlfind</span></code> is present in the <code class="docutils literal notranslate"><span class="pre">PATH</span></code>, then library files will
be copied to the directory reported by <code class="docutils literal notranslate"><span class="pre">ocamlfind</span> <span class="pre">printconf</span> <span class="pre">destdir</span></code>. This
ensures that <code class="docutils literal notranslate"><span class="pre">dune</span> <span class="pre">install</span></code> can be used without opam. When using opam,
<code class="docutils literal notranslate"><span class="pre">ocamlfind</span></code> is configured to point to the opam directory, so this rule makes
no difference.</p>
<p>Note that <code class="docutils literal notranslate"><span class="pre">--prefix</span></code> and <code class="docutils literal notranslate"><span class="pre">--libdir</span></code> are only supported if a single build
context is in use.</p>
</div>
</div>
<div class="section" id="workspace-configuration">
<h2>Workspace configuration<a class="headerlink" href="#workspace-configuration" title="Permalink to this headline">¶</a></h2>
<p>By default, a workspace has only one build context named <code class="docutils literal notranslate"><span class="pre">default</span></code> which
correspond to the environment in which <code class="docutils literal notranslate"><span class="pre">dune</span></code> is run. You can define more
contexts by writing a <code class="docutils literal notranslate"><span class="pre">dune-workspace</span></code> file.</p>
<p>You can point <code class="docutils literal notranslate"><span class="pre">dune</span></code> to an explicit <code class="docutils literal notranslate"><span class="pre">dune-workspace</span></code> file with the
<code class="docutils literal notranslate"><span class="pre">--workspace</span></code> option. For instance it is good practice to write a
<code class="docutils literal notranslate"><span class="pre">dune-workspace.dev</span></code> in your project with all the version of OCaml your
projects support. This way developers can tests that the code builds with all
version of OCaml by simply running:</p>
<div class="code bash highlight-default notranslate"><div class="highlight"><pre><span></span>$ dune build --workspace dune-workspace.dev @install @runtest
</pre></div>
</div>
<div class="section" id="id4">
<h3>dune-workspace<a class="headerlink" href="#id4" title="Permalink to this headline">¶</a></h3>
<p>The <code class="docutils literal notranslate"><span class="pre">dune-workspace</span></code> file uses the S-expression syntax. This is what
a typical <code class="docutils literal notranslate"><span class="pre">dune-workspace</span></code> file 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">1.0</span><span class="p">)</span>
<span class="p">(</span><span class="n">context</span> <span class="p">(</span><span class="n">opam</span> <span class="p">(</span><span class="n">switch</span> <span class="mf">4.02</span><span class="o">.</span><span class="mi">3</span><span class="p">)))</span>
<span class="p">(</span><span class="n">context</span> <span class="p">(</span><span class="n">opam</span> <span class="p">(</span><span class="n">switch</span> <span class="mf">4.03</span><span class="o">.</span><span class="mi">0</span><span class="p">)))</span>
<span class="p">(</span><span class="n">context</span> <span class="p">(</span><span class="n">opam</span> <span class="p">(</span><span class="n">switch</span> <span class="mf">4.04</span><span class="o">.</span><span class="mi">0</span><span class="p">)))</span>
</pre></div>
</div>
<p>The rest of this section describe the stanzas available.</p>
<p>Note that an empty <code class="docutils literal notranslate"><span class="pre">dune-workspace</span></code> file is interpreted the same as one
containing exactly:</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">1.0</span><span class="p">)</span>
<span class="p">(</span><span class="n">context</span> <span class="n">default</span><span class="p">)</span>
</pre></div>
</div>
<p>This allows you to use an empty <code class="docutils literal notranslate"><span class="pre">dune-workspace</span></code> file to mark the root of your
project.</p>
<div class="section" id="profile">
<h4>profile<a class="headerlink" href="#profile" title="Permalink to this headline">¶</a></h4>
<p>The build profile can be selected in the <code class="docutils literal notranslate"><span class="pre">dune-workspace</span></code> file by write a
<code class="docutils literal notranslate"><span class="pre">(profile</span> <span class="pre">...)</span></code> stanza. For instance:</p>
<div class="code scheme highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="n">profile</span> <span class="n">release</span><span class="p">)</span>
</pre></div>
</div>
<p>Note that the command line option <code class="docutils literal notranslate"><span class="pre">--profile</span></code> has precedence over this stanza.</p>
</div>
<div class="section" id="context">
<h4>context<a class="headerlink" href="#context" title="Permalink to this headline">¶</a></h4>
<p>The <code class="docutils literal notranslate"><span class="pre">(context</span> <span class="pre">...)</span></code> stanza declares a build context. The argument
can be either <code class="docutils literal notranslate"><span class="pre">default</span></code> or <code class="docutils literal notranslate"><span class="pre">(default)</span></code> for the default build
context or can be the description of an opam switch, as follows:</p>
<div class="code scheme highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="n">context</span> <span class="p">(</span><span class="n">opam</span> <span class="p">(</span><span class="n">switch</span> <span class="o"><</span><span class="n">opam</span><span class="o">-</span><span class="n">switch</span><span class="o">-</span><span class="n">name</span><span class="o">></span><span class="p">)</span>
<span class="o"><</span><span class="n">optional</span><span class="o">-</span><span class="n">fields</span><span class="o">></span><span class="p">))</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre"><optional-fields></span></code> are:</p>
<ul class="simple">
<li><code class="docutils literal notranslate"><span class="pre">(name</span> <span class="pre"><name>)</span></code> is the name of the subdirectory of <code class="docutils literal notranslate"><span class="pre">_build</span></code>
where the artifacts for this build context will be stored</li>
<li><code class="docutils literal notranslate"><span class="pre">(root</span> <span class="pre"><opam-root>)</span></code> is the opam root. By default it will take
the opam root defined by the environment in which <code class="docutils literal notranslate"><span class="pre">dune</span></code> is
run which is usually <code class="docutils literal notranslate"><span class="pre">~/.opam</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">(merlin)</span></code> instructs dune to use this build context for
merlin</li>
<li><code class="docutils literal notranslate"><span class="pre">(profile</span> <span class="pre"><profile>)</span></code> to set a different profile for a build
context. This has precedence over the command line option
<code class="docutils literal notranslate"><span class="pre">--profile</span></code></li>
</ul>
<p>Both <code class="docutils literal notranslate"><span class="pre">(default</span> <span class="pre">...)</span></code> and <code class="docutils literal notranslate"><span class="pre">(opam</span> <span class="pre">...)</span></code> accept a <code class="docutils literal notranslate"><span class="pre">targets</span></code> field in order to
setup cross compilation. See <a class="reference internal" href="advanced-topics.html#advanced-cross-compilation"><span class="std std-ref">Cross Compilation</span></a> for more
information.</p>
<p>Merlin reads compilation artifacts and it can only read the compilation
artifacts of a single context. Usually, you should use the artifacts from the
<code class="docutils literal notranslate"><span class="pre">default</span></code> context, and if you have the <code class="docutils literal notranslate"><span class="pre">(context</span> <span class="pre">default)</span></code> stanza in your
<code class="docutils literal notranslate"><span class="pre">dune-workspace</span></code> file, that is the one dune will use.</p>
<p>For rare cases where this is not what you want, you can force dune to use a
different build contexts for merlin by adding the field <code class="docutils literal notranslate"><span class="pre">(merlin)</span></code> to this
context.</p>
</div>
</div>
</div>
<div class="section" id="building-javascript-with-js-of-ocaml">
<h2>Building JavaScript with js_of_ocaml<a class="headerlink" href="#building-javascript-with-js-of-ocaml" title="Permalink to this headline">¶</a></h2>
<p>Dune knows how to generate a JavaScript version of an executable
(<code class="docutils literal notranslate"><span class="pre"><name>.bc.js</span></code>) using the js_of_ocaml compiler (the <code class="docutils literal notranslate"><span class="pre">js_of_ocaml-compiler</span></code>
opam package must be installed).</p>
<p>It supports two modes of compilation:</p>
<ul class="simple">
<li>Direct compilation of a bytecode program to JavaScript. This mode allows
js_of_ocaml to perform whole program deadcode elimination and whole program
inlining.</li>
<li>Separate compilation, where compilation units are compiled to JavaScript
separately and then linked together. This mode is useful during development as
it builds more quickly.</li>
</ul>
<p>The separate compilation mode will be selected when the build profile is
<code class="docutils literal notranslate"><span class="pre">dev</span></code>, which is the default. There is currently no other way to control this
behaviour.</p>
<p>See the section about <a class="reference internal" href="dune-files.html#dune-jsoo"><span class="std std-ref">js_of_ocaml</span></a> for passing custom flags to the
js_of_ocaml compiler</p>
</div>
<div class="section" id="distributing-projects">
<h2>Distributing Projects<a class="headerlink" href="#distributing-projects" title="Permalink to this headline">¶</a></h2>
<p>Dune provides support for building and installing your project. However it
doesn’t provide helpers for distributing it. It is recommended to use
<a class="reference external" href="https://github.com/samoht/dune-release">dune-release</a> for this purpose.</p>
<p>The common defaults are that your projects include the following files:</p>
<ul class="simple">
<li><code class="docutils literal notranslate"><span class="pre">README.md</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">CHANGES.md</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">LICENSE.md</span></code></li>
</ul>
<p>And that if your project contains several packages, then all the package names
must be prefixed by the shortest one.</p>
</div>
<div class="section" id="watermarking">
<h2>Watermarking<a class="headerlink" href="#watermarking" title="Permalink to this headline">¶</a></h2>
<p>One of the feature dune-release provides is watermarking; it replaces
various strings of the form <code class="docutils literal notranslate"><span class="pre">%%ID%%</span></code> in all files of your project
before creating a release tarball or when the package is pinned by the
user using opam.</p>
<p>This is especially interesting for the <code class="docutils literal notranslate"><span class="pre">VERSION</span></code> watermark, which gets
replaced by the version obtained from the vcs. For instance if you are using
git, dune-release invokes this command to find out the version:</p>
<div class="code bash highlight-default notranslate"><div class="highlight"><pre><span></span>$ git describe --always --dirty
1.0+beta9-79-g29e9b37
</pre></div>
</div>
<p>Projects using dune usually only need dune-release for creating and
publishing releases. However they might still want to substitute the
watermarks when the package is pinned by the user. To help with this,
dune provides the <code class="docutils literal notranslate"><span class="pre">subst</span></code> sub-command.</p>
</div>
<div class="section" id="dune-subst">
<h2>dune subst<a class="headerlink" href="#dune-subst" title="Permalink to this headline">¶</a></h2>
<p><code class="docutils literal notranslate"><span class="pre">dune</span> <span class="pre">subst</span></code> performs the same substitution <code class="docutils literal notranslate"><span class="pre">dune-release</span></code> does
with the default configuration. i.e. calling <code class="docutils literal notranslate"><span class="pre">dune</span> <span class="pre">subst</span></code> at the
root of your project will rewrite in place all the files in your
project.</p>
<p>More precisely, it replaces all the following watermarks in source files:</p>
<ul class="simple">
<li><code class="docutils literal notranslate"><span class="pre">NAME</span></code>, the name of the project</li>
<li><code class="docutils literal notranslate"><span class="pre">VERSION</span></code>, output of <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">describe</span> <span class="pre">--always</span> <span class="pre">--dirty</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">VERSION_NUM</span></code>, same as <code class="docutils literal notranslate"><span class="pre">VERSION</span></code> but with a potential leading
<code class="docutils literal notranslate"><span class="pre">v</span></code> or <code class="docutils literal notranslate"><span class="pre">V</span></code> dropped</li>
<li><code class="docutils literal notranslate"><span class="pre">VCS_COMMIT_ID</span></code>, commit hash from the vcs</li>
<li><code class="docutils literal notranslate"><span class="pre">PKG_MAINTAINER</span></code>, contents of the <code class="docutils literal notranslate"><span class="pre">maintainer</span></code> field from the
opam file</li>
<li><code class="docutils literal notranslate"><span class="pre">PKG_AUTHORS</span></code>, contents of the <code class="docutils literal notranslate"><span class="pre">authors</span></code> field from the opam file</li>
<li><code class="docutils literal notranslate"><span class="pre">PKG_HOMEPAGE</span></code>, contents of the <code class="docutils literal notranslate"><span class="pre">homepage</span></code> field from the opam file</li>
<li><code class="docutils literal notranslate"><span class="pre">PKG_ISSUES</span></code>, contents of the <code class="docutils literal notranslate"><span class="pre">issues</span></code> field from the opam file</li>
<li><code class="docutils literal notranslate"><span class="pre">PKG_DOC</span></code>, contents of the <code class="docutils literal notranslate"><span class="pre">doc</span></code> field from the opam file</li>
<li><code class="docutils literal notranslate"><span class="pre">PKG_LICENSE</span></code>, contents of the <code class="docutils literal notranslate"><span class="pre">license</span></code> field from the opam file</li>
<li><code class="docutils literal notranslate"><span class="pre">PKG_REPO</span></code>, contents of the <code class="docutils literal notranslate"><span class="pre">repo</span></code> field from the opam file</li>
</ul>
<p>The name of the project is obtained by reading the <code class="docutils literal notranslate"><span class="pre">dune-project</span></code>
file in the directory where <code class="docutils literal notranslate"><span class="pre">dune</span> <span class="pre">subst</span></code> is called. The
<code class="docutils literal notranslate"><span class="pre">dune-project</span></code> file must exist and contain a valid <code class="docutils literal notranslate"><span class="pre">(name</span> <span class="pre">...)</span></code>
field.</p>
<p>Note that <code class="docutils literal notranslate"><span class="pre">dune</span> <span class="pre">subst</span></code> is meant to be called from the opam file and
in particular behaves a bit different to other <code class="docutils literal notranslate"><span class="pre">dune</span></code> commands. In
particular it doesn’t try to detect the root of the workspace and must
be called from the root of the project.</p>
</div>
<div class="section" id="custom-build-directory">
<h2>Custom Build Directory<a class="headerlink" href="#custom-build-directory" title="Permalink to this headline">¶</a></h2>
<p>By default dune places all build artifacts in the <code class="docutils literal notranslate"><span class="pre">_build</span></code> directory relative
to the user’s workspace. However, one can customize this directory by using the
<code class="docutils literal notranslate"><span class="pre">--build-dir</span></code> flag or the <code class="docutils literal notranslate"><span class="pre">DUNE_BUILD_DIR</span></code> environment variable.</p>
<div class="code bash highlight-default notranslate"><div class="highlight"><pre><span></span>$ dune build --build-dir _build-foo
# this is equivalent to:
$ DUNE_BUILD_DIR=_build-foo dune build
# Absolute paths are also allowed
$ dune build --build-dir /tmp/build foo.exe
</pre></div>
</div>
</div>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="advanced-topics.html" class="btn btn-neutral float-right" title="Advanced topics" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="documentation.html" class="btn btn-neutral" title="Generating Documentation" 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
>
95
