1commands.json
2=============
3
4:code:`commands.json` files define how subcommands are executed by the
5:code:`./wpt` command. :code:`wpt` searches all command.json files under the top
6directory and sets up subcommands from these JSON files. A typical commands.json
7would look like the following::
8
9  {
10    "foo": {
11      "path": "foo.py",
12      "script": "run",
13      "parser": "get_parser",
14      "help": "Run foo"
15    },
16    "bar": {
17      "path": "bar.py",
18      "script": "run",
19      "virtualenv": true,
20      "requirements": [
21        "requirements.txt"
22      ]
23    }
24  }
25
26Each key of the top level object defines a name of a subcommand, and its value
27(a properties object) specifies how the subcommand is executed. Each properties
28object must contain :code:`path` and :code:`script` fields and may contain
29additional fields. All paths are relative to the commands.json.
30
31:code:`path`
32  The path to a Python script that implements the subcommand.
33
34:code:`script`
35  The name of a function that is used as the entry point of the subcommand.
36
37:code:`parser`
38  The name of a function that creates an argparse parser for the subcommand.
39
40:code:`parse_known`
41  When True, `parse_known_args() <https://docs.python.org/3/library/argparse.html#argparse.ArgumentParser.parse_known_args>`_
42  is used instead of parse_args() for the subcommand. Default to False.
43
44:code:`help`
45  Brief description of the subcommand.
46
47:code:`virtualenv`
48  When True, the subcommand is executed with a virtualenv environment. Default
49  to True.
50
51:code:`install`
52  A list of strings where each string represents a
53  `requirement object <https://setuptools.readthedocs.io/en/latest/pkg_resources.html#requirement-objects>`_.
54  These requirements are installed into the virtualenv environment before
55  running the subcommand. :code:`virtualenv` must be true when this field is
56  set.
57
58:code:`requirements`
59  A list of paths where each path specifies a requirements.txt. All requirements
60  listed in these files are installed into the virtualenv environment before
61  running the subcommand. :code:`virtualenv` must be true when this field is
62  set.
63
64:code:`conditional_requirements`
65  A key-value object. Each key represents a condition, and value represents
66  additional requirements when the condition is met. The requirements have the
67  same format as :code:`requirements`. Currently "commandline_flag" is the only
68  supported key. "commandline_flag" is used to specify requirements needed for a
69  certain command line flag of the subcommand. For example, given the following
70  commands.json::
71
72    "baz": {
73      "path": "baz.py",
74      "script": "run",
75      "virtualenv": true,
76      "conditional_requirements": {
77        "commandline_flag": {
78          "enable_feature1": [
79            "requirements_feature1.txt"
80          ]
81        }
82      }
83    }
84
85  Requirements in :code:`requirements_features1.txt` are installed only when
86  :code:`--enable-feature1` is specified to :code:`./wpt baz`.
87