west: add example west command

Add a working example for how to implement a west command within the
user's manifest repository. There is documentation for this, but we
should have some working code in here just to make life easier for
people.

Signed-off-by: Martí Bolívar <[email protected]>

Author: mbolivar-nordic

.gitignore

@@ -8,3 +8,5 @@
 
 # build
 /build*
+
+__pycache__/

README.md

@@ -11,6 +11,7 @@ applications. Some of the features demonstrated in this example are:
 - Custom [devicetree bindings][bindings]
 - Out-of-tree [drivers][drivers]
 - Example CI configuration (using Github Actions)
+- Custom [west extension][west_ext]
 
 This repository is versioned together with the [Zephyr main tree][zephyr]. This
 means that every time that Zephyr is tagged, this repository is tagged as well
@@ -26,6 +27,7 @@ point to the development branch of Zephyr, also `main`.
 [bindings]: https://docs.zephyrproject.org/latest/guides/dts/bindings.html
 [drivers]: https://docs.zephyrproject.org/latest/reference/drivers/index.html
 [zephyr]: https://github.com/zephyrproject-rtos/zephyr
+[west_ext]: https://docs.zephyrproject.org/latest/develop/west/extensions.html
 
 ## Getting Started
 

scripts/example_west_command.py

@@ -0,0 +1,49 @@
+# Copyright (c) 2019 Foundries.io
+# Copyright (c) 2022 Nordic Semiconductor ASA
+# SPDX-License-Identifier: Apache-2.0
+
+'''example_west_command.py
+
+Example of a west extension in the example-application repository.'''
+
+from west.commands import WestCommand  # your extension must subclass this
+from west import log                   # use this for user output
+
+class ExampleWestCommand(WestCommand):
+
+    def __init__(self):
+        super().__init__(
+            'example-west-command',               # gets stored as self.name
+            'an example west extension command',  # self.help
+            # self.description:
+            '''\
+A multi-line description of example-west-command.
+
+You can split this up into multiple paragraphs and they'll get
+reflowed for you. You can also pass
+formatter_class=argparse.RawDescriptionHelpFormatter when calling
+parser_adder.add_parser() below if you want to keep your line
+endings.''')
+
+    def do_add_parser(self, parser_adder):
+        # This is a bit of boilerplate, which allows you full control over the
+        # type of argparse handling you want. The "parser_adder" argument is
+        # the return value of an argparse.ArgumentParser.add_subparsers() call.
+        parser = parser_adder.add_parser(self.name,
+                                         help=self.help,
+                                         description=self.description)
+
+        # Add some example options using the standard argparse module API.
+        parser.add_argument('-o', '--optional', help='an optional argument')
+        parser.add_argument('required', help='a required argument')
+
+        return parser           # gets stored as self.parser
+
+    def do_run(self, args, unknown_args):
+        # This gets called when the user runs the command, e.g.:
+        #
+        #   $ west my-command-name -o FOO BAR
+        #   --optional is FOO
+        #   required is BAR
+        log.inf('--optional is', args.optional)
+        log.inf('required is', args.required)

scripts/west-commands.yml

@@ -0,0 +1,6 @@
+west-commands:
+  - file: scripts/example_west_command.py
+    commands:
+      - name: example-west-command
+        class: ExampleWestCommand
+        help: an example west extension command

west.yml

@@ -4,6 +4,7 @@
 manifest:
   self:
     path: example-application
+    west-commands: scripts/west-commands.yml
 
   remotes:
     - name: zephyrproject-rtos