Merge pull request #951 from rgrinberg/port-quickstart-dune

Port quick start to dune syntax

doc/quick-start.rst

@@ -3,21 +3,19 @@ Quickstart
 **********
 
 This document gives simple usage examples of dune. You can also look at
-`examples <https://github.com/ocaml/dune/tree/master/example>`__ for
+`examples <https://github.com/ocaml/dune/tree/master/example>`__ for complete
-complete examples of projects using dune.
+examples of projects using dune.
 
 Building a hello world program
 ==============================
 
-In a directory of your choice, write this ``jbuild`` file:
+In a directory of your choice, write this ``dune`` file:
 
 .. code:: scheme
 
-    (jbuild_version 1)
-
     ;; This declares the hello_world executable implemented by hello_world.ml
     (executable
-     ((name hello_world)))
+     (name hello_world))
 
 This ``hello_world.ml`` file:
 
@@ -33,20 +31,19 @@ And build it with:
 
 The executable will be built as ``_build/default/hello_world.exe``. Note that
 native code executables will have the ``.exe`` extension on all platforms
-(including non-Windows systems).
+(including non-Windows systems). The executable can ran with: ``$ dune exec
+./hello_world.exe``
 
 Building a hello world program using Lwt
 ========================================
 
-In a directory of your choice, write this ``jbuild`` file:
+In a directory of your choice, write this ``dune`` file:
 
 .. code:: scheme
 
-    (jbuild_version 1)
-
     (executable
-     ((name hello_world)
+     (name hello_world)
-      (libraries (lwt.unix))))
+     (libraries lwt.unix))
 
 This ``hello_world.ml`` file:
 
@@ -65,17 +62,14 @@ The executable will be built as ``_build/default/hello_world.exe``
 Building a hello world program using Core and Jane Street PPXs
 ==============================================================
 
-Write this jbuild:
+Write this ``dune`` file:
 
 .. code:: scheme
 
-    (jbuild_version 1)
-
     (executable
-     ((name hello_world)
+     (name hello_world)
-      (libraries (core))
+     (libraries core)
-      (preprocess (pps (ppx_jane)))
+     (preprocess (pps ppx_jane)))
-     ))
 
 This ``hello_world.ml`` file:
 
@@ -98,16 +92,14 @@ The executable will be built as ``_build/default/hello_world.exe``
 Defining a library using Lwt and ocaml-re
 =========================================
 
-Write this jbuild:
+Write this ``dune`` file:
 
 .. code:: scheme
 
-    (jbuild_version 1)
-
     (library
-     ((name        mylib)
+     (name        mylib)
-      (public_name mylib)
+     (public_name mylib)
-      (libraries (re lwt))))
+     (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
@@ -119,7 +111,7 @@ to the ``(libraries ...)`` field.
 Setting the OCaml compilation flags globally
 ============================================
 
-Write this jbuild at the root of your project:
+Write this ``dune`` file at the root of your project:
 
 .. code:: scheme
 
@@ -144,79 +136,72 @@ Add this field to your ``library`` or ``executable`` stanzas:
 
 .. code:: scheme
 
-    (preprocess (action (run ${bin:cppo} -V OCAML:${ocaml_version} ${<})))
+    (preprocess (action (run %{bin:cppo} -V OCAML:%{ocaml_version} %{<})))
 
 Additionally, if you are include a ``config.h`` file, you need to
 declare the dependency to this file via:
 
 .. code:: scheme
 
-    (preprocessor_deps (config.h))
+    (preprocessor_deps config.h)
 
 Using the .cppo.ml style like the ocamlbuild plugin
 ---------------------------------------------------
 
-Write this in your jbuild:
+Write this in your ``dune`` file:
 
 .. code:: scheme
 
     (rule
-     ((targets (foo.ml))
+     (targets foo.ml)
-      (deps    (foo.cppo.ml <other files that foo.ml includes>))
+     (deps    foo.cppo.ml <other files that foo.ml includes>)
-      (action  (run ${bin:cppo} ${<} -o ${@}))))
+     (action  (run %{bin:cppo} %{<} -o %{@})))
 
 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 jbuild:
+this ``dune`` file:
 
 .. code:: scheme
 
-    (jbuild_version 1)
-
     (library
-     ((name            mylib)
+     (name            mylib)
-      (public_name     mylib)
+     (public_name     mylib)
-      (libraries       (re lwt))
+     (libraries       re lwt)
-      (c_names         (mystubs))
+     (c_names         mystubs)
-      (c_flags         (-I/blah/include))
+     (c_flags         (-I/blah/include))
-      (c_library_flags (-lblah))))
+     (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 jbuild:
+compilation and link flags. Write this ``dune`` file:
 
 .. code:: scheme
 
-    (jbuild_version 1)
-
     (library
-     ((name            mylib)
+     (name            mylib)
-      (public_name     mylib)
+     (public_name     mylib)
-      (libraries       (re lwt))
+     (libraries       re lwt)
-      (c_names         (mystubs))
+     (c_names         mystubs)
-      (c_flags         (:include c_flags.sexp))
+     (c_flags         (:include c_flags.sexp))
-      (c_library_flags (:include c_library_flags.sexp))))
+     (c_library_flags (:include c_library_flags.sexp)))
 
     (rule
-     ((targets (c_flags.sexp
+     (targets c_flags.sexp c_library_flags.sexp)
-                c_library_flags.sexp))
+     (deps    config/discover.exe)
-      (deps    (config/discover.exe))
+     (action  (run %{<} -ocamlc %{OCAMLC})))
-      (action  (run ${<} -ocamlc ${OCAMLC}))))
 
-Then create a ``config`` subdirectory and write this ``jbuild``:
+Then create a ``config`` subdirectory and write this ``dune`` file:
 
 .. code:: scheme
 
-    (jbuild_version 1)
-
     (executable
-     ((name discover)
+     (name discover)
-      (libraries (base stdio configurator))))
+     (libraries base stdio configurator))
 
 as well as this ``discover.ml`` file:
 
@@ -253,26 +238,22 @@ To generate a file ``foo.ml`` using a program from another directory:
 
 .. code:: scheme
 
-    (jbuild_version 1)
-
     (rule
-     ((targets (foo.ml))
+     (targets foo.ml)
-      (deps    (../generator/gen.exe))
+     (deps    ../generator/gen.exe)
-      (action  (run ${<} -o ${@}))))
+     (action  (run %{<} -o %{@})))
 
 Defining tests
 ==============
 
-Write this in your ``jbuild`` file:
+Write this in your ``dune`` file:
 
 .. code:: scheme
 
-    (jbuild_version 1)
-
     (alias
-     ((name    runtest)
+     (name    runtest)
-      (deps    (my-test-program.exe))
+     (deps    my-test-program.exe)
-      (action  (run ${<}))))
+     (action  (run %{<})))
 
 And run the tests with:
 
@@ -283,21 +264,19 @@ And run the tests with:
 Building a custom toplevel
 ==========================
 
-A toplevel is simply an executable calling ``Topmain.main ()`` and
+A toplevel is simply an executable calling ``Topmain.main ()`` and linked with
-linked with the compiler libraries and ``-linkall``. Moreover,
+the compiler libraries and ``-linkall``. Moreover, currently toplevels can only
-currently toplevels can only be built in bytecode.
+be built in bytecode.
 
-As a result, write this in your ``jbuild`` file:
+As a result, write this in your ``dune`` file:
 
 .. code:: scheme
 
-    (jbuild_version 1)
-
     (executable
-     ((name       mytoplevel)
+     (name       mytoplevel)
-      (libraries  (compiler-libs.toplevel mylib))
+     (libraries  compiler-libs.toplevel mylib)
-      (link_flags (-linkall))
+     (link_flags (-linkall))
-      (modes      (byte))))
+     (modes      byte))
 
 And write this in ``mytoplevel.ml``