Upcoming Cmdliner 2.0 changes that need your attention

Community
1

If you are a user of cmdliner note that cmdliner 2.0 – in exchange for auto-completion support – will remove the ability to specify command and options names by unambiguous prefixes according to this plan of action.

If you are horrified by it please chime in on the issue.

19 Likes
2

Other changes you may want to pay attention to is that cmdliner 2.0 will:

  1. Remove deprecated identifiers.
  2. Make the Arg.conv type abstract[1].

If you happen to be walking around your cmdliner usage or making a new cli these days, pay particular attention to 2. as the concrete type has been deprecated since 2017 but sadly it was never possible to make it a visible deprecation (OCaml compiler help us! :man_bowing:).

Note that both 1. and 2. can be resolved now by using cmdliner.1.3.0, there are a few instructions here. It’s no guaranteed, but if you are on opam I may have filed an issue in your issue tracker :waving_hand:.

P.S. I think there’s not a single occurence where I did not eventually regret making a public type concrete.

  1. So that completion behaviours can be defined at that level; aswell as the documentation metavariable which you could specify with Arg.conv constructors for ages but would simply be dropped to return the concrete pair. ↩︎

1 Like
3

The dev repo has now relatively decent completion merged in. The scheme, end-user configuration and how to install completion for your cmdliner based tools are documented here. Do not hesitate to provide feedback about it on the issue tracker before the release.

This can be tested via:

opam pin cmdliner --dev

Reminder. A few packages are known to be broken by 2.0.0 they can be fixed before. I made PRs for odoc, ocp-indent and ocp-index. You can pin these branches if the above pin creates mayhem for you. I think it would be nice if these eco-system tools would not prevent people from using cmdliner 2.0 :–)

As I expected completion support opens new cans of worms for cmdliner which are tracked under the completion label in the issue tracker. Do not hesitate to give a hand on the shell completion script issues, especially if you are familiar with shell completion systems. They are extremely time consuming and brain damaging to work with and tend to make me want to throw out my computer out of the window – this would hinder a cmdliner 2.0 release.

One final notice, I finally jumped the shark and moved to ANSI styled messages (issue, docs) for error and deprection messages – nothing fancy mostly mirrors the way synopses are rendered in manpages, a bit of red on error key words and yellow for the token deprecated.

As I need to switch to something else right now I expect to make the release at most by end of may, possibly before.

1 Like