unikernel/duniverse/dune_/doc/howto/toplevel.rst

@@ -0,0 +1,55 @@
+How to Load a Project in a Toplevel
+===================================
+
+It is possible to use OCaml code in an interactive way, by typing an
+expression, which gets evaluated and its result printed. Such a program is
+called a `toplevel`, or REPL (Read-Eval-Print Loop).
+
+The compiler distribution comes with a small REPL called simply ``ocaml``, and
+the community has developed enhanced versions such as `UTop
+<https://github.com/ocaml-community/utop>`_.
+
+Building a Specialized UTop Executable
+--------------------------------------
+
+It is possible to generate a specialized version of UTop that embeds the
+current project. To do so, use the following command:
+
+.. code:: console
+
+  $ dune utop
+
+The interactive session will start with all the modules loaded.
+
+If some of the libraries are PPX rewriters, the phrases you type in the
+toplevel will be rewritten with these PPX rewriters. Similarly, PPX derivers
+defined in the project will be available.
+
+Loading the Project in a Toplevel
+---------------------------------
+
+It is also possible to load Dune projects in any toplevel. To do that, simply
+execute the following in your toplevel:
+
+.. code:: ocaml
+
+    # #use_output "dune ocaml top";;
+
+``dune ocaml top`` is a Dune command that builds all the libraries in the
+current directory and subdirectories and outputs the relevant toplevel
+directives (``#directory`` and ``#load``) to make the various modules
+available in the toplevel.
+
+Loading a Single Module in a Toplevel
+-------------------------------------
+
+It's also possible to load individual modules for interactive development. Use
+the following dune command:
+
+.. code:: ocaml
+
+  # #use_output "dune ocaml top-module foo.ml";;
+
+This will print directives that will load ``foo.ml`` without sealing it behind
+``foo.mli``. This is particularly useful for peeking and prodding at a module's
+internals.