From 11890d2b8db0d3cc849a0aaa2d2001abad56940f Mon Sep 17 00:00:00 2001 From: Rudi Grinberg Date: Wed, 4 Jul 2018 18:47:09 +0700 Subject: [PATCH] Port quick start to dune syntax Signed-off-by: Rudi Grinberg --- doc/quick-start.rst | 139 +++++++++++++++++++------------------------- 1 file changed, 59 insertions(+), 80 deletions(-) diff --git a/doc/quick-start.rst b/doc/quick-start.rst index fa53ba14..5e8a30a7 100644 --- a/doc/quick-start.rst +++ b/doc/quick-start.rst @@ -3,21 +3,19 @@ Quickstart ********** This document gives simple usage examples of dune. You can also look at -`examples `__ for -complete examples of projects using dune. +`examples `__ for complete +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) - (libraries (lwt.unix)))) + (name hello_world) + (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) - (libraries (core)) - (preprocess (pps (ppx_jane))) - )) + (name hello_world) + (libraries core) + (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) - (public_name mylib) - (libraries (re lwt)))) + (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 @@ -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)) - (deps (foo.cppo.ml )) - (action (run ${bin:cppo} ${<} -o ${@})))) + (targets foo.ml) + (deps foo.cppo.ml ) + (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) - (public_name mylib) - (libraries (re lwt)) - (c_names (mystubs)) - (c_flags (-I/blah/include)) - (c_library_flags (-lblah)))) + (name mylib) + (public_name mylib) + (libraries re lwt) + (c_names mystubs) + (c_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 jbuild: +compilation and link flags. Write this ``dune`` file: .. code:: scheme - (jbuild_version 1) - (library - ((name mylib) - (public_name mylib) - (libraries (re lwt)) - (c_names (mystubs)) - (c_flags (:include c_flags.sexp)) - (c_library_flags (:include c_library_flags.sexp)))) + (name mylib) + (public_name mylib) + (libraries re lwt) + (c_names mystubs) + (c_flags (:include c_flags.sexp)) + (c_library_flags (:include c_library_flags.sexp))) (rule - ((targets (c_flags.sexp - c_library_flags.sexp)) - (deps (config/discover.exe)) - (action (run ${<} -ocamlc ${OCAMLC})))) + (targets c_flags.sexp c_library_flags.sexp) + (deps config/discover.exe) + (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) - (libraries (base stdio configurator)))) + (name discover) + (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)) - (deps (../generator/gen.exe)) - (action (run ${<} -o ${@})))) + (targets foo.ml) + (deps ../generator/gen.exe) + (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) - (deps (my-test-program.exe)) - (action (run ${<})))) + (name runtest) + (deps my-test-program.exe) + (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 -linked with the compiler libraries and ``-linkall``. Moreover, -currently toplevels can only be built in bytecode. +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 ``jbuild`` file: +As a result, write this in your ``dune`` file: .. code:: scheme - (jbuild_version 1) - (executable - ((name mytoplevel) - (libraries (compiler-libs.toplevel mylib)) - (link_flags (-linkall)) - (modes (byte)))) + (name mytoplevel) + (libraries compiler-libs.toplevel mylib) + (link_flags (-linkall)) + (modes byte)) And write this in ``mytoplevel.ml``