Merge pull request #696 from rgrinberg/configurator-doc

Documentation for new configurator

doc/configurator.rst

@@ -0,0 +1,114 @@
+************
+Configurator
+************
+
+Configurator is a small library designed to query features available on the
+system, in order to generate configuration for dune builds. Such generated
+configuration is usually in the form of command line flags, generated headers,
+stubs, but there are no limitations on this.
+
+Configurator allows you to query for the following features:
+
+* Variables defined in ``ocamlc - config``,
+
+* pkg-config_ flags for packages,
+
+* Test features by compiling C code,
+
+* Extract compile time information such as ``#define`` variables.
+
+Configurator is designed to be cross compilation friendly and avoids _running_
+any compiled code to extract any of the information above.
+
+Configurator started as an `independent library
+<https://github.com/janestreet/configurator>`__, but now lives in dune. You do
+not need to install anything to use configurator.
+
+Usage
+=====
+
+We'll describe configurator with a simple example. Everything else can be easily
+learned by studying `configurator's API
+<https://github.com/ocaml/dune/blob/master/src/configurator/v1.mli>`__.
+
+To use configurator, we write an executable that will query the system using
+configurator's API and output a set of targets reflecting the results. For
+example:
+
+.. code-block:: ocaml
+
+  module C = Configurator.V1
+
+  let clock_gettime_code = {|
+  #include <time.h>
+
+  int main()
+  {
+    struct timespec ts;
+    clock_gettime(CLOCK_REALTIME, &ts);
+    return 0;
+  }
+  |}
+
+  let () =
+    C.main ~name:"foo" (fun c ->
+      let has_clock_gettime = C.c_test c clock_gettime_code ~link_flags:["-lrt"] in
+
+      C.C_define.gen_header_file c ~fname:"config.h"
+        [ "HAS_CKOCK_GETTIME", Switch has_ckock_gettime ]);
+
+Usually, the module above would be named ``discover.ml``. The next step is to
+invoke it as an executable and tell dune about the targets that it produces:
+
+.. code-block:: lisp
+
+  (executable
+   ((name discover)
+    (libraries (jbuilder.configurator))))
+
+  (rule
+   ((targets (config.h))
+    (action (run ./discover.exe))))
+
+Another common pattern is to produce a flags file with configurator and then use
+this flag file using ``:include``:
+
+.. code-block:: lisp
+
+  (library
+   ((name mylib)
+    (c_names (foo))
+    (c_library_flags (:include (flags.sexp)))))
+
+Upgrading from the old Configurator
+===================================
+
+The old configurator is the independent `configurator
+<https://github.com/janestreet/configurator>`__ opam package. It is deprecated
+and users are encouraged to migrate to dune's own configurator. The advantage of
+the transition include:
+
+* No extra dependencies,
+
+* No need to manually pass ``-ocamlc`` flag,
+
+* New configurator is cross compilation compatible.
+
+The following steps must be taken to transition from the old configurator:
+
+* Mentions of the ``configurator`` opam package should be removed.
+
+* The library name ``configurator`` should be changed ``jbuilder.configurator``.
+
+* The ``-ocamlc`` flag in rules that run configurator scripts should be removed.
+  This information is now passed automatically by dune.
+
+* The new configurator API is versioned explicitly. The version that is
+  compatible with old configurator is under the ``V1`` module. Hence, to
+  transition one's code it's enough to add this module alias:
+
+.. code-block:: ocaml
+
+   module Configurator = Configurator.V1
+
+.. _pkg-config: https://www.freedesktop.org/wiki/Software/pkg-config/

doc/index.rst

@@ -18,5 +18,6 @@ Welcome to jbuilder's documentation!
    documentation
    usage
    advanced-topics
+   configurator
    faq
    known-issues

doc/jbuild.rst

@@ -1157,8 +1157,7 @@ automatically handled by Jbuilder.
 The DSL is currently quite limited, so if you want to do something complicated
 it is recommended to write a small OCaml program and use the DSL to invoke it.
 You can use `shexp <https://github.com/janestreet/shexp>`__ to write portable
-scripts or `configurator <https://github.com/janestreet/configurator>`__ for
-configuration related tasks.
+scripts or `Configurator`_ for configuration related tasks.
 
 The following constructions are available: