No way to get help for pub subcommands with dart pub

[mit-mit]

Pub has many sub-commands. Getting help for this is a fairly common use case. However. dart help pub publish fails:

mit-macbookpro4:~ mit$ dart help pub publish
Command "dart pub" does not expect a subcommand.

Usage: dart pub [arguments]

Note that this does seem to work for other commands, e.g. compile:

mit-macbookpro4:~ mit$ dart help compile exe
Compile Dart to a self-contained executable

Usage: dart compile exe [arguments] <dart entry point>

[mit-mit]

cc @jwren @jonasfj

[jonasfj]

dart pub help publish is likely to work. We could do a work around for this. Otherwise, I would expect this to resolve if we manage to get pub embedded in dartdev.

[mit-mit]

Note that this does work:

mit-macbookpro4:flutter mit$ dart help compile exe
Compile Dart to a self-contained executable

Usage: dart compile exe [arguments] <dart entry point>
-h, --help                          Print this usage information.
-o, --output                        Write the output to <file name>.
                                    This can be an absolute or reletive path.
-D, --define=<key=value>            Set values of environment variables. To specify multiple variables, use multiple options or use commas to separate key-value pairs.
                                    E.g.: dart compile exe -Da=1,b=2 main.dart
    --enable-asserts                Enable assert statements.
-p, --packages=<path>               Get package locations from the specified file instead of .packages. <path> can be relative or absolute.
                                    E.g.: dart compile exe --packages=/tmp/pkgs main.dart
-S, --save-debugging-info=<path>    Remove debugging information from the output and save it separately to the specified file. <path> can be relative or absolute.

[mit-mit]

This is caused by the argument parsers for some older commands (like pub) being shallow wrappers in dart CLI that call out to the existing commands. Over time as we discontinue the older commands, we can move all of the command and argument parsing into the dart CLI.

Also, you can use dart pub publish --help. Would be good to investigate if we can generally support turning dart help foo bar into dart foo bar --help.

[devoncarew]

I believe a solution for this would be to do some light parsing of the command line for the pub subcommand, to convert:

dart help pub publish

(which currently fails), to:

dart pub publish -h

which will succeed.

We'd need to be careful with that parsing and re-writing to ensure that we're correct in various cases; hopefully we can cover that w/ good unit tests.

I don't think this is critical for this milestone however; it's currently a P2 - we may consider moving it out of the milestone as we get closer to the release.

[jwren]

@devoncarew -- yes, thank you for articulating on the bug. I am working on this issue now. With the exception of a Dart VM issue, this is the last dart-cli bug labeled with the September milestone.

[jwren]

@devoncarew @mit-mit

A call to dart help pub publish doesn't invoke any code (such as printUsage in pub.dart)

To re-order the commands, we'd have to intercept modify the runCommand (in dartdev.dart) to match when the user has [..., help, pub, ...] in their arguments. However, even when such a match has been made, there is no way to then have the arguments re-ordered or re-parsed with the current args library: newArgResults is hidden when src/arg_results.dart is exported.

Unfortunately, with the architecture of the args package the most robust way to implement this would be to copy the pub argument parser over like we have done for test. Given this, how important is this for the September release schedule?

[devoncarew]

A call to dart help pub publish doesn't invoke any code (such as printUsage in pub.dart)

To re-order the commands, we'd have to intercept modify the runCommand (in dartdev.dart) to match when the user has [..., help, pub, ...] in their arguments. However, even when such a match has been made, there is no way to then have the arguments re-ordered or re-parsed with the current args library...

Yes, I think the CommandRunner doesn't support re-writing / re-parsing args. Its a specialized use case (but important when you need it).

Have you considered doing the re-write before we pass the list of args to CommandRunner.run()? That would be on or around https://github.com/dart-lang/sdk/blob/master/pkg/dartdev/lib/dartdev.dart#L122. This is were things get tricky - you have to be careful about how you identify something like help pub publish, so you don't mis-identify other invocations.

[jonasfj]

We have work ongoing in dart-lang/pub#2622 to facilitate embedding pub in dartdev, that would alleviate these issues.

[jwren]

PR out at https://dart-review.googlesource.com/c/sdk/+/159341. @jonasfj - if/when embedding is done of pub into dartdev directly, the tests should remain, but the argument parsing in lib/dartdev.dart should be removed.