mte/unikernel/duniverse/dune_/doc/quick-start.rst

**********
Quickstart
**********

.. TODO(diataxis)

   Split this into:

   - :doc:`tutorials/from-zero-to-opam`
   - :doc:`tutorials/developing-with-dune`
   - :doc:`howto/changing-flags`
   - an how-to guide about ``cppo``
   - an how-to guide about staged programming / generators
   - an how-to guide about testing

This document gives simple usage examples of Dune. You can also look at
`examples <https://github.com/ocaml/dune/tree/master/example>`__ for complete
examples of projects using Dune with `CRAM stanzas <https://ocaml.org/p/craml/1.0.0>`__.

To try these examples, you will need to have Dune installed. See
:doc:`howto/install-dune`.

Initializing Projects
=====================

The following subsections illustrate basic usage of the ``dune init proj``
subcommand. For more documentation, see :ref:`initializing_components` and the
inline help available from ``dune init --help``.

.. _initializing-an-executable:

Initializing an Executable
--------------------------

To initialize a project that will build an executable program, run the following
(replacing ``project_name`` with the name of your project):

.. code:: console

  $ dune init proj project_name

This creates a project directory that includes the following contents:

.. code::

    project_name/
    ├── dune-project
    ├── test
    │   ├── dune
    │   └── test_project_name.ml
    ├── lib
    │   └── dune
    ├── bin
    │   ├── dune
    │   └── main.ml
    └── project_name.opam

Now, enter your project's directory:

.. code:: console

  $ cd project_name

Then, you can build your project with:

.. code:: console

  $ dune build

You can run your tests with:

.. code:: console

  $ dune test

You can run your program with:

.. code:: console

  $ dune exec project_name

This simple project will print "Hello World" in your shell.

The following itemization of the generated content isn't necessary to review at
this point. But whenever you are ready, it will provide jump-off points from
which you can dive deeper into Dune's capabilities:

* The ``dune-project`` file specifies metadata about the project, including its
  name, packaging data (including dependencies), and information about the
  authors and maintainers. Open this in your editor to fill in the
  placeholder values. See :doc:`/reference/dune-project/index` for
  details.
* The ``test`` directory contains a skeleton for your project's tests. Add to
  the tests by editing ``test/test_project_name.ml``. See :ref:`writing-tests` for
  details on testing.
* The ``lib`` directory will hold the library you write to provide your executable's core
  functionality. Add modules to your library by creating new
  ``.ml`` files in this directory. See :doc:`/reference/dune/library` for
  details on specifying libraries manually.
* The ``bin`` directory holds a skeleton for the executable program. Within the
  modules in this directory, you can access the modules in your ``lib`` under
  the namespace ``project_name.Mod``, where ``project_name`` is replaced with
  the name of your project and ``Mod`` corresponds to the name of the file in
  the ``lib`` directory. You can run the executable with ``dune exec
  project_name``.  See :ref:`hello-world-program` for an example of specifying
  an executable manually and :doc:`/reference/dune/executable` for
  details.
* The ``project_name.opam`` file will be freshly generated from the
  ``dune-project`` file whenever you build your project. You shouldn't need to
  worry about this, but you can see :doc:`explanation/opam-integration` for
  details.
* The ``dune`` files in each directory specify the component to be built with
  the files in that directory. For details on ``dune`` files, see :doc:`/reference/dune/index`.

Initializing a Library
----------------------

To initialize a project for an OCaml library, run the following (replacing
``project_name`` with the name of your project):

.. code:: console

  $ dune init proj --kind=lib project_name

This creates a project directory that includes the following contents:

.. code::

    project_name/
    ├── dune-project
    ├── lib
    │   └── dune
    ├── test
    │   ├── dune
    │   └── test_project_name.ml
    └── project_name.opam

Now, enter your project's directory:

.. code:: console

  $ cd project_name

Then, you can build your project with:

.. code:: console

  $ dune build

You can run your tests with:

.. code:: console

  $ dune test

All of the subcomponents generated are the same as those described in
:ref:`initializing-an-executable`, with the following exceptions:

* There is no ``bin`` directory generated.
* The ``dune`` file in the ``lib`` directory specifies that the library should
  be *public*. See :doc:`/reference/dune/library` for details.

.. _hello-world-program:

Building a Hello World Program From Scratch
===========================================

Create a new directory within a Dune project (:ref:`initializing-an-executable`).
Since OCaml is a compiled language, first create a ``dune`` file in Nano, Vim, 
or your preferred text editor. Declare the ``hello_world`` executable by including the following stanza 
(shown below). Name this initial file ``dune`` and save it. 

.. code:: dune

    (executable
     (name hello_world))

Create a second file containing the following code and name it ``hello_world.ml`` (including 
the .ml extension). It will implement the executable stanza in the ``dune`` file when built. 

.. code:: ocaml

    print_endline "Hello, world!"

Next, build your new program in a shell using this command:

.. code:: console

   $ dune build hello_world.exe

This will create a directory called ``_build`` and build the 
program: ``_build/default/hello_world.exe``. Note that
native code executables will have the ``.exe`` extension on all platforms
(including non-Windows systems). 

Finally, run it with the following command to see that it worked. In 
fact, the executable can both be built and run in a single
step:

.. code:: console

   $ dune exec -- ./hello_world.exe

Voila! This should print "Hello, world!" in the command line.

Building a Hello World Program Using Lwt
========================================

Lwt is a concurrent library in OCaml. 

In a directory of your choice, write this ``dune`` file:

.. code:: dune

    (executable
     (name hello_world)
     (libraries lwt.unix))

This ``hello_world.ml`` file:

.. code:: ocaml

    Lwt_main.run (Lwt_io.printf "Hello, world!\n")

And build it with:

.. code:: console

  $ dune build hello_world.exe

The executable will be built as ``_build/default/hello_world.exe``

Building a Hello World Program Using Core and Jane Street PPXs
==============================================================

Write this ``dune`` file:

.. code:: dune

    (executable
     (name hello_world)
     (libraries core)
     (preprocess (pps ppx_jane)))

This ``hello_world.ml`` file:

.. code:: ocaml

    open Core

    let () =
      Sexp.to_string_hum [%sexp ([3;4;5] : int list)]
      |> print_endline

And build it with:

.. code:: console

  $ dune build hello_world.exe

The executable will be built as ``_build/default/hello_world.exe``


Defining a Library Using Lwt and ``ocaml-re``
=============================================

Write this ``dune`` file:

.. code:: dune

    (library
     (name        mylib)
     (public_name mylib)
     (libraries re lwt))

The library will be composed of all the modules in the same directory.
Outside of the library, module ``Foo`` will be accessible as
``Mylib.Foo``, unless you write an explicit ``mylib.ml`` file.

You can then use this library in any other directory by adding ``mylib``
to the ``(libraries ...)`` field.

Building a Hello World Program in Bytecode
============================================

In a directory of your choice, write this ``dune`` file:

.. code:: dune

    ;; This declares the hello_world executable implemented by hello_world.ml
    ;; to be build as native (.exe) or bytecode (.bc) version.
    (executable
     (name hello_world)
     (modes byte exe))

This ``hello_world.ml`` file:

.. code:: ocaml

    print_endline "Hello, world!"

And build it with:

.. code:: console

  $ dune build hello_world.bc

The executable will be built as ``_build/default/hello_world.bc``.
The executable can be built and run in a single
step with ``dune exec ./hello_world.bc``. This bytecode version allows the usage of 
``ocamldebug``.

Setting the OCaml Compilation Flags Globally
============================================

Write this ``dune`` file at the root of your project:

.. code:: dune

    (env
     (dev
      (flags (:standard -w +42)))
     (release
      (ocamlopt_flags (:standard -O3))))

`dev` and `release` correspond to build profiles. The build profile
can be selected from the command line with ``--profile foo`` or from a
`dune-workspace` file by writing:

.. code:: dune

    (profile foo)

Using Cppo
==========

Add this field to your ``library`` or ``executable`` stanzas:

.. code:: dune

    (preprocess (action (run %{bin:cppo} -V OCAML:%{ocaml_version} %{input-file})))

Additionally, if you want to include a ``config.h`` file, you need to
declare the dependency to this file via:

.. code:: dune

    (preprocessor_deps config.h)

Using the ``.cppo.ml`` Style Like the ``ocamlbuild`` Plugin
-----------------------------------------------------------

Write this in your ``dune`` file:

.. code:: dune

    (rule
     (targets foo.ml)
     (deps    (:first-dep foo.cppo.ml) <other files that foo.ml includes>)
     (action  (run %{bin:cppo} %{first-dep} -o %{targets})))

Defining a Library with C Stubs
===============================

Assuming you have a file called ``mystubs.c``, that you need to pass
``-I/blah/include`` to compile it and ``-lblah`` at link time, write
this ``dune`` file:

.. code:: dune

    (library
     (name            mylib)
     (public_name     mylib)
     (libraries       re lwt)
     (foreign_stubs
      (language c)
      (names mystubs)
      (flags -I/blah/include))
     (c_library_flags (-lblah)))

Defining a Library with C Stubs using ``pkg-config``
====================================================

Same context as before, but using ``pkg-config`` to query the
compilation and link flags. Write this ``dune`` file:

.. code:: dune

    (library
     (name            mylib)
     (public_name     mylib)
     (libraries       re lwt)
     (foreign_stubs
      (language c)
      (names mystubs)
      (flags (:include c_flags.sexp)))
     (c_library_flags (:include c_library_flags.sexp)))

    (rule
     (targets c_flags.sexp c_library_flags.sexp)
     (action  (run ./config/discover.exe)))

Then create a ``config`` subdirectory and write this ``dune`` file:

.. code:: dune

    (executable
     (name discover)
     (libraries dune-configurator))

as well as this ``discover.ml`` file:

.. code:: ocaml

    module C = Configurator.V1

    let () =
    C.main ~name:"foo" (fun c ->
    let default : C.Pkg_config.package_conf =
      { libs   = ["-lgst-editing-services-1.0"]
      ; cflags = []
      }
    in
    let conf =
      match C.Pkg_config.get c with
      | None -> default
      | Some pc ->
         match (C.Pkg_config.query pc ~package:"gst-editing-services-1.0") with
         | None -> default
         | Some deps -> deps
    in


    C.Flags.write_sexp "c_flags.sexp"         conf.cflags;
    C.Flags.write_sexp "c_library_flags.sexp" conf.libs)


Using a Custom Code Generator
=============================

To generate a file ``foo.ml`` using a program from another directory:

.. code:: dune

    (rule
     (targets foo.ml)
     (deps    (:gen ../generator/gen.exe))
     (action  (run %{gen} -o %{targets})))

Defining Tests
==============

Write this in your ``dune`` file:

.. code:: dune

    (test (name my_test_program))

And run the tests with:

.. code:: console

  $ dune runtest

It will run the test program (the main module is ``my_test_program.ml``) and
error if it exits with a nonzero code.

In addition, if a ``my_test_program.expected`` file exists, it will be compared
to the standard output of the test program and the differences will be
displayed. It is possible to replace the ``.expected`` file with the last output
using:

.. code:: console

  $ dune promote

Building a Custom Toplevel
==========================

A toplevel is simply an executable calling ``Topmain.main ()`` and linked with
the compiler libraries and ``-linkall``. Moreover, currently toplevels can only
be built in bytecode.

As a result, write this in your ``dune`` file:

.. code:: dune

    (executable
     (name       mytoplevel)
     (libraries  compiler-libs.toplevel mylib)
     (link_flags (-linkall))
     (modes      byte))

And write this in ``mytoplevel.ml``:

.. code:: ocaml

    let () = exit (Topmain.main ())