From 6e4c2b9be9c15daefc6fab2f4bcc0622557d92e8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mart=C3=AD=20Bol=C3=ADvar?= Date: Thu, 25 Jun 2020 12:58:58 -0700 Subject: [PATCH] scripts: clean up west build/flash/debug help MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Just changes to the west help output; no functional changes expected. Make option descriptions lowercase to match the argparse module's conventions. When multiple sentences are required, move them to parser prolog/epilog or argument group description sections. Clarify some points that have confused multiple people. Signed-off-by: Martí Bolívar --- scripts/west_commands/build.py | 66 ++++++++++++---------- scripts/west_commands/build_helpers.py | 2 +- scripts/west_commands/debug.py | 11 ++-- scripts/west_commands/flash.py | 5 +- scripts/west_commands/run_common.py | 51 ++++++++--------- scripts/west_commands/zephyr_ext_common.py | 2 +- 6 files changed, 70 insertions(+), 67 deletions(-) diff --git a/scripts/west_commands/build.py b/scripts/west_commands/build.py index 763d3846471..0a286f21d76 100644 --- a/scripts/west_commands/build.py +++ b/scripts/west_commands/build.py @@ -24,14 +24,24 @@ west build [-h] [-b BOARD] [-d BUILD_DIR] [source_dir] -- [cmake_opt [cmake_opt ...]] ''' -BUILD_DESCRIPTION = '''\ +BUILD_DESCRIPTION = f'''\ Convenience wrapper for building Zephyr applications. +{FIND_BUILD_DIR_DESCRIPTION} + positional arguments: - source_dir Use this path as the source directory - cmake_opt Extra options to pass to CMake; implies -c + source_dir application source directory + cmake_opt extra options to pass to cmake; implies -c + (these must come after "--" as shown above) ''' +PRISTINE_DESCRIPTION = """\ +A "pristine" build directory is empty. The -p option controls +whether the build directory is made pristine before the build +is done. A bare '--pristine' with no value is the same as +--pristine=always. Setting --pristine=auto uses heuristics to +guess if a pristine build may be necessary.""" + def _banner(msg): log.inf('-- west build: ' + msg, colorize=True) @@ -86,36 +96,34 @@ class Build(Forceable): # Remember to update scripts/west-completion.bash if you add or remove # flags - parser.add_argument('-b', '--board', help='Board to build for') + parser.add_argument('-b', '--board', help='board to build for') # Hidden option for backwards compatibility parser.add_argument('-s', '--source-dir', help=argparse.SUPPRESS) parser.add_argument('-d', '--build-dir', - help='Build directory. ' + - FIND_BUILD_DIR_DESCRIPTION + - " Otherwise the default build directory is " + - "created and used.") - parser.add_argument('-t', '--target', - help='''Build system target ("usage" - for more info; and "help" for a list)''') - parser.add_argument('-p', '--pristine', choices=['auto', 'always', - 'never'], action=AlwaysIfMissing, nargs='?', - help='''Control whether the build folder is made - pristine before running CMake. --pristine is the - same as --pristine=always. If 'auto', it will - be made pristine only if needed.''') - parser.add_argument('-c', '--cmake', action='store_true', - help='Force CMake to run') - parser.add_argument('--cmake-only', action='store_true', - help="Just run CMake; don't build. Implies -c.") - parser.add_argument('-n', '--just-print', '--dry-run', '--recon', - dest='dry_run', action='store_true', - help='''Just print the build commands; don't run - them''') - parser.add_argument('-o', '--build-opt', default=[], action='append', - help='''Options to pass to the build tool. - May be given more than once to append multiple - values.''') + help='build directory to create or use') self.add_force_arg(parser) + + group = parser.add_argument_group('cmake and build tool') + group.add_argument('-c', '--cmake', action='store_true', + help='force a cmake run') + group.add_argument('--cmake-only', action='store_true', + help="just run cmake; don't build (implies -c)") + group.add_argument('-t', '--target', + help='''run this build system target (try "-t usage" + or "-t help")''') + group.add_argument('-o', '--build-opt', default=[], action='append', + help='''options to pass to the build tool + (make or ninja); may be given more than once''') + group.add_argument('-n', '--just-print', '--dry-run', '--recon', + dest='dry_run', action='store_true', + help="just print build commands; don't run them") + + group = parser.add_argument_group('pristine builds', + PRISTINE_DESCRIPTION) + group.add_argument('-p', '--pristine', choices=['auto', 'always', + 'never'], action=AlwaysIfMissing, nargs='?', + help='pristine build folder setting') + return parser def do_run(self, args, remainder): diff --git a/scripts/west_commands/build_helpers.py b/scripts/west_commands/build_helpers.py index ca116f1bdcf..631528bb93a 100644 --- a/scripts/west_commands/build_helpers.py +++ b/scripts/west_commands/build_helpers.py @@ -24,7 +24,7 @@ DEFAULT_CMAKE_GENERATOR = 'Ninja' '''Name of the default CMake generator.''' FIND_BUILD_DIR_DESCRIPTION = '''\ -If not given, the default build directory is {}/ unless the +If the build directory is not given, the default is {}/ unless the build.dir-fmt configuration variable is set. The current directory is checked after that. If either is a Zephyr build directory, it is used. '''.format(DEFAULT_BUILD_DIR) diff --git a/scripts/west_commands/debug.py b/scripts/west_commands/debug.py index 469dc3d0b54..288363d2e0b 100644 --- a/scripts/west_commands/debug.py +++ b/scripts/west_commands/debug.py @@ -10,7 +10,7 @@ from textwrap import dedent from west.commands import WestCommand -from run_common import desc_common, add_parser_common, do_run_common +from run_common import add_parser_common, do_run_common class Debug(WestCommand): @@ -23,8 +23,7 @@ class Debug(WestCommand): dedent(''' Connect to the board, flash the program, and start a debugging session. Use "west attach" instead to attach - a debugger without reflashing.\n\n''') + - desc_common('debug'), + a debugger without reflashing.'''), accepts_unknown_args=True) self.runner_key = 'debug-runner' # in runners.yaml @@ -48,8 +47,7 @@ class DebugServer(WestCommand): The debug server binds to a known port, and allows client software started elsewhere to connect to it and debug the running - Zephyr image.\n\n''') + - desc_common('debugserver'), + Zephyr image.'''), accepts_unknown_args=True) self.runner_key = 'debug-runner' # in runners.yaml @@ -67,8 +65,7 @@ class Attach(WestCommand): 'attach', # Keep this in sync with the string in west-commands.yml. 'interactively debug a board', - "Like \"west debug\", but doesn't reflash the program.\n\n" + - desc_common('attach'), + "Like \"west debug\", but doesn't reflash the program.", accepts_unknown_args=True) self.runner_key = 'debug-runner' # in runners.yaml diff --git a/scripts/west_commands/flash.py b/scripts/west_commands/flash.py index d7585817221..321ba24bacd 100644 --- a/scripts/west_commands/flash.py +++ b/scripts/west_commands/flash.py @@ -8,7 +8,7 @@ from west.commands import WestCommand -from run_common import desc_common, add_parser_common, do_run_common +from run_common import add_parser_common, do_run_common class Flash(WestCommand): @@ -18,8 +18,7 @@ class Flash(WestCommand): 'flash', # Keep this in sync with the string in west-commands.yml. 'flash and run a binary on a board', - 'Permanently reprogram a board with a new binary.\n' + - desc_common('flash'), + "Permanently reprogram a board's flash with a new binary.", accepts_unknown_args=True) self.runner_key = 'flash-runner' # in runners.yaml diff --git a/scripts/west_commands/run_common.py b/scripts/west_commands/run_common.py index d1ae9c47951..08fb57f76cc 100644 --- a/scripts/west_commands/run_common.py +++ b/scripts/west_commands/run_common.py @@ -80,53 +80,52 @@ def add_parser_common(command, parser_adder=None, parser=None): command.name, formatter_class=argparse.RawDescriptionHelpFormatter, help=command.help, - description=command.description, - epilog=FIND_BUILD_DIR_DESCRIPTION) + description=command.description) # Remember to update scripts/west-completion.bash if you add or remove # flags parser.add_argument('-H', '--context', action='store_true', - help='''Rebuild application and print context-sensitive - help; this may be combined with --runner to restrict - output to a given runner.''') + help='print build directory specific help') - group = parser.add_argument_group(title='General options') + group = parser.add_argument_group('general options', + FIND_BUILD_DIR_DESCRIPTION) group.add_argument('-d', '--build-dir', metavar='DIR', - help='zephyr build directory') + help='application build directory') + # still supported for backwards compatibility, but questionably + # useful now that we do everything with runners.yaml group.add_argument('-c', '--cmake-cache', metavar='FILE', - help='override the default CMake cache file') + help=argparse.SUPPRESS) group.add_argument('-r', '--runner', - help=f'overrides the default {command.name} runner') + help='override default runner from --build-dir') group.add_argument('--skip-rebuild', action='store_true', - help='do not rebuild the application first') + help='do not refresh cmake dependencies first') - group = parser.add_argument_group(title='Common runner options') + group = parser.add_argument_group( + 'runner configuration overrides', + 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.''')) - group.add_argument('--board-dir', metavar='DIR', - help='zephyr board directory') - # FIXME: we should just have a single --file argument. + # TODO: is this actually useful? + group.add_argument('--board-dir', metavar='DIR', help='board directory') + # FIXME: we should just have a single --file argument. The variation + # between runners is confusing people. group.add_argument('--elf-file', metavar='FILE', help='path to zephyr.elf') group.add_argument('--hex-file', metavar='FILE', help='path to zephyr.hex') group.add_argument('--bin-file', metavar='FILE', help='path to zephyr.bin') - # FIXME: these are runner-specific. Remove them from this location. - group.add_argument('--gdb', help='path to GDB, if applicable') - group.add_argument('--openocd', help='path to OpenOCD, if applicable') + # FIXME: these are runner-specific and should be moved to where --context + # can find them instead. + group.add_argument('--gdb', help='path to GDB') + group.add_argument('--openocd', help='path to openocd') group.add_argument( '--openocd-search', metavar='DIR', - help='path to add to OpenOCD search path, if applicable') + help='path to add to openocd search path, if applicable') return parser -def desc_common(command_name): - return textwrap.dedent(f'''\ - Only common "west {command_name}" options are listed here. - To get help on available runner-specific options, run: - - west {command_name} --context -d BUILD_DIR - ''') - def do_run_common(command, user_args, user_runner_args): # This is the main routine for all the "west flash", "west debug", # etc. commands. diff --git a/scripts/west_commands/zephyr_ext_common.py b/scripts/west_commands/zephyr_ext_common.py index 233044cc046..40bc3764095 100644 --- a/scripts/west_commands/zephyr_ext_common.py +++ b/scripts/west_commands/zephyr_ext_common.py @@ -32,7 +32,7 @@ class Forceable(WestCommand): def add_force_arg(parser): '''Add a -f / --force option to the parser.''' parser.add_argument('-f', '--force', action='store_true', - help='Ignore any errors and try to proceed') + help='ignore any errors and try to proceed') def check_force(self, cond, msg): '''Abort if the command needs to be forced and hasn't been.