commands.json

commands.json files define how subcommands are executed by the ./wpt command. wpt searches all command.json files under the top directory and sets up subcommands from these JSON files. A typical commands.json would look like the following:

{
  "foo": {
    "path": "foo.py",
    "script": "run",
    "parser": "get_parser",
    "help": "Run foo"
  },
  "bar": {
    "path": "bar.py",
    "script": "run",
    "virtualenv": true,
    "requirements": [
      "requirements.txt"
    ]
  }
}

Each key of the top level object defines a name of a subcommand, and its value (a properties object) specifies how the subcommand is executed. Each properties object must contain path and script fields and may contain additional fields. All paths are relative to the commands.json.

path

The path to a Python script that implements the subcommand.

script

The name of a function that is used as the entry point of the subcommand.

parser

The name of a function that creates an argparse parser for the subcommand.

parse_known

When True, parse_known_args() is used instead of parse_args() for the subcommand. Default to False.

help

Brief description of the subcommand.

virtualenv

When True, the subcommand is executed with a virtualenv environment. Default to True.

install

A list of strings where each string represents a requirement object. These requirements are installed into the virtualenv environment before running the subcommand. virtualenv must be true when this field is set.

requirements

A list of paths where each path specifies a requirements.txt. All requirements listed in these files are installed into the virtualenv environment before running the subcommand. virtualenv must be true when this field is set.

conditional_requirements

A key-value object. Each key represents a condition, and value represents additional requirements when the condition is met. The requirements have the same format as requirements. Currently “commandline_flag” is the only supported key. “commandline_flag” is used to specify requirements needed for a certain command line flag of the subcommand. For example, given the following commands.json:

"baz": {
  "path": "baz.py",
  "script": "run",
  "virtualenv": true,
  "conditional_requirements": {
    "commandline_flag": {
      "enable_feature1": [
        "requirements_feature1.txt"
      ]
    }
  }
}

Requirements in requirements_features1.txt are installed only when --enable-feature1 is specified to ./wpt baz.