doc: document --alias-rec and --alias in manpages and generally dune build in docs

[Alizter]

These were added without documentation and can be confusing if users are not familiar with to concept of aliases in dune.

Another note is that perhaps we should wrap some of these cmdliner arguments so that the doc is explicitly required and cannot be omitted.

[raphael-proust]

It's not just that they can be confusing to anyone unfamiliar with aliases, it's that the way they map onto the concept of aliasees is not obvious:

• can you put several --alias options? I'm thinking dune build --alias=fmt --alias=runtest lib/foo
• can you put several paths when you use an --alias option? I'm thinking dune build --alias=fmt src/lib_*
• can you mix-and-match --alias for some dir paths but also give non-alias targets? I'm thinking dune build --alias=fmt src/lib_* src/doc/index.html

[Alizter]

dune build can accept all sorts of targets and aliases that you would like to build. So before if you wrote dune build @fmt my.exe @@utils/bench it would now be possible to write dune build --alias-rec fmt my.exe --alias utils/bench.

So to answer your questions:

can you put several --alias options? I'm thinking dune build --alias=fmt --alias=runtest lib/foo

Yes.

can you put several paths when you use an --alias option? I'm thinking dune build --alias=fmt src/lib_*

Yes.

can you mix-and-match --alias for some dir paths but also give non-alias targets? I'm thinking dune build --alias=fmt src/lib_* src/doc/index.html

Anything that you were writing with @ and @@ before can equivalently be written with --alias-rec and --alias.

So the same questions you asked are also applicable before this feature to the alias @ syntax. I've noticed the documentation is a little light on this concept since it is a CLI one.

The man page for dune build:

SYNOPSIS
       dune build [OPTION]… [TARGET]…

DESCRIPTION
       Targets starting with a @ are interpreted as aliases.

states this.

Let me know if you think my explanation is clear. If it's not, then I will need to think a little harder about how this doc should be written. :)

[raphael-proust]

dune build --alias-rec fmt my.exe --alias utils/bench

oh it doesn't work at all like I expected it to.

What I infer from your example: you can replace the @ part of the argument for --alias-rec (space included). As in your example is equivalent to dune build @fmt my.exe @utils/bench

If that is the case then we can indeed do autocompletion (up to the alias) using the shell's built-in path completion. But we can't do globbing. As in dune build --alias utils/internal_*/bench won't expand correctly bc bench doesn't exist there.

(I thought that the use was dune build --alias=bench utils/ as in "after the --alias parameter, all the paths are to be considered as directories in which to build the alias". This would allow both auto-completion and globbing.)

[Alizter]

Yes, it's a very boring feature. It simply fills the gap where some users, for example on Windows cmd.exe, cannot type commands with @. As a side affect, the parent directory of the alias can be completed, but nothing past that.

For actual completion, something like #12515 would have to happen. In https://preview.dune.build we actually install some completion scripts alongside a nightly release of dune. We are planning to rebrand this to a nightly build.