Use new cmdliner in tests & dev pkgs

.github/workflows/ci.yml

@@ -35,7 +35,7 @@ jobs:
           opam-repositories: |
             default: https://github.com/ocaml/opam-repository.git
             mbarbin: https://github.com/mbarbin/opam-repository.git
-      #     alpha:   https://github.com/kit-ty-kate/opam-alpha-repository.git
+            alpha:   https://github.com/kit-ty-kate/opam-alpha-repository.git
       #     janestreet-bleeding: https://github.com/janestreet/opam-repository.git
       #     janestreet-bleeding-external: https://github.com/janestreet/opam-repository.git#external-packages
 

.github/workflows/deploy-doc.yml

@@ -42,7 +42,7 @@ jobs:
           opam-repositories: |
             default: https://github.com/ocaml/opam-repository.git
             mbarbin: https://github.com/mbarbin/opam-repository.git
-      #     alpha:   https://github.com/kit-ty-kate/opam-alpha-repository.git
+            alpha:   https://github.com/kit-ty-kate/opam-alpha-repository.git
       #     janestreet-bleeding: https://github.com/janestreet/opam-repository.git
       #     janestreet-bleeding-external: https://github.com/janestreet/opam-repository.git#external-packages
 

.github/workflows/test-deploy-doc.yml

@@ -42,7 +42,7 @@ jobs:
           opam-repositories: |
             default: https://github.com/ocaml/opam-repository.git
             mbarbin: https://github.com/mbarbin/opam-repository.git
-      #     alpha:   https://github.com/kit-ty-kate/opam-alpha-repository.git
+            alpha:   https://github.com/kit-ty-kate/opam-alpha-repository.git
       #     janestreet-bleeding: https://github.com/janestreet/opam-repository.git
       #     janestreet-bleeding-external: https://github.com/janestreet/opam-repository.git#external-packages
 

CHANGES.md

@@ -1,3 +1,12 @@
+## Unreleased
+
+### Changed
+
+- Require `cmdliner >= 2.1.1` for test packages (@mbarbin).
+- `cmdlang-to-cmdliner` still targets `cmdliner >= 1.3.0` for broad compatibility, but is no longer tested against versions older than 2.1.1 (@mbarbin).
+- Migrated expect and cram tests to `cmdliner.2.1.1`'s revised error/help output (@mbarbin).
+- Force `NO_COLOR=1` in the dev build environment so `cmdliner`'s ANSI-styled error and help output doesn't leak into expected traces (@mbarbin).
+
 ## 0.0.11 (2026-05-08)
 
 ### Added

cmdlang-dev.opam

@@ -18,7 +18,7 @@ depends: [
   "cmdlang-to-base" {= version}
   "cmdlang-to-climate" {= version}
   "cmdlang-to-cmdliner" {= version}
-  "cmdliner" {>= "1.3.0" & < "2.0"}
+  "cmdliner" {>= "2.1.1"}
   "conf-jq"
   "dune-build-info" {>= "3.17"}
   "mdx" {>= "2.4"}

cmdlang-tests.opam

@@ -17,7 +17,7 @@ depends: [
   "cmdlang-to-base" {= version}
   "cmdlang-to-climate" {= version}
   "cmdlang-to-cmdliner" {= version}
-  "cmdliner" {>= "1.3.0" & < "2.0"}
+  "cmdliner" {>= "2.1.1"}
   "core" {>= "v0.17"}
   "core_unix" {>= "v0.17"}
   "dune-build-info" {>= "3.17"}

cmdlang-to-cmdliner.opam

@@ -35,6 +35,12 @@ description: """\
 specified with [cmdlang] into [cmdliner] commands suitable for
 execution.
 
+This library aims to remain as compatible as possible with older
+versions of [cmdliner], down to [1.3]. However, it is only actively
+tested against the version of [cmdliner] used by this project's own
+test suite (currently [>= 2.1.1]), so older versions are no longer
+verified by CI.
+
 [cmdliner]: https://github.com/dbuenzli/cmdliner
 
 """

cmdlang-to-cmdliner.opam.template

@@ -4,6 +4,12 @@ description: """\
 specified with [cmdlang] into [cmdliner] commands suitable for
 execution.
 
+This library aims to remain as compatible as possible with older
+versions of [cmdliner], down to [1.3]. However, it is only actively
+tested against the version of [cmdliner] used by this project's own
+test suite (currently [>= 2.1.1]), so older versions are no longer
+verified by CI.
+
 [cmdliner]: https://github.com/dbuenzli/cmdliner
 
 """

doc/docs/tutorials/getting-started/README.md

@@ -264,7 +264,7 @@ NAME
        my-calculator - A simple calculator.
 
 SYNOPSIS
-       my-calculator [--op=OP] [--verbose] [OPTION]… a b
+       my-calculator --op=OP [--verbose] [OPTION]… a b
 
 ARGUMENTS
        a (required)
@@ -308,19 +308,17 @@ Additionally, we don't need to worry about handling invalid usages, this is done
 
 ```sh
 $ ./my-calculator --op=not-found 1 2.5
+Usage: my-calculator [--help] --op=OP [--verbose] [OPTION]… a b
 my-calculator: option '--op': invalid value 'not-found', expected either
                'add' or 'mul'
-Usage: my-calculator [--op=OP] [--verbose] [OPTION]… a b
-Try 'my-calculator --help' for more information.
 [124]
 ```
 
 ```sh
 $ ./my-calculator --op=add true 2.5
+Usage: my-calculator [--help] --op=OP [--verbose] [OPTION]… a b
 my-calculator: a argument: invalid value 'true', expected a floating point
                number
-Usage: my-calculator [--op=OP] [--verbose] [OPTION]… a b
-Try 'my-calculator --help' for more information.
 [124]
 ```
 

dune

@@ -1,4 +1,9 @@
 (env
  (dev
   (odoc
-   (warnings fatal))))
+   (warnings fatal))
+  ;; Since cmdliner 2.0, error and help messages use ANSI-styled. This makes our
+  ;; expect and cram tests depend on the ambient environment of whoever runs
+  ;; them. Force plain output so corrected files are stable across environments.
+  (env-vars
+   (NO_COLOR "1"))))

dune-project

@@ -101,9 +101,7 @@
   (cmdlang-to-cmdliner
    (= :version))
   (cmdliner
-   (and
-    (>= 1.3.0)
-    (< 2.0)))
+   (>= 2.1.1))
   (core
    (>= v0.17))
   (core_unix
@@ -159,9 +157,7 @@
   (cmdlang-to-cmdliner
    (= :version))
   (cmdliner
-   (and
-    (>= 1.3.0)
-    (< 2.0)))
+   (>= 2.1.1))
   conf-jq
   (dune-build-info
    (>= 3.17))

src/cmdlang-to-cmdliner/translate.mli

@@ -4,7 +4,13 @@
 (*_  SPDX-License-Identifier: MIT                                                 *)
 (*_********************************************************************************)
 
-(** Translate cmdlang parsers to cmdliner. *)
+(** Translate cmdlang parsers to cmdliner.
+
+    This library aims to remain as compatible as possible with older
+    versions of [cmdliner], down to [1.3]. However, it is only actively
+    tested against the version of [cmdliner] used by this project's own test
+    suite (currently [>= 2.1.1]), so older versions are no longer verified
+    by CI. *)
 
 (** {1 Param} *)
 

test/cram/basic.t

@@ -190,9 +190,8 @@ flags.
   [124]
 
   $ ./main_cmdliner.exe basic int -13
-  ./main_cmdliner.exe: unknown option '-1'.
-  Usage: ./main_cmdliner.exe basic int [OPTION]… INT
-  Try './main_cmdliner.exe basic int --help' or './main_cmdliner.exe --help' for more information.
+  Usage: ./main_cmdliner.exe basic int [--help] [OPTION]… INT
+  ./main_cmdliner.exe: unknown option '-1'
   [124]
 
   $ ./main_stdlib_runner.exe basic int -13
@@ -315,9 +314,8 @@ flags.
   [124]
 
   $ ./main_cmdliner.exe basic float -13.8
-  ./main_cmdliner.exe: unknown option '-1'.
-  Usage: ./main_cmdliner.exe basic float [OPTION]… FLOAT
-  Try './main_cmdliner.exe basic float --help' or './main_cmdliner.exe --help' for more information.
+  Usage: ./main_cmdliner.exe basic float [--help] [OPTION]… FLOAT
+  ./main_cmdliner.exe: unknown option '-1'
   [124]
 
   $ ./main_stdlib_runner.exe basic float -13.8
@@ -454,10 +452,9 @@ And run it too.
   [124]
 
   $ ./main_cmdliner.exe basic bool True
-  ./main_cmdliner.exe: BOOL argument: invalid value 'True', either 'true' or
-                       'false'
-  Usage: ./main_cmdliner.exe basic bool [OPTION]… BOOL
-  Try './main_cmdliner.exe basic bool --help' or './main_cmdliner.exe --help' for more information.
+  Usage: ./main_cmdliner.exe basic bool [--help] [OPTION]… BOOL
+  ./main_cmdliner.exe: BOOL argument: invalid value 'True', expected either
+                       'true' or 'false'
   [124]
 
   $ ./main_stdlib_runner.exe basic bool True
@@ -497,10 +494,9 @@ Invalid entry.
   [124]
 
   $ ./main_cmdliner.exe basic bool Not_a_bool
-  ./main_cmdliner.exe: BOOL argument: invalid value 'Not_a_bool', either 'true'
-                       or 'false'
-  Usage: ./main_cmdliner.exe basic bool [OPTION]… BOOL
-  Try './main_cmdliner.exe basic bool --help' or './main_cmdliner.exe --help' for more information.
+  Usage: ./main_cmdliner.exe basic bool [--help] [OPTION]… BOOL
+  ./main_cmdliner.exe: BOOL argument: invalid value 'Not_a_bool', expected
+                       either 'true' or 'false'
   [124]
 
   $ ./main_stdlib_runner.exe basic bool Not_a_bool
@@ -595,9 +591,8 @@ And run it too.
   foo.txt
 
   $ ./main_cmdliner.exe basic file foo.txt
+  Usage: ./main_cmdliner.exe basic file [--help] [OPTION]… FILE
   ./main_cmdliner.exe: FILE argument: no 'foo.txt' file or directory
-  Usage: ./main_cmdliner.exe basic file [OPTION]… FILE
-  Try './main_cmdliner.exe basic file --help' or './main_cmdliner.exe --help' for more information.
   [124]
 
   $ ./main_stdlib_runner.exe basic file foo.txt
@@ -631,9 +626,8 @@ Same when the file actually exists
   /bogus/bar
 
   $ ./main_cmdliner.exe basic file /bogus/bar
+  Usage: ./main_cmdliner.exe basic file [--help] [OPTION]… FILE
   ./main_cmdliner.exe: FILE argument: no '/bogus/bar' file or directory
-  Usage: ./main_cmdliner.exe basic file [OPTION]… FILE
-  Try './main_cmdliner.exe basic file --help' or './main_cmdliner.exe --help' for more information.
   [124]
 
   $ ./main_stdlib_runner.exe basic file /bogus/bar

test/cram/enum.t

@@ -138,18 +138,17 @@ Cmdliner.
   red
 
   $ ./main_cmdliner.exe enum pos INVALID
+  Usage: ./main_cmdliner.exe enum pos [--help] [OPTION]… COLOR
   ./main_cmdliner.exe: COLOR argument: invalid value 'INVALID', expected one of
                        'red', 'green' or 'blue'
-  Usage: ./main_cmdliner.exe enum pos [OPTION]… COLOR
-  Try './main_cmdliner.exe enum pos --help' or './main_cmdliner.exe --help' for more information.
   [124]
 
   $ ./main_cmdliner.exe enum named --help=plain
   NAME
          ./main_cmdliner.exe-enum-named - Print color.
 
   SYNOPSIS
-         ./main_cmdliner.exe enum named [--color=COLOR] [OPTION]…
+         ./main_cmdliner.exe enum named --color=COLOR [OPTION]…
 
   OPTIONS
          --color=COLOR (required)
@@ -183,10 +182,9 @@ Cmdliner.
   red
 
   $ ./main_cmdliner.exe enum named --color INVALID
+  Usage: ./main_cmdliner.exe enum named [--help] --color=COLOR [OPTION]…
   ./main_cmdliner.exe: option '--color': invalid value 'INVALID', expected one
                        of 'red', 'green' or 'blue'
-  Usage: ./main_cmdliner.exe enum named [--color=COLOR] [OPTION]…
-  Try './main_cmdliner.exe enum named --help' or './main_cmdliner.exe --help' for more information.
   [124]
 
 Stdlib runner.

test/cram/group.t

@@ -133,9 +133,9 @@ What happens when that group is run:
   [1]
 
   $ ./main_cmdliner.exe basic
-  ./main_cmdliner.exe: required COMMAND name is missing, must be one of 'bool', 'file', 'float', 'int' or 'string'.
-  Usage: ./main_cmdliner.exe basic COMMAND …
-  Try './main_cmdliner.exe basic --help' or './main_cmdliner.exe --help' for more information.
+  Usage: ./main_cmdliner.exe basic [--help] COMMAND …
+  ./main_cmdliner.exe: required COMMAND name is missing, must be one of 'bool',
+                       'file', 'float', 'int' or 'string'
   [124]
 
   $ ./main_stdlib_runner.exe basic
@@ -266,9 +266,8 @@ What happens when that group with a default is run:
   [124]
 
   $ ./main_cmdliner.exe group
+  Usage: ./main_cmdliner.exe group [--help] [COMMAND] …
   ./main_cmdliner.exe: required argument STRING is missing
-  Usage: ./main_cmdliner.exe group [COMMAND] …
-  Try './main_cmdliner.exe group --help' or './main_cmdliner.exe --help' for more information.
   [124]
 
   $ ./main_stdlib_runner.exe group
@@ -299,9 +298,8 @@ With cmdliner, this particular default command is not supported because the
 positional argument is interpreted as an unknown command:
 
   $ ./main_cmdliner.exe group World
-  ./main_cmdliner.exe: unknown command 'World', must be 'a'.
-  Usage: ./main_cmdliner.exe group [COMMAND] …
-  Try './main_cmdliner.exe group --help' or './main_cmdliner.exe --help' for more information.
+  Usage: ./main_cmdliner.exe group [--help] [COMMAND] …
+  ./main_cmdliner.exe: unknown command 'World'. Must be 'a'
   [124]
 
 The recommended way to handle this in cmdliner is to add the special '--' token, such as in:
@@ -345,9 +343,9 @@ default, when it is invoked with an invalid subcommand name.
   [124]
 
   $ ./main_cmdliner.exe invalid
-  ./main_cmdliner.exe: unknown command 'invalid', must be one of 'basic', 'doc', 'enum', 'flags', 'group', 'named' or 'return'.
-  Usage: ./main_cmdliner.exe COMMAND …
-  Try './main_cmdliner.exe --help' for more information.
+  Usage: ./main_cmdliner.exe [--help] COMMAND …
+  ./main_cmdliner.exe: unknown command 'invalid'. Must be one of 'basic',
+                       'doc', 'enum', 'flags', 'group', 'named' or 'return'
   [124]
 
   $ ./main_stdlib_runner.exe invalid

test/cram/named-with-default.t

@@ -217,9 +217,9 @@ functions or parsers generated from modules with utils.
   [124]
 
   $ ./main_cmdliner.exe named with-default create --who=C
+  Usage: ./main_cmdliner.exe named with-default create [--help] [--who=(A|B)]
+         [OPTION]…
   ./main_cmdliner.exe: option '--who': "C": invalid E.t
-  Usage: ./main_cmdliner.exe named with-default create [--who=(A|B)] [OPTION]…
-  Try './main_cmdliner.exe named with-default create --help' or './main_cmdliner.exe --help' for more information.
   [124]
 
   $ ./main_stdlib_runner.exe named with-default create --who C
@@ -330,11 +330,11 @@ Named-with-default with a stringable parameter.
          Named_with_default__stringable
 
   SYNOPSIS
-         ./main_cmdliner.exe named with-default stringable [--who=VAL]
+         ./main_cmdliner.exe named with-default stringable [--who=VALUE]
          [OPTION]…
 
   OPTIONS
-         --who=VAL (absent=my-id)
+         --who=VALUE (absent=my-id)
              identifier.
 
   COMMON OPTIONS
@@ -413,10 +413,10 @@ Named-with-default with a validated string parameter.
          Named_with_default__validated
 
   SYNOPSIS
-         ./main_cmdliner.exe named with-default validated [--who=VAL] [OPTION]…
+         ./main_cmdliner.exe named with-default validated [--who=VALUE] [OPTION]…
 
   OPTIONS
-         --who=VAL (absent=0000)
+         --who=VALUE (absent=0000)
              4 letters alphanumerical identifier.
 
   COMMON OPTIONS
@@ -490,10 +490,10 @@ Invalid entry for the validated string parameter.
   [124]
 
   $ ./main_cmdliner.exe named with-default validated --who foo
+  Usage: ./main_cmdliner.exe named with-default validated [--help]
+         [--who=VALUE] [OPTION]…
   ./main_cmdliner.exe: option '--who': "foo": invalid 4 letters alphanumerical
                        identifier
-  Usage: ./main_cmdliner.exe named with-default validated [--who=VAL] [OPTION]…
-  Try './main_cmdliner.exe named with-default validated --help' or './main_cmdliner.exe --help' for more information.
   [124]
 
   $ ./main_stdlib_runner.exe named with-default validated --who foo
@@ -614,9 +614,9 @@ Named-with-default with a comma-separated string parameter.
   [124]
 
   $ ./main_cmdliner.exe named with-default pos-int -x blah
+  Usage: ./main_cmdliner.exe named with-default pos-int [--help] [-x X]
+         [OPTION]…
   ./main_cmdliner.exe: option '-x': Not an int
-  Usage: ./main_cmdliner.exe named with-default pos-int [-x X] [OPTION]…
-  Try './main_cmdliner.exe named with-default pos-int --help' or './main_cmdliner.exe --help' for more information.
   [124]
 
   $ ./main_stdlib_runner.exe named with-default pos-int -x blah
@@ -652,9 +652,9 @@ Named-with-default with a comma-separated string parameter.
   [124]
 
   $ ./main_cmdliner.exe named with-default pos-int -x 0
+  Usage: ./main_cmdliner.exe named with-default pos-int [--help] [-x X]
+         [OPTION]…
   ./main_cmdliner.exe: option '-x': Strictly positive int expected
-  Usage: ./main_cmdliner.exe named with-default pos-int [-x X] [OPTION]…
-  Try './main_cmdliner.exe named with-default pos-int --help' or './main_cmdliner.exe --help' for more information.
   [124]
 
   $ ./main_stdlib_runner.exe named with-default pos-int -x 0