From fb0ac48af22d38d343ab78bf9207864354d0ab73 Mon Sep 17 00:00:00 2001 From: Rudi Grinberg Date: Wed, 11 Apr 2018 22:14:53 +0700 Subject: [PATCH 1/5] Documentation for new configurator --- doc/configurator.rst | 113 +++++++++++++++++++++++++++++++++++++++++++ doc/index.rst | 1 + doc/jbuild.rst | 3 +- 3 files changed, 115 insertions(+), 2 deletions(-) create mode 100644 doc/configurator.rst diff --git a/doc/configurator.rst b/doc/configurator.rst new file mode 100644 index 00000000..327cc872 --- /dev/null +++ b/doc/configurator.rst @@ -0,0 +1,113 @@ +************ +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 +`__, 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. + +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 + + 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 (dune.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 +`__ 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 ``dune.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/ diff --git a/doc/index.rst b/doc/index.rst index b8bb2f1a..4928bf37 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -18,5 +18,6 @@ Welcome to jbuilder's documentation! documentation usage advanced-topics + configurator faq known-issues diff --git a/doc/jbuild.rst b/doc/jbuild.rst index 1d229a1c..fc376ec5 100644 --- a/doc/jbuild.rst +++ b/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 `__ to write portable -scripts or `configurator `__ for -configuration related tasks. +scripts or `Configurator`_ for configuration related tasks. The following constructions are available: From 320154ef8780102925c030f6196b089c3494ae16 Mon Sep 17 00:00:00 2001 From: Rudi Grinberg Date: Wed, 11 Apr 2018 23:50:16 +0700 Subject: [PATCH 2/5] italicize running --- doc/configurator.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/configurator.rst b/doc/configurator.rst index 327cc872..623a2c96 100644 --- a/doc/configurator.rst +++ b/doc/configurator.rst @@ -17,8 +17,8 @@ Configurator allows you to query for the following features: * 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 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 `__, but now lives in dune. You do From 9673d4eaf91ed4cc46a73ed34963d9da62f668d2 Mon Sep 17 00:00:00 2001 From: Rudi Grinberg Date: Wed, 11 Apr 2018 23:50:23 +0700 Subject: [PATCH 3/5] Switch jbuilder in library names --- doc/configurator.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/configurator.rst b/doc/configurator.rst index 623a2c96..e2ea6ce4 100644 --- a/doc/configurator.rst +++ b/doc/configurator.rst @@ -63,7 +63,7 @@ invoke it as an executable and tell dune about the targets that it produces: (executable ((name discover) - (libraries (dune.configurator)))) + (libraries (jbuilder.configurator)))) (rule ((targets (config.h)) @@ -97,7 +97,7 @@ 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 ``dune.configurator`` +* 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. From 0d9669f907379c55e4d8617d1339118381de560a Mon Sep 17 00:00:00 2001 From: Rudi Grinberg Date: Thu, 12 Apr 2018 00:05:44 +0700 Subject: [PATCH 4/5] Add link to .mli as a stand in for the api docs --- doc/configurator.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/configurator.rst b/doc/configurator.rst index e2ea6ce4..5f449f39 100644 --- a/doc/configurator.rst +++ b/doc/configurator.rst @@ -28,7 +28,8 @@ Usage ===== We'll describe configurator with a simple example. Everything else can be easily -learned by studying configurator's API. +learned by studying `configurator's API +`__. 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 From 620bffd21b2193b3738e865f5cd3349838960315 Mon Sep 17 00:00:00 2001 From: Rudi Grinberg Date: Thu, 12 Apr 2018 09:12:56 +0700 Subject: [PATCH 5/5] Add , for lists --- doc/configurator.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/configurator.rst b/doc/configurator.rst index 5f449f39..73d49f74 100644 --- a/doc/configurator.rst +++ b/doc/configurator.rst @@ -9,11 +9,11 @@ stubs, but there are no limitations on this. Configurator allows you to query for the following features: -* Variables defined in ``ocamlc - config`` +* Variables defined in ``ocamlc - config``, -* pkg-config_ flags for packages +* pkg-config_ flags for packages, -* Test features by compiling C code +* Test features by compiling C code, * Extract compile time information such as ``#define`` variables. @@ -88,17 +88,17 @@ The old configurator is the independent `configurator and users are encouraged to migrate to dune's own configurator. The advantage of the transition include: -* No extra dependencies +* No extra dependencies, -* No need to manually pass ``-ocamlc`` flag +* No need to manually pass ``-ocamlc`` flag, -* New configurator is cross compilation compatible +* 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 +* Mentions of the ``configurator`` opam package should be removed. -* The library name ``configurator`` should be changed ``jbuilder.configurator`` +* 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.