Add a promote actions and include stanzas

Add a promote action that allows to copy over generated files as
source files and an include stanza allowing to include a file in a
jbuild file.

CHANGES.md

@@ -33,6 +33,12 @@ next
   [opam-cross-windows](https://github.com/whitequark/opam-cross-windows)
   (#355)
 
+- Add an `(include ...)` stanza allowing one to include another
+  non-generated jbuild file in the current file (#402)
+
+- Add a `(promote (<file1> as <file2>) ...)` action allowing one to
+  promote generated files as source files (#402)
+
 1.0+beta16 (05/11/2017)
 -----------------------
 

Makefile

@@ -33,24 +33,8 @@ 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 --promote copy
 
 accept-corrections:
 	for i in `find . -name \*.corrected`; do \

bin/main.ml

@@ -22,6 +22,8 @@ type common =
   ; only_packages    : String_set.t option
   ; capture_outputs  : bool
   ; x                : string option
+  ; diff_command     : string option
+  ; promote_mode     : Clflags.promote_mode
   ; (* Original arguments for the external-lib-deps hint *)
     orig_args        : string list
   }
@@ -39,6 +41,8 @@ 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.promote_mode := c.promote_mode;
   Clflags.external_lib_deps_hint :=
     List.concat
       [ ["jbuilder"; "external-lib-deps"; "--missing"]
@@ -156,6 +160,8 @@ let common =
         verbose
         no_buffer
         workspace_file
+        diff_command
+        promote_mode
         (root, only_packages, orig)
         x
     =
@@ -182,6 +188,8 @@ let common =
     ; root
     ; orig_args
     ; target_prefix = String.concat ~sep:"" (List.map to_cwd ~f:(sprintf "%s/"))
+    ; diff_command
+    ; promote_mode
     ; only_packages =
         Option.map only_packages
           ~f:(fun s -> String_set.of_list (String.split s ~on:','))
@@ -315,6 +323,36 @@ let common =
          & info ["x"] ~docs
              ~doc:{|Cross-compile using this toolchain.|})
   in
+  let diff_command =
+    Arg.(value
+         & opt (some string) None
+         & info ["diff-command"] ~docs
+             ~doc:"Shell command to use to diff files")
+  in
+  let promote =
+    let mode =
+      Arg.(conv
+             (Arg.parser_of_kind_of_string ~kind:"promotion mode"
+                (function
+                  | "ignore" -> Some Clflags.Ignore
+                  | "check" -> Some Check
+                  | "copy" -> Some Copy
+                  | _ -> None),
+              fun ppf mode ->
+                Format.pp_print_string ppf
+                  (match mode with
+                   | Clflags.Ignore -> "ignore"
+                   | Check -> "check"
+                   | Copy -> "copy")))
+    in
+    Arg.(value
+         & opt mode Check
+         & info ["promote"] ~docs
+             ~doc:"How to interpret promote actions. $(b,check), the default, means to
+                   only check that promoted files are equal to the source files.
+                   $(b,ignore) means to ignore promote action altogether and $(b,copy)
+                   means to copy generated files to the source tree.")
+  in
   Term.(const make
         $ concurrency
         $ ddep_path
@@ -324,6 +362,8 @@ let common =
         $ verbose
         $ no_buffer
         $ workspace_file
+        $ diff_command
+        $ promote
         $ root_and_only_packages
         $ x
        )

doc/jbuild

@@ -9,104 +9,12 @@
  ((section man)
   (files (jbuilder.1))))
 
-;; Run "make update-jbuilds" to update the rest of this file
-;;GENERATED
+(include jbuild.inc)
 
 (rule
-  ((targets (jbuilder-build.1))
-   (action  (with-stdout-to ${@}
-             (run ${bin:jbuilder} build --help=groff)))))
+ (with-stdout-to jbuild.inc.gen
+  (run bash ${path:update-jbuild.sh} ${bin:jbuilder})))
 
-(install
- ((section man)
-  (files (jbuilder-build.1))))
-
-(rule
-  ((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)))))
-
-(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)))))
-
-(install
- ((section man)
-  (files (jbuilder-external-lib-deps.1))))
-
-(rule
-  ((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)))))
-
-(install
- ((section man)
-  (files (jbuilder-installed-libraries.1))))
-
-(rule
-  ((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)))))
-
-(install
- ((section man)
-  (files (jbuilder-runtest.1))))
-
-(rule
-  ((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)))))
-
-(install
- ((section man)
-  (files (jbuilder-uninstall.1))))
-
-(rule
-  ((targets (jbuilder-utop.1))
-   (action  (with-stdout-to ${@}
-             (run ${bin:jbuilder} utop --help=groff)))))
-
-(install
- ((section man)
-  (files (jbuilder-utop.1))))
+(alias
+ ((name jbuild)
+  (action (promote (jbuild.inc.gen as jbuild.inc)))))

doc/jbuild.inc

@@ -0,0 +1,100 @@
+
+(rule
+ ((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)))))
+
+(install
+ ((section man)
+  (files (jbuilder-clean.1))))
+
+(rule
+ ((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)))))
+
+(install
+ ((section man)
+  (files (jbuilder-external-lib-deps.1))))
+
+(rule
+ ((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)))))
+
+(install
+ ((section man)
+  (files (jbuilder-installed-libraries.1))))
+
+(rule
+ ((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)))))
+
+(install
+ ((section man)
+  (files (jbuilder-runtest.1))))
+
+(rule
+ ((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)))))
+
+(install
+ ((section man)
+  (files (jbuilder-uninstall.1))))
+
+(rule
+ ((targets (jbuilder-utop.1))
+  (action  (with-stdout-to ${@}
+            (run ${bin:jbuilder} utop --help=groff)))))
+
+(install
+ ((section man)
+  (files (jbuilder-utop.1))))
+