# qiBuild documentation

# Parsing command line arguments

Before reading this section, please make sure you have read the Extending qiBuild actions tutorial.

Briefly, you should create a file named `spam.py` looking like:

    """Add some eggs !"""

    import qisys.parsers

    def configure_parser(parser):
        """Configure parser for this action """
        qisys.parsers.default_parser(parser)
        parser.add_argument("--num-eggs",
          help="Number of eggs to add",
          type=int)
        parser.set_defaults(
          num_eggs=3)

    def do(args):
      """Main entry point"""
      qisys.ui.info("adding %i eggs" % args.num_eggs)

Now lets have a look of what happens when you type:

    $ qibuild spam --num-eggs=42

You first go through qibuild script, in `bin/qibuild`

You will see it uses :

    modules = qisys.script.action_modules_from_package("qibuild.actions")
    qisys.script.root_command_main("qibuild", parser, modules)

The first line will look for every Python module in the `qibuild.actions` package that contains a `do()` and a `configure_args` methods.

The second line will do the main parsing.

Note that the last argument is simply a list of modules.

So if you ever wanted to add an action outside `qibuild.actions` package, you could do:

    import spam
    qisys.script.root_command_main("qibuild", parser, modules + [spam])

So what does the `root_command_main` do?

You can see it takes a `parser` object as argument.

You should call this function with an `argparse.ArgumentParser` object.

The parser will then be updated.

    parser = argparse.ArgumentParser()
    qisys.script.root_command_main("qibuild", parser)

Basically, we will call:

    subparsers = parser.add_subparsers(dest="action", title="actions")
    action_parser = subparsers.add_parser("spam")
    spam.configure_parser(action_parser)

for each module in the list.

Note how we format the help looking using `module.__doc__`

This means that `spam.py` contains everything to handle the parsing:

- The documentation of the action is simply the docstring of the module
- Specific arguments are added using the `configure_parser` function of the module

Thus, everything is put in one place, and the `--help` output is always correct.

Changelog CMake index Python index Index