Add an (inline ...) stanza

CHANGES.md

@@ -19,11 +19,14 @@ next
   absolute path but with the context's environment set appropriately. Lastly,
   `jbuilder exec` will change the root as to which paths are relative using the
   `-root` option. (#286)
-  
+
 - Fix `jbuilder rules` printing rules when some binaries are missing (#292)
 
 - Build documentation for non public libraries (#306)
 
+- Add an `(inline)` allowing one to auto-generate part of a jbuild
+  file and keep it up-to-date (#371)
+
 1.0+beta16 (05/11/2017)
 -----------------------
 

Makefile

@@ -33,28 +33,12 @@ clean:
 doc:
 	cd doc && sphinx-build . _build
 
-CMDS = $(shell $(BIN) --help=plain | \
-  sed -n '/COMMANDS/,/OPTIONS/p' | sed -En 's/^       ([a-z-]+)/\1/p')
-
 update-jbuilds: $(BIN)
-	sed -n '1,/;;GENERATED/p' doc/jbuild > doc/jbuild.tmp
-	{ for cmd in $(CMDS); do \
-	    echo -ne "\n"\
-	"(rule\n"\
-	"  ((targets (jbuilder-$$cmd.1))\n"\
-	"   (action  (with-stdout-to $$""{@}\n"\
-	"             (run $$""{bin:jbuilder} $$cmd --help=groff)))))\n"\
-	"\n"\
-	"(install\n"\
-	" ((section man)\n"\
-	"  (files (jbuilder-$$cmd.1))))\n"; \
-	  done } >> doc/jbuild.tmp
-	rm -f doc/jbuild
-	mv doc/jbuild.tmp doc/jbuild
+	$(BIN) build --dev @jbuild
 
 accept-corrections:
 	for i in `find . -name \*.corrected`; do \
-	  cp $$i $${i/.corrected}; \
+	  cp $$i $${i%.corrected}; \
 	done
 
 .DEFAULT_GOAL := default

bin/main.ml

@@ -21,6 +21,7 @@ type common =
   ; target_prefix    : string
   ; only_packages    : String_set.t option
   ; capture_outputs  : bool
+  ; diff_command     : string option
   ; (* Original arguments for the external-lib-deps hint *)
     orig_args        : string list
   }
@@ -38,6 +39,7 @@ let set_common c ~targets =
   if c.root <> Filename.current_dir_name then
     Sys.chdir c.root;
   Clflags.workspace_root := Sys.getcwd ();
+  Clflags.diff_command := c.diff_command;
   Clflags.external_lib_deps_hint :=
     List.concat
       [ ["jbuilder"; "external-lib-deps"; "--missing"]
@@ -153,6 +155,7 @@ let common =
         verbose
         no_buffer
         workspace_file
+        diff_command
         (root, only_packages, orig)
     =
     let root, to_cwd =
@@ -178,6 +181,7 @@ let common =
     ; root
     ; orig_args
     ; target_prefix = String.concat ~sep:"" (List.map to_cwd ~f:(sprintf "%s/"))
+    ; diff_command
     ; only_packages =
         Option.map only_packages
           ~f:(fun s -> String_set.of_list (String.split s ~on:','))
@@ -304,6 +308,12 @@ let common =
                $ only_packages
                $ frop))
   in
+  let diff_command =
+    Arg.(value
+         & opt (some string) None
+         & info ["diff-command"] ~docs
+             ~doc:"Shell command to use to diff files")
+  in
   Term.(const make
         $ concurrency
         $ ddep_path
@@ -313,6 +323,7 @@ let common =
         $ verbose
         $ no_buffer
         $ workspace_file
+        $ diff_command
         $ root_and_only_packages
        )
 

doc/jbuild

@@ -9,104 +9,105 @@
  ((section man)
   (files (jbuilder.1))))
 
-;; Run "make update-jbuilds" to update the rest of this file
-;;GENERATED
+(inline (run bash ${path:update-jbuild.sh} ${bin:jbuilder}))
 
 (rule
-  ((targets (jbuilder-build.1))
-   (action  (with-stdout-to ${@}
-             (run ${bin:jbuilder} build --help=groff)))))
+ ((targets (jbuilder-build.1))
+  (action  (with-stdout-to ${@}
+            (run ${bin:jbuilder} build --help=groff)))))
 
 (install
  ((section man)
   (files (jbuilder-build.1))))
 
 (rule
-  ((targets (jbuilder-clean.1))
-   (action  (with-stdout-to ${@}
-             (run ${bin:jbuilder} clean --help=groff)))))
+ ((targets (jbuilder-clean.1))
+  (action  (with-stdout-to ${@}
+            (run ${bin:jbuilder} clean --help=groff)))))
 
 (install
  ((section man)
   (files (jbuilder-clean.1))))
 
 (rule
-  ((targets (jbuilder-exec.1))
-   (action  (with-stdout-to ${@}
-             (run ${bin:jbuilder} exec --help=groff)))))
+ ((targets (jbuilder-exec.1))
+  (action  (with-stdout-to ${@}
+            (run ${bin:jbuilder} exec --help=groff)))))
 
 (install
  ((section man)
   (files (jbuilder-exec.1))))
 
 (rule
-  ((targets (jbuilder-external-lib-deps.1))
-   (action  (with-stdout-to ${@}
-             (run ${bin:jbuilder} external-lib-deps --help=groff)))))
+ ((targets (jbuilder-external-lib-deps.1))
+  (action  (with-stdout-to ${@}
+            (run ${bin:jbuilder} external-lib-deps --help=groff)))))
 
 (install
  ((section man)
   (files (jbuilder-external-lib-deps.1))))
 
 (rule
-  ((targets (jbuilder-install.1))
-   (action  (with-stdout-to ${@}
-             (run ${bin:jbuilder} install --help=groff)))))
+ ((targets (jbuilder-install.1))
+  (action  (with-stdout-to ${@}
+            (run ${bin:jbuilder} install --help=groff)))))
 
 (install
  ((section man)
   (files (jbuilder-install.1))))
 
 (rule
-  ((targets (jbuilder-installed-libraries.1))
-   (action  (with-stdout-to ${@}
-             (run ${bin:jbuilder} installed-libraries --help=groff)))))
+ ((targets (jbuilder-installed-libraries.1))
+  (action  (with-stdout-to ${@}
+            (run ${bin:jbuilder} installed-libraries --help=groff)))))
 
 (install
  ((section man)
   (files (jbuilder-installed-libraries.1))))
 
 (rule
-  ((targets (jbuilder-rules.1))
-   (action  (with-stdout-to ${@}
-             (run ${bin:jbuilder} rules --help=groff)))))
+ ((targets (jbuilder-rules.1))
+  (action  (with-stdout-to ${@}
+            (run ${bin:jbuilder} rules --help=groff)))))
 
 (install
  ((section man)
   (files (jbuilder-rules.1))))
 
 (rule
-  ((targets (jbuilder-runtest.1))
-   (action  (with-stdout-to ${@}
-             (run ${bin:jbuilder} runtest --help=groff)))))
+ ((targets (jbuilder-runtest.1))
+  (action  (with-stdout-to ${@}
+            (run ${bin:jbuilder} runtest --help=groff)))))
 
 (install
  ((section man)
   (files (jbuilder-runtest.1))))
 
 (rule
-  ((targets (jbuilder-subst.1))
-   (action  (with-stdout-to ${@}
-             (run ${bin:jbuilder} subst --help=groff)))))
+ ((targets (jbuilder-subst.1))
+  (action  (with-stdout-to ${@}
+            (run ${bin:jbuilder} subst --help=groff)))))
 
 (install
  ((section man)
   (files (jbuilder-subst.1))))
 
 (rule
-  ((targets (jbuilder-uninstall.1))
-   (action  (with-stdout-to ${@}
-             (run ${bin:jbuilder} uninstall --help=groff)))))
+ ((targets (jbuilder-uninstall.1))
+  (action  (with-stdout-to ${@}
+            (run ${bin:jbuilder} uninstall --help=groff)))))
 
 (install
  ((section man)
   (files (jbuilder-uninstall.1))))
 
 (rule
-  ((targets (jbuilder-utop.1))
-   (action  (with-stdout-to ${@}
-             (run ${bin:jbuilder} utop --help=groff)))))
+ ((targets (jbuilder-utop.1))
+  (action  (with-stdout-to ${@}
+            (run ${bin:jbuilder} utop --help=groff)))))
 
 (install
  ((section man)
   (files (jbuilder-utop.1))))
+
+(end)

doc/jbuild.rst

@@ -537,6 +537,34 @@ The difference between ``copy_files`` and ``copy_files#`` is the same
 as the difference between the ``copy`` and ``copy#`` action. See the
 `User actions`_ section for more details.
 
+inline
+------
+
+Inline blocks are written as follow:
+
+.. code:: scheme
+
+    (inline <action>)
+    <stanzas>
+    (end)
+
+When reading jbuild files, ``inline`` and ``end`` stanzas are
+ignored. However, when building the ``jbuild`` alias, jbuilder will
+run ``<action>`` and make sure that the output of the action matches
+``<stanzas>``. If not, jbuilder will update the jbuild file in place,
+print a diff and fail. You then have to restart the build to pick up
+the changes.
+
+You can use this feature to auto-generate a part of a jbuild file and
+keep it up to date. In order to make sure that the jbuild files are
+up-to-date, simply build the ``jbuild`` alias. For instance you can
+use this command line to build both the package and check the jbuild
+files:
+
+..code:: bash
+
+    $ jbuilder build @install @jbuild
+
 Common items
 ============
 

doc/update-jbuild.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+
+# CR-someday jdimino: maybe it's possible to get cmdliner to print that directly
+
+set -e -o pipefail
+
+jbuilder=$1
+
+CMDS=$($jbuilder --help=plain | \
+           sed -n '/COMMANDS/,/OPTIONS/p' | sed -En 's/^       ([a-z-]+)/\1/p')
+
+for cmd in $CMDS; do
+    cat <<EOF
+
+(rule
+ ((targets (jbuilder-$cmd.1))
+  (action  (with-stdout-to \${@}
+            (run \${bin:jbuilder} $cmd --help=groff)))))
+
+(install
+ ((section man)
+  (files (jbuilder-$cmd.1))))
+EOF
+done
+
+echo