Mach has special handling for remainder arguments which previously
only worked with the decoration form. Extend this to also work when
a command passes in an explict parser
Without this, we throw UnrecognizedArgumentError when running commands
such as `./mach mochitest-plain test`, which causes an error message
such as the below to be emitted:
It looks like you passed an unrecognized argument into mach.
The mochitest-plain command does not accept the arguments: test
This patch will fix the above command to instead print the corresponding
deprecation message.
Simplify construction of mach's MethodHandler instances by by passing in
our new rich type that holds all command metadata.
While we are here, kill the docstring argument, as it can be computed
easily inside MethodHandler.__init__.
Up to this point, mach command metadata has been stored in tuples.
Initially, things weren't so bad. But they have evolved into tuples with
many elements. Adding new attributes is cumbersome. Let's restructure
the code to capture metadata in a dedicated class.
Before, there existed a separate attribute on the @Command or
@SubCommand decorated method for each mach decorator: @Command,
@CommandArgument, @CommandArgumentGroup. With the magic of __ior__,
we can now capture all metadata on a single type. This simplies
processing, as we now only look at a single attribute on methods:
_mach_command.
Before, we used separate attributes to distinguish between mach commands
and mach sub-commands. Now that we have a type that can hold all data,
we combine things into the _mach_command attribute and look for the
presence of the "subcommand" attribute on this type to identify
sub-commands.
`mach help <command>` currently only displays a brief description of the
command along with its arguments. Sometimes more detailed help text is
needed.
With this commit, the docstrings of mach command handlers will appear in
the output of `mach help <command>` if they are defined.
I've implemented basic docstrings for the three flavors of mach commands
(normal command, main subcommand, subcommand) to demonstate things work.
My hope is others will start to fill in docstrings once this feature
lands so the output for `mach help` can serve as a better learning guide
for new contributors.
Previously, we raised errors attempting to register a mach sub-command
if the parent command was not defined on the Registrar. This broke B2G
because its mach command Registrar imposes restrictions on which
commands it exposes. Commands there were not getting registered on the
Registrar, leading mach to give a false positive that the parent command
was never defined.
We change the verification logic to take present but unregistered
commands into consideration and to skip registering sub-commands if the
parent isn't present in the Registrar.
The previous debugger was setting a breakpoint in the mach dispatcher.
This required users to step into the main function to be called into.
Using pdb.runcall(), the debugger starts at the first line in the
executed command, which is far more useful.
terminal.py had an ambiguous |import logging| that was importing
mach.logging from Sphinx. We fix it.
There was also a poorly formed link in the mach commands documentation.
We fix it.
People often seek to learn how mach commands work. A common way to do
this is to launch a debugger and step through the code as it is
executing. But this requires someone to first find and modify the mach
command. This involves overhead.
This patch adds a global --debug-command argument to mach. When present,
we launch an interactive debugger right before command dispatch. This
allows people to easily enter a debugger to see what mach commands are
doing, hopefully lowering the barrier to understanding and contributing.
The reason to use '+' prefixing was to distinguish between options to the
mach command itself, and options that are passed down to whatever the
command does (like mach run passing down args to the built application).
That makes things unnecessarily awkward, and quite non-standard.
Instead, use standard '-' prefixing, and pass all the unknown arguments
down. If there is overlap between the known arguments and arguments supported
by the underlying tool (like -remote when using mach run), it is possible to
use '--' to mark all following arguments as being targetted at the underlying
tool.
For instance:
mach run -- -remote something
would run
firefox -remote something
while
mach run -remote something
would run
firefox something
As allow_all_arguments is redundant with the presence of a argparse.REMAINDER
CommandArgument, allow_all_arguments is removed. The only mach command with a
argparse.REMAINDER CommandArgument without allow_all_arguments was "mach dmd",
and it did so because it didn't want to use '+' prefixes.
While I was here, I removed the try..except in favor of failing fast.
Before, we were only making cosmetic changes. Now, we actually need the
group for mach to work. It makes sense to stop ignoring errors.
This fixes a regression from d53d1c6cdf13 / bug 951733.
