README.md
1# idf.py extensions
2Python modules (subdirectories and files) in this directory named `[your_extension]_ext` will be loaded as idf.py extensions.
3If you want to provide extra extensions just provide `;` separated list of directories with extensions in `IDF_EXTRA_ACTIONS_PATH`. Extensions will be loaded in alphanumeric order.
4Command line arguments parsing and extension mechanism is implemented on top of [Click](https://click.palletsprojects.com/en/5.x/) (versions >=5.0 are supported).
5
6They should define a function `action_extensions(base_actions, project_path)` where:
7
8- base_actions - dictionary with actions that are already available for idf.py
9- project_path - working dir, may be defaulted to `os.getcwd()`
10
11This function have to return a dict with 3 possible keys:
12
13```python
14{
15 # Additional options that will be available from id
16 "global_options": [{
17 "names": ["--option-name"],
18 "help": "Help for option --option-name.",
19 }],
20 # List of functions that will have access to full app context, and can mangle with arguments
21 "global_action_callbacks": [global_callback],
22 # Additional subcommands for idf.py
23 "actions": {
24 "subcommand_name": {
25 "callback": subcommand_callback,
26 "help": "Help for subcommand.",
27 },
28 },
29}
30```
31
32Where function `global_callback(ctx, global_args, tasks)` accepts 3 arguments:
33
34- ctx - [Click context](https://click.palletsprojects.com/en/5.x/api/#context)
35- global_args - dictionary of all available global arguments
36- tasks - list of Task objects
37
38And `subcommand_callback(subcommand_name, ctx, args)` accepts 3 arguments:
39
40- subcommand_name - name of subcommand
41- ctx - [Click context](https://click.palletsprojects.com/en/5.x/api/#context)
42- args - list of command's arguments
43
