scripts: clean up west build/flash/debug help
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 <marti.bolivar@nordicsemi.no>
This commit is contained in:
Martí Bolívar
Anas Nashif
parent
79a8d0f616
commit
6e4c2b9be9
|
|
@ -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):
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in a new issue