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.
--HG--
extra : rebase_source : 12783c69027989ac031d29e4ecbc1ee2f465ffa4
extra : histedit_source : 4283c6cdecc4de8aa7636d0c4cc566daf5142b50
An upcoming patch will reuse this code. Split it out into its own
function.
--HG--
extra : rebase_source : 2057266a1ed4d86b1ca857712cd279bdfbd32148
extra : histedit_source : 8f2b7ec06e5b72ab08586902c51c3025a53259e6
With this patch, we now have the ability to declare mach sub-commands.
Subsequent patches will implement dispatching for sub-commands.
--HG--
extra : rebase_source : 32a672ff3ba7a1a1c8c27dff3fe657dec08e3569
extra : histedit_source : 2bb2c27ae0e2dab052a6ef93b0a70f488f8cd56e
We will soon have proper sub-commands. Let's fix function names.
--HG--
extra : rebase_source : 1cb0c008ecc0d2159dd799e76adad4892d65f119
extra : histedit_source : 9472b2d2609224b011eca04385cf9d5a49986864
mach conditions are implemented elsewhere. This comment can die.
--HG--
extra : rebase_source : c956d5af7858d997a1f49f3b24bb54e5f8a52240
extra : histedit_source : 76b8155b12ab0ea86e16e807b1c6f691cb8f3640
Documentation was referencing sub commands. The proper terminology is
"command."
--HG--
extra : rebase_source : aa2fc73c6141850109324fd5299491e49ef29e91
extra : histedit_source : da075bea5a36a9de81527d93a9fc751cd6cae9b2
There were a few parts of the docs that were linking to Python types
incorrectly. Let's fix that.
--HG--
extra : rebase_source : 374be660084727eba1ce9181c2abf384f40eeb82
extra : histedit_source : bfa8de9b7a277666d92ebe71cd64ffed96628518
The main mach docs page is a bit long. Let's split it into multiple
articles to increase readability going forward.
--HG--
rename : python/mach/docs/index.rst => python/mach/docs/commands.rst
rename : python/mach/docs/index.rst => python/mach/docs/driver.rst
rename : python/mach/docs/index.rst => python/mach/docs/logging.rst
extra : rebase_source : 484d60327568333fcb0069e1f3444dc6db4322c0
extra : histedit_source : 18d09ac2e2e93565661763b6567f7a46226735f5
Now that mach's docs are part of a proper Sphinx install, link to
Python type docs. While we're here, we also clean up formatting of code
samples.
--HG--
extra : rebase_source : 974337316dc87c04aca79a9e4a0d464490e5cdd4
extra : histedit_source : db87e8e5cb7c9c1969fd89e58c39623862684a6a
mach has restructured text documentation. Let's expose it to the in-tree
Sphinx config so we can increase visibility of the documentation.
--HG--
rename : python/mach/README.rst => python/mach/docs/index.rst
extra : rebase_source : 68a08bebaa5b99ca39e250fa1ed60ca4d7d0af68
extra : histedit_source : 6afda2fece486547192c1c8eba97a2474e3d99c1
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.
--HG--
extra : rebase_source : 5ebfa7f5fd89f96dac5f7cb035ab520c63b32e55
extra : amend_source : c53c988763c328020b49aa5c6245df685b6f30bc
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.
--HG--
extra : rebase_source : aeb6c99a945eaff32cf86fa481d03c0c8dee593a
extra : amend_source : f1e29385bf8ca8ac250a04f81e7e955c4152b476
test_entry_point.py is not enabled because the test fails. This is
tracked by bug 958196.
--HG--
extra : rebase_source : 1f326a9bbd7ee0e8e12ff33f49d8484cc244c42d
The test changes and setup.py are NPOTB. base.py and main.py
added a new feature to declare global arguments.
--HG--
extra : rebase_source : 4b14487d9aff98247464e0b0c08b4fc5cfbd862a
