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

@@ -0,0 +1,498 @@
+**********
+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 ())