Introduce dune ocaml command group

CHANGES.md

@@ -7,7 +7,7 @@ Unreleased
 - Fixed a bug that could result in needless recompilation under Windows due to
   case differences in the result of `Sys.getcwd` (observed under `emacs`).
   (#3966, @nojb).
-  
+
 - Fixed absence of executable bit for installed `.cmxs` (#4149, fixes #4148, @bobot)
 
 - Allow `%{version:pkg}` to work for external packages (#4104, @kit-ty-kate)
@@ -17,6 +17,9 @@ Unreleased
 - Automatically generate empty `.mli` files for executables and tests (#3768,
   fixes #3745, @CraigFe)
 
+- Add `ocaml` command subgroup for OCaml related commands such as `utop`, `top`,
+  and `merlin` (#3936, @rgrinberg).
+
 2.8.2 (21/01/2021)
 ------------------
 

bin/import.ml

@@ -29,6 +29,8 @@ module Profile = Dune_rules.Profile
 module Log = Dune_util.Log
 include Common.Let_syntax
 
+let in_group (t, info) = (Term.Group.Term t, info)
+
 let make_cache (config : Config.t) =
   let make_cache () =
     let command_handler (Cache.Dedup file) =

bin/main.ml

@@ -1,31 +1,36 @@
 open! Stdune
 open Import
 
-let all =
-  [ Installed_libraries.command
-  ; External_lib_deps.command
-  ; Build_cmd.build
-  ; Build_cmd.runtest
-  ; command_alias Build_cmd.runtest "test"
-  ; Clean.command
-  ; Install_uninstall.install
-  ; Install_uninstall.uninstall
-  ; Exec.command
-  ; Subst.command
-  ; Print_rules.command
-  ; Utop.command
-  ; Init.command
-  ; Promote.command
-  ; Printenv.command
-  ; Help.command
-  ; Format_dune_file.command
-  ; Compute.command
-  ; Upgrade.command
-  ; Caching.command
-  ; Describe.command
-  ; Top.command
-  ; Ocaml_merlin.command
-  ]
+let all : _ Term.Group.t list =
+  let terms =
+    [ Installed_libraries.command
+    ; External_lib_deps.command
+    ; Build_cmd.build
+    ; Build_cmd.runtest
+    ; command_alias Build_cmd.runtest "test"
+    ; Clean.command
+    ; Install_uninstall.install
+    ; Install_uninstall.uninstall
+    ; Exec.command
+    ; Subst.command
+    ; Print_rules.command
+    ; Utop.command
+    ; Init.command
+    ; Promote.command
+    ; Printenv.command
+    ; Help.command
+    ; Format_dune_file.command
+    ; Compute.command
+    ; Upgrade.command
+    ; Caching.command
+    ; Describe.command
+    ; Top.command
+    ; Ocaml_merlin.command
+    ]
+    |> List.map ~f:in_group
+  in
+  let groups = [ Ocaml.group ] in
+  terms @ groups
 
 let common_commands_synopsis =
   (* Short reminders for the most used and useful commands *)
@@ -88,7 +93,7 @@ let default =
 let () =
   Colors.setup_err_formatter_colors ();
   try
-    match Term.eval_choice default all ~catch:false with
+    match Term.Group.eval default all ~catch:false with
     | `Error _ -> exit 1
     | _ -> exit 0
   with exn ->

bin/ocaml.ml

@@ -0,0 +1,11 @@
+open Import
+
+let info = Term.info "ocaml"
+
+let group =
+  ( Term.Group.Group
+      [ in_group Utop.command
+      ; in_group Ocaml_merlin.command
+      ; in_group Top.command
+      ]
+  , info )

bin/ocaml.mli

@@ -0,0 +1,3 @@
+open Import
+
+val group : unit Term.Group.t

bin/top.mli

@@ -0,0 +1 @@
+val command : unit Cmdliner.Term.t * Cmdliner.Term.info

doc/dune.inc

@@ -1,4 +1,13 @@
 
+(rule
+ (with-stdout-to dune-test.1
+  (run dune test --help=groff)))
+
+(install
+ (section man)
+ (package dune)
+ (files   dune-test.1))
+
 (rule
  (with-stdout-to dune-build.1
   (run dune build --help=groff)))
@@ -107,6 +116,15 @@
  (package dune)
  (files   dune-installed-libraries.1))
 
+(rule
+ (with-stdout-to dune-ocaml.1
+  (run dune ocaml --help=groff)))
+
+(install
+ (section man)
+ (package dune)
+ (files   dune-ocaml.1))
+
 (rule
  (with-stdout-to dune-ocaml-merlin.1
   (run dune ocaml-merlin --help=groff)))
@@ -197,12 +215,3 @@
  (package dune)
  (files   dune-utop.1))
 
-(rule
- (with-stdout-to dune-test.1
-  (run dune test --help=groff)))
-
-(install
- (section man)
- (package dune)
- (files   dune-test.1))
-

doc/toplevel-integration.rst

@@ -13,9 +13,9 @@ simply execute the following in your toplevel:
 
 .. code:: ocaml
 
-    # #use_output "dune top";;
+    # #use_output "dune ocaml top";;
 
-``dune top`` is a dune command that builds all the libraries in the
+``dune ocaml top`` is a dune command that builds all the libraries in the
 current directory and sub-directories and output the relevant toplevel
 directives (``#directory`` and ``#load``) to make the various modules
 available in the toplevel.
@@ -25,9 +25,9 @@ you type in the toplevel will be rewritten with these ppx rewriters.
 
 This command is available since Dune 2.5.0.
 
-Note that the ``#use_output`` directivce is only available since OCaml
-4.11. You can add the following snippet to your ``~/.ocamlinit`` file
-to make it available in older versions of OCaml:
+Note that the ``#use_output`` directive is only available since OCaml 4.11. You
+can add the following snippet to your ``~/.ocamlinit`` file to make it available
+in older versions of OCaml:
 
 .. code:: ocaml
 

doc/update-jbuild.sh

@@ -5,7 +5,7 @@
 set -e -o pipefail
 
 CMDS=$(dune --help=plain | \
-           sed -n '/COMMANDS/,/OPTIONS/p' | sed -En 's/^       ([a-z-]+) ?.*/\1/p')
+           sed -n '/COMMAND ALIASES/,/OPTIONS/p' | sed -En 's/^       ([a-z-]+) ?.*/\1/p')
 
 for cmd in $CMDS; do
     cat <<EOF

test/blackbox-tests/test-cases/cmdliner-dep-conf.t/run.t

@@ -14,13 +14,13 @@
   [1]
 
   $ dune build "(fi"
-  dune: TARGET... arguments: unclosed parenthesis at end of input
+  dune build: TARGET... arguments: unclosed parenthesis at end of input
   Usage: dune build [OPTION]... [TARGET]...
   Try `dune build --help' or `dune --help' for more information.
   [1]
 
   $ dune build "()"
-  dune: TARGET... arguments: Unexpected list
+  dune build: TARGET... arguments: Unexpected list
   Usage: dune build [OPTION]... [TARGET]...
   Try `dune build --help' or `dune --help' for more information.
   [1]

test/blackbox-tests/test-cases/describe.t/run.t

@@ -94,10 +94,10 @@ Test errors
   [1]
 
   $ dune describe --lang 1.0
-  dune: Only --lang 0.1 is available at the moment as this command is not yet
-        stabilised. If you would like to release a software that relies on the output
-        of 'dune describe', please open a ticket on
-        https://github.com/ocaml/dune.
+  dune describe: Only --lang 0.1 is available at the moment as this command is not yet
+                 stabilised. If you would like to release a software that relies on the output
+                 of 'dune describe', please open a ticket on
+                 https://github.com/ocaml/dune.
   Usage: dune describe [OPTION]... [STRING]...
   Try `dune describe --help' or `dune --help' for more information.
   [1]

test/blackbox-tests/test-cases/dune-init.t/run.t

@@ -239,10 +239,11 @@ Comments in dune files are preserved
 Will not create components with invalid names
 
   $ dune init lib invalid-component-name ./_test_lib
-  dune: NAME argument: invalid component name `invalid-component-name'
-        Library names must be non-empty and composed only of the
-        following
-        characters: 'A'..'Z', 'a'..'z', '_' or '0'..'9'.
+  dune init: NAME argument: invalid component name
+             `invalid-component-name'
+             Library names must be non-empty and composed only of the
+             following
+             characters: 'A'..'Z', 'a'..'z', '_' or '0'..'9'.
   Usage: dune init [OPTION]... INIT_KIND NAME [PATH]
   Try `dune init --help' or `dune --help' for more information.
   [1]
@@ -252,8 +253,8 @@ Will not create components with invalid names
 Will fail and inform user when invalid component command is given
 
   $ dune init foo blah
-  dune: INIT_KIND argument: invalid value `foo', expected one of `executable',
-        `library', `project' or `test'
+  dune init: INIT_KIND argument: invalid value `foo', expected one of
+             `executable', `library', `project' or `test'
   Usage: dune init [OPTION]... INIT_KIND NAME [PATH]
   Try `dune init --help' or `dune --help' for more information.
   [1]

test/blackbox-tests/test-cases/findlib-dynload.t/run.t

@@ -51,15 +51,15 @@
   b: called
   a: called
 
-  $ dune exe mytool_auto
+  $ dune exec mytool_auto
   m: init
   a: init
   b: init
   b: registering
   b: called
   a: called
 
-  $ dune exe mytool c_thread
+  $ dune exec mytool c_thread
   m: init
   c_thread: registering
 

test/blackbox-tests/test-cases/format-dune-file.t/run.t

@@ -171,7 +171,7 @@ Files in OCaml syntax are copied verbatim (but error when passed in stdin).
 
 Non 0 error code:
 
-  $ echo "(" | dune format ; echo $?
+  $ echo "(" | dune format-dune-file ; echo $?
   File "", line 2, characters 0-0:
   Error: unclosed parenthesis at end of input
   1

test/blackbox-tests/test-cases/github3046.t/run.t

@@ -7,28 +7,29 @@ are given as parameters
 `dune init exe main --libs="str gsl"` returns an informative parsing error
 
   $ dune init exe main --libs="str gsl"
-  dune: option `--libs': invalid element in list (`str gsl'): expected a valid
-        dune atom
+  dune init: option `--libs': invalid element in list (`str gsl'): expected a
+             valid dune atom
   Usage: dune init [OPTION]... INIT_KIND NAME [PATH]
   Try `dune init --help' or `dune --help' for more information.
   [1]
 
 `dune init lib foo --ppx="foo bar"` returns an informative parsing error
 
   $ dune init lib foo --ppx="foo bar"
-  dune: option `--ppx': invalid element in list (`foo bar'): expected a valid
-        dune atom
+  dune init: option `--ppx': invalid element in list (`foo bar'): expected a
+             valid dune atom
   Usage: dune init [OPTION]... INIT_KIND NAME [PATH]
   Try `dune init --help' or `dune --help' for more information.
   [1]
 
 `dune init lib foo --public="some/invalid&name!"` returns an informative parsing error
 
   $ dune init lib foo --public="some/invalid&name!"
-  dune: option `--public': invalid component name `some/invalid&name!'
-        Library names must be non-empty and composed only of the
-        following
-        characters: 'A'..'Z', 'a'..'z', '_' or '0'..'9'.
+  dune init: option `--public': invalid component name
+             `some/invalid&name!'
+             Library names must be non-empty and composed only of the
+             following
+             characters: 'A'..'Z', 'a'..'z', '_' or '0'..'9'.
   Usage: dune init [OPTION]... INIT_KIND NAME [PATH]
   Try `dune init --help' or `dune --help' for more information.
   [1]

test/blackbox-tests/test-cases/github3530.t/run.t

@@ -2,15 +2,15 @@ When an empty string is passed to `-p`, we get a nice error message.
 
   $ echo '(lang dune 2.0)' > dune-project
   $ dune build -p ''
-  dune: option `-p': Invalid package name: ""
+  dune build: option `-p': Invalid package name: ""
   Usage: dune build [OPTION]... [TARGET]...
   Try `dune build --help' or `dune --help' for more information.
   [1]
 
 This can happen in a list as well:
 
   $ dune build -p 'a,b,'
-  dune: option `-p': Invalid package name: ""
+  dune build: option `-p': Invalid package name: ""
   Usage: dune build [OPTION]... [TARGET]...
   Try `dune build --help' or `dune --help' for more information.
   [1]

test/blackbox-tests/test-cases/misc.t/run.t

@@ -6,37 +6,37 @@ Test that incompatible options are properly reported
 ----------------------------------------------------
 
   $ dune build --verbose --display quiet
-  dune: Cannot use --verbose and --display simultaneously
+  dune build: Cannot use --verbose and --display simultaneously
   Usage: dune build [OPTION]... [TARGET]...
   Try `dune build --help' or `dune --help' for more information.
   [1]
 
   $ dune build -p toto --root .
-  dune: Cannot use --root and -p simultaneously
+  dune build: Cannot use --root and -p simultaneously
   Usage: dune build [OPTION]... [TARGET]...
   Try `dune build --help' or `dune --help' for more information.
   [1]
 
   $ dune build --for-release-of-packages toto --root .
-  dune: Cannot use --root and --for-release-of-packages simultaneously
+  dune build: Cannot use --root and --for-release-of-packages simultaneously
   Usage: dune build [OPTION]... [TARGET]...
   Try `dune build --help' or `dune --help' for more information.
   [1]
 
   $ dune build --no-config --config x
-  dune: Cannot use --config and --no-config simultaneously
+  dune build: Cannot use --config and --no-config simultaneously
   Usage: dune build [OPTION]... [TARGET]...
   Try `dune build --help' or `dune --help' for more information.
   [1]
 
   $ dune build -p toto --release
-  dune: Cannot use --release and -p simultaneously
+  dune build: Cannot use --release and -p simultaneously
   Usage: dune build [OPTION]... [TARGET]...
   Try `dune build --help' or `dune --help' for more information.
   [1]
 
   $ dune build --release --root .
-  dune: Cannot use --root and --release simultaneously
+  dune build: Cannot use --root and --release simultaneously
   Usage: dune build [OPTION]... [TARGET]...
   Try `dune build --help' or `dune --help' for more information.
   [1]

test/blackbox-tests/test-cases/pipe-actions.t/run.t

@@ -52,7 +52,7 @@ The makefile version of pipe actions uses actual pipes:
   >    (pipe-outputs (run a) (run b) (run c)))))
   > EOF
 
-  $ dune rule -m target
+  $ dune rules -m target
   _build/default/target: _build/install/default/bin/a \
     _build/install/default/bin/b _build/install/default/bin/c
   	mkdir -p _build/default; \