Added an example with a configure step

example/sample-projects/with-configure-step/README.org

@@ -0,0 +1,36 @@
+This project shows how to add a configure step to a project using
+jbuilder.
+
+In order to keep things composable, it offers several way to configure
+the project:
+
+1. with the classic =./configure <args...>=. When doing this, the configuration
+   script are run immediately and the resulting configuration is frozen for the
+   rest of the build
+
+2. by copying =config.defaults= to =config= and editing it. The
+   configuration scripts will be run as part of the build using what
+   is written in =config=.  When =config= is edited, the configuration
+   scripts will be automatically re-run
+
+3. by doing nothing. The configuration scripts will be run as part of the build
+   using the default values provided in =config.defaults=
+
+Technically this is how it works:
+
+=configure= is a simple OCaml script that:
+- parses the command line
+- generates a =config= file using what was given on the command line
+- calls =ocaml real_configure.ml=
+- =real_configure.ml= does some stuff and generates =config.full=
+
+=config.full= is what is used by the rest of the build.
+
+Now in order to support (2) and (3), we setup the following rules in
+the toplevel =jbuild=:
+- a rule to procude =config= by copying =config.default=
+- a rule to produce =config.full= by running =real_configure.ml=
+
+The reason it all work as described is because if Jbuilder knows how
+to build a file and this file is already present in the source tree,
+it will always prefer the file that's already there

example/sample-projects/with-configure-step/config.defaults

@@ -0,0 +1,7 @@
+(* -*- tuareg -*- *)
+
+(* Default configuration, copy this file to "config" and edit it to change the build
+   configuration. Alternatively call ./configure *)
+
+(* Enable support for blah *)
+let enable_blah = Auto

example/sample-projects/with-configure-step/config_common.ml

@@ -0,0 +1,11 @@
+(* Various types used by configure and real_configure.ml *)
+
+type switch =
+  | Yes
+  | No
+  | Auto
+
+let string_of_switch = function
+  | Yes  -> "Yes"
+  | No   -> "No"
+  | Auto -> "Auto"

example/sample-projects/with-configure-step/configure

@@ -0,0 +1,27 @@
+#!/usr/bin/env ocaml
+(* -*- tuareg -*- *)
+
+#warnings "-40";;
+
+#use "config_common.ml"
+
+let () =
+  let enable_blah = ref Auto in
+  Arg.parse
+    (Arg.align
+       [ "--enable-blah", Unit (fun () -> enable_blah := Yes),
+         " Enable support for blah"
+       ; "--disable-blah", Unit (fun () -> enable_blah := No),
+         " Enable support for blah"
+       ])
+    (fun s -> raise (Arg.Bad (Printf.sprintf "don't know what to do with %S" s)))
+    "Usage: ./configure [OPTIONS]";
+  let oc = open_out_bin "config" in
+  Printf.fprintf oc {|
+let enable_blah = %s
+|}
+    (string_of_switch !enable_blah);
+  close_out oc
+;;
+
+#use "real_configure.ml"

example/sample-projects/with-configure-step/jbuild

@@ -0,0 +1,11 @@
+(jbuild_version 1)
+
+(rule
+ ((targets (config))
+  (deps    (config.defaults))
+  (action  (copy ${<} ${@}))))
+
+(rule
+ ((targets (config.full))
+  (deps    (config_common.ml config))
+  (action  (run ${OCAML} ${path:real_configure.ml}))))

example/sample-projects/with-configure-step/myproject.opam

@@ -0,0 +1,11 @@
+opam-version: "1.2"
+version: "1.0"
+maintainer: "bob@sponge.com"
+authors: ["SpongeBob"]
+homepage: "https://github.com/SpongeBob/myproject"
+bug-reports: "https://github.com/SpongeCob/myproject/issues"
+dev-repo: "https://github.com/SpongeBob/myproject.git"
+license: "Apache-2.0"
+build: [
+  ["jbuilder" "build" "--only" "myproject" "--root" "." "-j" jobs "@install"]
+]

example/sample-projects/with-configure-step/real_configure.ml

@@ -0,0 +1,24 @@
+#use "config_common.ml"
+#use "config"
+
+let with_blah =
+  match enable_blah with
+  | Yes  -> true
+  | No   -> false
+  | Auto -> true (* replace by some detection code *)
+
+let blah_path =
+  if with_blah then
+    (* replace by some relevant stuff *)
+    "/path/to/blah"
+  else
+    "<no support for blah>"
+
+let () =
+  let oc = open_out_bin "config.full" in
+  Printf.fprintf oc {|
+let with_blah = %B
+let blah_path = %S
+|}
+    with_blah blah_path
+

example/sample-projects/with-configure-step/src/jbuild

@@ -0,0 +1,14 @@
+(jbuild_version 1)
+
+(executables
+ ((names (plop))))
+
+(install
+ ((section bin)
+  (files ((plop.exe as plop)))))
+
+(rule
+ ((targets (config.ml))
+  (deps    (../config.full))
+  (action  (copy ${<} ${@}))))
+

example/sample-projects/with-configure-step/src/plop.ml

@@ -0,0 +1,5 @@
+let () =
+  Printf.printf "Built with support for blah: %B\n\
+                 Path to blah is:             %S\n"
+    Config.with_blah
+    Config.blah_path