west: flash/debug: try to make --context more prominent
I keep seeing people miss the --context option in the "west flash
--help" output.
This option is very important for understanding the runner-specific
options and state, and missing it means people get confused about what
west flash, debug, etc. can do and are doing.
Try to avoid this problem by adding a big fat banner about the
omission of runner-specific options in the main help output, and
provide more hints about how to use --context.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
diff --git a/scripts/west_commands/run_common.py b/scripts/west_commands/run_common.py
index c89ee62..73a021f 100644
--- a/scripts/west_commands/run_common.py
+++ b/scripts/west_commands/run_common.py
@@ -85,9 +85,6 @@
# Remember to update scripts/west-completion.bash if you add or remove
# flags
- parser.add_argument('-H', '--context', action='store_true',
- help='print build directory specific help')
-
group = parser.add_argument_group('general options',
FIND_BUILD_DIR_DESCRIPTION)
@@ -103,12 +100,27 @@
help='do not refresh cmake dependencies first')
group = parser.add_argument_group(
- 'runner configuration overrides',
+ 'runner configuration',
textwrap.dedent(f'''\
- Run "west {command.name} --context" for --build-dir specific options.
- Not all runners respect --elf-file / --hex-file / --bin-file, nor use
- gdb or openocd.'''))
+ ===================================================================
+ IMPORTANT:
+ Individual runners support additional options not printed here.
+ ===================================================================
+ Run "west {command.name} --context" for runner-specific options.
+
+ If a build directory is found, --context also prints per-runner
+ settings found in that build directory's runners.yaml file.
+
+ Use "west {command.name} --context -r RUNNER" to limit output to a
+ specific RUNNER.
+
+ Some runner settings also can be overridden with options like
+ --hex-file. However, this depends on the runner: not all runners
+ respect --elf-file / --hex-file / --bin-file, nor use gdb or openocd,
+ etc.'''))
+ group.add_argument('-H', '--context', action='store_true',
+ help='print runner- and build-specific help')
# Options used to override RunnerConfig values in runners.yaml.
# TODO: is this actually useful?
group.add_argument('--board-dir', metavar='DIR', help='board directory')
