zephyr/scripts/west_commands/run_common.py

# Copyright (c) 2018 Open Source Foundries Limited.
# Copyright (c) 2023 Nordic Semiconductor ASA
# Copyright (c) 2025 Aerlync Labs Inc.
#
# SPDX-License-Identifier: Apache-2.0

'''Common code used by commands which execute runners.
'''

import importlib.util
import re
import argparse
import logging
from collections import defaultdict
from os import close, getcwd, path, fspath
from pathlib import Path
from subprocess import CalledProcessError
import sys
import tempfile
import textwrap
import traceback

from dataclasses import dataclass
from west import log
from build_helpers import find_build_dir, is_zephyr_build, load_domains, \
    FIND_BUILD_DIR_DESCRIPTION
from west.commands import CommandError
from west.configuration import config
from runners.core import FileType
from runners.core import BuildConfiguration
import yaml

import zephyr_module
from zephyr_ext_common import ZEPHYR_BASE, ZEPHYR_SCRIPTS

# Runners depend on edtlib. Make sure the copy in the tree is
# available to them before trying to import any.
sys.path.insert(0, str(ZEPHYR_SCRIPTS / 'dts' / 'python-devicetree' / 'src'))

from runners import get_runner_cls, ZephyrBinaryRunner, MissingProgram
from runners.core import RunnerConfig
import zcmake

# Context-sensitive help indentation.
# Don't change this, or output from argparse won't match up.
INDENT = ' ' * 2

IGNORED_RUN_ONCE_PRIORITY = -1
SOC_FILE_RUN_ONCE_DEFAULT_PRIORITY = 0
BOARD_FILE_RUN_ONCE_DEFAULT_PRIORITY = 10

if log.VERBOSE >= log.VERBOSE_NORMAL:
    # Using level 1 allows sub-DEBUG levels of verbosity. The
    # west.log module decides whether or not to actually print the
    # message.
    #
    # https://docs.python.org/3.7/library/logging.html#logging-levels.
    LOG_LEVEL = 1
else:
    LOG_LEVEL = logging.INFO

def _banner(msg):
    log.inf('-- ' + msg, colorize=True)

class WestLogFormatter(logging.Formatter):

    def __init__(self):
        super().__init__(fmt='%(name)s: %(message)s')

class WestLogHandler(logging.Handler):

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.setFormatter(WestLogFormatter())
        self.setLevel(LOG_LEVEL)

    def emit(self, record):
        fmt = self.format(record)
        lvl = record.levelno
        if lvl > logging.CRITICAL:
            log.die(fmt)
        elif lvl >= logging.ERROR:
            log.err(fmt)
        elif lvl >= logging.WARNING:
            log.wrn(fmt)
        elif lvl >= logging.INFO:
            _banner(fmt)
        elif lvl >= logging.DEBUG:
            log.dbg(fmt)
        else:
            log.dbg(fmt, level=log.VERBOSE_EXTREME)

@dataclass
class UsedFlashCommand:
    command: str
    boards: list
    runners: list
    first: bool
    ran: bool = False

@dataclass
class ImagesFlashed:
    flashed: int = 0
    total: int = 0

@dataclass
class SocBoardFilesProcessing:
    filename: str
    board: bool = False
    priority: int = IGNORED_RUN_ONCE_PRIORITY
    yaml: object = None

def import_from_path(module_name, file_path):
    spec = importlib.util.spec_from_file_location(module_name, file_path)
    module = importlib.util.module_from_spec(spec)
    sys.modules[module_name] = module
    spec.loader.exec_module(module)
    return module

def command_verb(command):
    return "flash" if command.name == "flash" else "debug"

def add_parser_common(command, parser_adder=None, parser=None):
    if parser_adder is not None:
        parser = parser_adder.add_parser(
            command.name,
            formatter_class=argparse.RawDescriptionHelpFormatter,
            help=command.help,
            description=command.description)

    # Remember to update west-completion.bash if you add or remove
    # flags

    group = parser.add_argument_group('general options',
                                      FIND_BUILD_DIR_DESCRIPTION)

    group.add_argument('-d', '--build-dir', metavar='DIR',
                       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=argparse.SUPPRESS)
    group.add_argument('-r', '--runner',
                       help='override default runner from --build-dir')
    group.add_argument('--skip-rebuild', action='store_true',
                       help='do not refresh cmake dependencies first')
    group.add_argument('--domain', action='append',
                       help='execute runner only for given domain')

    group = parser.add_argument_group(
        'runner configuration',
        textwrap.dedent(f'''\
        ===================================================================
          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')
    # 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', action='append',
        help='path to add to openocd search path, if applicable')

    return parser

def is_sysbuild(build_dir):
    # Check if the build directory is part of a sysbuild (multi-image build).
    domains_yaml_path = path.join(build_dir, "domains.yaml")
    return path.exists(domains_yaml_path)

def get_domains_to_process(build_dir, args, domain_file, get_all_domain=False):
    try:
        domains = load_domains(build_dir)
    except Exception as e:
        log.die(f"Failed to load domains: {e}")

    if domain_file is None:
        if getattr(args, "domain", None) is None and get_all_domain:
            # This option for getting all available domains in the case of --context
            # So default domain will be used.
            return domains.get_domains()
        if getattr(args, "domain", None) is None:
            # No domains are passed down and no domains specified by the user.
            # So default domain will be used.
            return [domains.get_default_domain()]
        else:
            # No domains are passed down, but user has specified domains to use.
            # Get the user specified domains.
            return domains.get_domains(args.domain)
    else:
        # Use domains from domain file with flash order
        return domains.get_domains(args.domain, default_flash_order=True)

def do_run_common(command, user_args, user_runner_args, domain_file=None):
    # This is the main routine for all the "west flash", "west debug",
    # etc. commands.

    # Holds a list of run once commands, this is useful for sysbuild images
    # whereby there are multiple images per board with flash commands that can
    # interfere with other images if they run one per time an image is flashed.
    used_cmds = []

    # Holds a set of processed board names for flash running information.
    processed_boards = set()

    # Holds a dictionary of board image flash counts, the first element is
    # number of images flashed so far and second element is total number of
    # images for a given board.
    board_image_count = defaultdict(ImagesFlashed)

    highest_priority = IGNORED_RUN_ONCE_PRIORITY
    highest_entry = None
    check_files = []

    if user_args.context:
        dump_context(command, user_args, user_runner_args)
        return

    # Import external module runners
    for module in zephyr_module.parse_modules(ZEPHYR_BASE, command.manifest):
        runners_ext = module.meta.get("runners", [])
        for runner in runners_ext:
            import_from_path(
                module.meta.get("name", "runners_ext"), Path(module.project) / runner["file"]
            )

    build_dir = get_build_dir(user_args)
    if not user_args.skip_rebuild:
        rebuild(command, build_dir, user_args)

    domains = get_domains_to_process(build_dir, user_args, domain_file)

    if len(domains) > 1:
        if len(user_runner_args) > 0:
            log.wrn("Specifying runner options for multiple domains is experimental.\n"
                    "If problems are experienced, please specify a single domain "
                    "using '--domain <domain>'")

        # Process all domains to load board names and populate flash runner
        # parameters.
        board_names = set()
        for d in domains:
            if d.build_dir is None:
                build_dir = get_build_dir(user_args)
            else:
                build_dir = d.build_dir

            cache = load_cmake_cache(build_dir, user_args)
            build_conf = BuildConfiguration(build_dir)
            board = build_conf.get('CONFIG_BOARD_TARGET')
            board_names.add(board)
            board_image_count[board].total += 1

            # Load board flash runner configuration (if it exists) and store
            # single-use commands in a dictionary so that they get executed
            # once per unique board name.
            for directory in cache.get_list('SOC_DIRECTORIES'):
                if directory not in processed_boards:
                    check_files.append(SocBoardFilesProcessing(Path(directory) / 'soc.yml'))
                    processed_boards.add(directory)

            for directory in cache.get_list('BOARD_DIRECTORIES'):
                if directory not in processed_boards:
                    check_files.append(SocBoardFilesProcessing(Path(directory) / 'board.yml', True))
                    processed_boards.add(directory)

        for check in check_files:
            try:
                with open(check.filename, 'r') as f:
                    check.yaml = yaml.safe_load(f.read())

                    if 'runners' not in check.yaml:
                        continue
                    elif check.board is False and 'run_once' not in check.yaml['runners']:
                        continue

                    if 'priority' in check.yaml['runners']:
                        check.priority = check.yaml['runners']['priority']
                    else:
                        check.priority = BOARD_FILE_RUN_ONCE_DEFAULT_PRIORITY if check.board is True else SOC_FILE_RUN_ONCE_DEFAULT_PRIORITY

                    if check.priority == highest_priority:
                        log.die("Duplicate flash run once configuration found with equal priorities")

                    elif check.priority > highest_priority:
                        highest_priority = check.priority
                        highest_entry = check

            except FileNotFoundError:
                continue

        if highest_entry is not None:
            group_type = 'boards' if highest_entry.board is True else 'qualifiers'

            for cmd in highest_entry.yaml['runners']['run_once']:
                for data in highest_entry.yaml['runners']['run_once'][cmd]:
                    for group in data['groups']:
                        run_first = bool(data['run'] == 'first')
                        if group_type == 'qualifiers':
                            targets = []
                            for target in group[group_type]:
                                # For SoC-based qualifiers, prepend to the beginning of the
                                # match to allow for matching any board name
                                targets.append('([^/]+)/' + target)
                        else:
                            targets = group[group_type]

                        used_cmds.append(UsedFlashCommand(cmd, targets, data['runners'], run_first))

    # Reduce entries to only those having matching board names (either exact or with regex) and
    # remove any entries with empty board lists
    for i, entry in enumerate(used_cmds):
        for l, match in enumerate(entry.boards):
            match_found = False

            # Check if there is a matching board for this regex
            for check in board_names:
                if re.match(fr'^{match}$', check) is not None:
                    match_found = True
                    break

            if not match_found:
                del entry.boards[l]

        if len(entry.boards) == 0:
            del used_cmds[i]

    prev_runner = None
    for d in domains:
        prev_runner = do_run_common_image(command, user_args, user_runner_args, used_cmds,
                                          board_image_count, d.build_dir, prev_runner)


def do_run_common_image(command, user_args, user_runner_args, used_cmds,
                        board_image_count, build_dir=None, prev_runner=None):
    global re
    command_name = command.name
    if build_dir is None:
        build_dir = get_build_dir(user_args)
    cache = load_cmake_cache(build_dir, user_args)
    build_conf = BuildConfiguration(build_dir)
    board = build_conf.get('CONFIG_BOARD_TARGET')

    if board_image_count is not None and board in board_image_count:
        board_image_count[board].flashed += 1

    # Load runners.yaml.
    yaml_path = runners_yaml_path(build_dir, board)
    runners_yaml = load_runners_yaml(yaml_path)

    # Get a concrete ZephyrBinaryRunner subclass to use based on
    # runners.yaml and command line arguments.
    runner_cls = use_runner_cls(command, board, user_args, runners_yaml,
                                cache)
    runner_name = runner_cls.name()

    # Set up runner logging to delegate to west.log commands.
    logger = logging.getLogger('runners')
    logger.setLevel(LOG_LEVEL)
    if not logger.hasHandlers():
        # Only add a runners log handler if none has been added already.
        logger.addHandler(WestLogHandler())

    # If the user passed -- to force the parent argument parser to stop
    # parsing, it will show up here, and needs to be filtered out.
    runner_args = [arg for arg in user_runner_args if arg != '--']

    # Check if there are any commands that should only be ran once per board
    # and if so, remove them for all but the first iteration of the flash
    # runner per unique board name.
    if len(used_cmds) > 0 and len(runner_args) > 0:
        i = len(runner_args) - 1
        while i >= 0:
            for cmd in used_cmds:
                if cmd.command == runner_args[i] and (runner_name in cmd.runners or 'all' in cmd.runners):
                    # Check if board is here
                    match_found = False

                    for match in cmd.boards:
                        # Check if there is a matching board for this regex
                        if re.match(fr'^{match}$', board) is not None:
                            match_found = True
                            break

                    if not match_found:
                        continue

                    # Check if this is a first or last run
                    if not cmd.first:
                        # For last run instances, we need to check that this really is the last
                        # image of all boards being flashed
                        for check in cmd.boards:
                            can_continue = False

                            for match in board_image_count:
                                if re.match(fr'^{check}$', match) is not None:
                                    if board_image_count[match].flashed == board_image_count[match].total:
                                        can_continue = True
                                        break

                        if not can_continue:
                            continue

                    if not cmd.ran:
                        cmd.ran = True
                    else:
                        runner_args.pop(i)

                    break

            i = i - 1

    # Arguments in this order to allow specific to override general:
    #
    # - runner-specific runners.yaml arguments
    # - user-provided command line arguments
    final_argv = runners_yaml['args'][runner_name] + runner_args

    # If flashing multiple images, the runner supports reset after flashing and
    # the board has enabled this functionality, check if the board should be
    # reset or not. If this is not specified in the board/soc file, leave it up to
    # the runner's default configuration to decide if a reset should occur.
    if runner_cls.capabilities().reset and '--no-reset' not in final_argv:
        if board_image_count is not None:
            reset = True

            for cmd in used_cmds:
                if cmd.command == '--reset' and (runner_name in cmd.runners or 'all' in cmd.runners):
                    # Check if board is here
                    match_found = False

                    for match in cmd.boards:
                        if re.match(fr'^{match}$', board) is not None:
                            match_found = True
                            break

                    if not match_found:
                        continue

                    # Check if this is a first or last run
                    if cmd.first and cmd.ran:
                        reset = False
                        break
                    elif not cmd.first and not cmd.ran:
                        # For last run instances, we need to check that this really is the last
                        # image of all boards being flashed
                        for check in cmd.boards:
                            can_continue = False

                            for match in board_image_count:
                                if re.match(fr'^{check}$', match) is not None:
                                    if board_image_count[match].flashed != board_image_count[match].total:
                                        reset = False
                                        break

            if reset:
                final_argv.append('--reset')
            else:
                final_argv.append('--no-reset')

    # 'user_args' contains parsed arguments which are:
    #
    # 1. provided on the command line, and
    # 2. handled by add_parser_common(), and
    # 3. *not* runner-specific
    #
    # 'final_argv' contains unparsed arguments from either:
    #
    # 1. runners.yaml, or
    # 2. the command line
    #
    # We next have to:
    #
    # - parse 'final_argv' now that we have all the command line
    #   arguments
    # - create a RunnerConfig using 'user_args' and the result
    #   of parsing 'final_argv'
    parser = argparse.ArgumentParser(prog=runner_name, allow_abbrev=False)
    add_parser_common(command, parser=parser)
    runner_cls.add_parser(parser)
    args, unknown = parser.parse_known_args(args=final_argv)
    if unknown:
        log.die(f'runner {runner_name} received unknown arguments: {unknown}')

    # Propagate useful args from previous domain invocations
    if prev_runner is not None:
        runner_cls.args_from_previous_runner(prev_runner, args)

    # Override args with any user_args. The latter must take
    # precedence, or e.g. --hex-file on the command line would be
    # ignored in favor of a board.cmake setting.
    for a, v in vars(user_args).items():
        if v is not None:
            setattr(args, a, v)

    # Create the RunnerConfig from runners.yaml and any command line
    # overrides.
    runner_config = get_runner_config(build_dir, yaml_path, runners_yaml, args)
    log.dbg(f'runner_config: {runner_config}', level=log.VERBOSE_VERY)

    # Use that RunnerConfig to create the ZephyrBinaryRunner instance
    # and call its run().
    try:
        runner = runner_cls.create(runner_config, args)
        runner.run(command_name)
    except ValueError as ve:
        log.err(str(ve), fatal=True)
        dump_traceback()
        raise CommandError(1)
    except MissingProgram as e:
        log.die('required program', e.filename,
                'not found; install it or add its location to PATH')
    except RuntimeError as re:
        if not user_args.verbose:
            log.die(re)
        else:
            log.err('verbose mode enabled, dumping stack:', fatal=True)
            raise
    return runner

def get_build_dir(args, die_if_none=True):
    # Get the build directory for the given argument list and environment.
    if args.build_dir:
        return args.build_dir

    guess = config.get('build', 'guess-dir', fallback='never')
    guess = guess == 'runners'
    dir = find_build_dir(None, guess)

    if dir and is_zephyr_build(dir):
        return dir
    elif die_if_none:
        msg = '--build-dir was not given, '
        if dir:
            msg = msg + 'and neither {} nor {} are zephyr build directories.'
        else:
            msg = msg + ('{} is not a build directory and the default build '
                         'directory cannot be determined. Check your '
                         'build.dir-fmt configuration option')
        log.die(msg.format(getcwd(), dir))
    else:
        return None

def load_cmake_cache(build_dir, args):
    cache_file = path.join(build_dir, args.cmake_cache or zcmake.DEFAULT_CACHE)
    try:
        return zcmake.CMakeCache(cache_file)
    except FileNotFoundError:
        log.die(f'no CMake cache found (expected one at {cache_file})')

def rebuild(command, build_dir, args):
    _banner(f'west {command.name}: rebuilding')
    try:
        zcmake.run_build(build_dir)
    except CalledProcessError:
        if args.build_dir:
            log.die(f're-build in {args.build_dir} failed')
        else:
            log.die(f're-build in {build_dir} failed (no --build-dir given)')

def runners_yaml_path(build_dir, board):
    ret = Path(build_dir) / 'zephyr' / 'runners.yaml'
    if not ret.is_file():
        log.die(f'no runners.yaml found in {build_dir}/zephyr. '
        f"Either board {board} doesn't support west flash/debug/simulate,"
        ' or a pristine build is needed.')
    return ret

def load_runners_yaml(path):
    # Load runners.yaml and convert to Python object.

    try:
        with open(path, 'r') as f:
            content = yaml.safe_load(f.read())
    except FileNotFoundError:
        log.die(f'runners.yaml file not found: {path}')

    if not content.get('runners'):
        log.wrn(f'no pre-configured runners in {path}; '
                "this probably won't work")

    return content

def use_runner_cls(command, board, args, runners_yaml, cache):
    # Get the ZephyrBinaryRunner class from its name, and make sure it
    # supports the command. Print a message about the choice, and
    # return the class.

    runner = args.runner or runners_yaml.get(command.runner_key)
    if runner is None:
        log.die(f'no {command.name} runner available for board {board}. '
                "Check the board's documentation for instructions.")

    _banner(f'west {command.name}: using runner {runner}')

    available = runners_yaml.get('runners', [])
    if runner not in available:
        if 'BOARD_DIR' in cache:
            board_cmake = Path(cache['BOARD_DIR']) / 'board.cmake'
        else:
            board_cmake = 'board.cmake'
        log.err(f'board {board} does not support runner {runner}',
                fatal=True)
        log.inf(f'To fix, configure this runner in {board_cmake} and rebuild.')
        sys.exit(1)
    try:
        runner_cls = get_runner_cls(runner)
    except ValueError as e:
        log.die(e)
    if command.name not in runner_cls.capabilities().commands:
        log.die(f'runner {runner} does not support command {command.name}')

    return runner_cls

def get_runner_config(build_dir, yaml_path, runners_yaml, args=None):
    # Get a RunnerConfig object for the current run. yaml_config is
    # runners.yaml's config: map, and args are the command line arguments.
    yaml_config = runners_yaml['config']
    yaml_dir = yaml_path.parent
    if args is None:
        args = argparse.Namespace()

    def output_file(filetype):

        from_args = getattr(args, f'{filetype}_file', None)
        if from_args is not None:
            return from_args

        from_yaml = yaml_config.get(f'{filetype}_file')
        if from_yaml is not None:
            # Output paths in runners.yaml are relative to the
            # directory containing the runners.yaml file.
            return fspath(yaml_dir / from_yaml)

        return None

    def config(attr, default=None):
        return getattr(args, attr, None) or yaml_config.get(attr, default)

    def filetype(attr):
        ftype = str(getattr(args, attr, None)).lower()
        if ftype == "hex":
            return FileType.HEX
        elif ftype == "bin":
            return FileType.BIN
        elif ftype == "elf":
            return FileType.ELF
        elif getattr(args, attr, None) is not None:
            err = 'unknown --file-type ({}). Please use hex, bin or elf'
            raise ValueError(err.format(ftype))

        # file-type not provided, try to get from filename
        file = getattr(args, "file", None)
        if file is not None:
            ext = Path(file).suffix
            if ext == ".hex":
                return FileType.HEX
            if ext == ".bin":
                return FileType.BIN
            if ext == ".elf":
                return FileType.ELF

        # we couldn't get the file-type, set to
        # OTHER and let the runner deal with it
        return FileType.OTHER

    return RunnerConfig(build_dir,
                        yaml_config['board_dir'],
                        output_file('elf'),
                        output_file('exe'),
                        output_file('hex'),
                        output_file('bin'),
                        output_file('uf2'),
                        output_file('mot'),
                        config('file'),
                        filetype('file_type'),
                        config('gdb'),
                        config('openocd'),
                        config('openocd_search', []),
                        config('rtt_address'))

def dump_traceback():
    # Save the current exception to a file and return its path.
    fd, name = tempfile.mkstemp(prefix='west-exc-', suffix='.txt')
    close(fd)        # traceback has no use for the fd
    with open(name, 'w') as f:
        traceback.print_exc(file=f)
    log.inf("An exception trace has been saved in", name)

#
# west {command} --context
#

def dump_context(command, args, unknown_args):
    build_dir = get_build_dir(args, die_if_none=False)
    get_all_domain = False

    if build_dir is None:
        log.wrn('no --build-dir given or found; output will be limited')
        dump_context_no_config(command, None)
        return

    if is_sysbuild(build_dir):
        get_all_domain = True

    # Re-build unless asked not to, to make sure the output is up to date.
    if build_dir and not args.skip_rebuild:
        rebuild(command, build_dir, args)

    domains = get_domains_to_process(build_dir, args, None, get_all_domain)

    if len(domains) > 1 and not getattr(args, "domain", None):
        log.inf("Multiple domains available:")
        for i, domain in enumerate(domains, 1):
            log.inf(f"{INDENT}{i}. {domain.name} (build_dir: {domain.build_dir})")

        while True:
            try:
                choice = input(f"Select domain (1-{len(domains)}): ")
                choice = int(choice)
                if 1 <= choice <= len(domains):
                    domains = [domains[choice-1]]
                    break
                log.wrn(f"Please enter a number between 1 and {len(domains)}")
            except ValueError:
                log.wrn("Please enter a valid number")
            except EOFError:
                log.die("Input cancelled, exiting")

    selected_build_dir = domains[0].build_dir

    if not path.exists(selected_build_dir):
        log.die(f"Build directory does not exist: {selected_build_dir}")

    build_conf = BuildConfiguration(selected_build_dir)

    board = build_conf.get('CONFIG_BOARD_TARGET')
    if not board:
        log.die("CONFIG_BOARD_TARGET not found in build configuration.")

    yaml_path = runners_yaml_path(selected_build_dir, board)
    if not path.exists(yaml_path):
        log.die(f"runners.yaml not found in: {yaml_path}")

    runners_yaml = load_runners_yaml(yaml_path)

    # Dump runner info
    log.inf(f'build configuration:', colorize=True)
    log.inf(f'{INDENT}build directory: {build_dir}')
    log.inf(f'{INDENT}board: {board}')
    log.inf(f'{INDENT}runners.yaml: {yaml_path}')
    if args.runner:
        try:
            cls = get_runner_cls(args.runner)
            dump_runner_context(command, cls, runners_yaml)
        except ValueError:
            available_runners = ", ".join(cls.name() for cls in ZephyrBinaryRunner.get_runners())
            log.die(f"Invalid runner name {args.runner}; choices: {available_runners}")
    else:
        dump_all_runner_context(command, runners_yaml, board, selected_build_dir)

def dump_context_no_config(command, cls):
    if not cls:
        all_cls = {cls.name(): cls for cls in ZephyrBinaryRunner.get_runners()
                   if command.name in cls.capabilities().commands}
        log.inf('all Zephyr runners which support {}:'.format(command.name),
                colorize=True)
        dump_wrapped_lines(', '.join(all_cls.keys()), INDENT)
        log.inf()
        log.inf('Note: use -r RUNNER to limit information to one runner.')
    else:
        # This does the right thing with a None argument.
        dump_runner_context(command, cls, None)

def dump_runner_context(command, cls, runners_yaml, indent=''):
    dump_runner_caps(cls, indent)
    dump_runner_option_help(cls, indent)

    if runners_yaml is None:
        return

    if cls.name() in runners_yaml['runners']:
        dump_runner_args(cls.name(), runners_yaml, indent)
    else:
        log.wrn(f'support for runner {cls.name()} is not configured '
                f'in this build directory')

def dump_runner_caps(cls, indent=''):
    # Print RunnerCaps for the given runner class.

    log.inf(f'{indent}{cls.name()} capabilities:', colorize=True)
    log.inf(f'{indent}{INDENT}{cls.capabilities()}')

def dump_runner_option_help(cls, indent=''):
    # Print help text for class-specific command line options for the
    # given runner class.

    dummy_parser = argparse.ArgumentParser(prog='', add_help=False, allow_abbrev=False)
    cls.add_parser(dummy_parser)
    formatter = dummy_parser._get_formatter()
    for group in dummy_parser._action_groups:
        # Break the abstraction to filter out the 'flash', 'debug', etc.
        # TODO: come up with something cleaner (may require changes
        # in the runner core).
        actions = group._group_actions
        if len(actions) == 1 and actions[0].dest == 'command':
            # This is the lone positional argument. Skip it.
            continue
        formatter.start_section('REMOVE ME')
        formatter.add_text(group.description)
        formatter.add_arguments(actions)
        formatter.end_section()
    # Get the runner help, with the "REMOVE ME" string gone
    runner_help = f'\n{indent}'.join(formatter.format_help().splitlines()[1:])

    log.inf(f'{indent}{cls.name()} options:', colorize=True)
    log.inf(indent + runner_help)

def dump_runner_args(group, runners_yaml, indent=''):
    msg = f'{indent}{group} arguments from runners.yaml:'
    args = runners_yaml['args'][group]
    if args:
        log.inf(msg, colorize=True)
        for arg in args:
            log.inf(f'{indent}{INDENT}{arg}')
    else:
        log.inf(f'{msg} (none)', colorize=True)

def dump_all_runner_context(command, runners_yaml, board, build_dir):
    all_cls = {cls.name(): cls for cls in ZephyrBinaryRunner.get_runners() if
               command.name in cls.capabilities().commands}
    available = runners_yaml['runners']
    available_cls = {r: all_cls[r] for r in available if r in all_cls}
    default_runner = runners_yaml[command.runner_key]
    yaml_path = runners_yaml_path(build_dir, board)
    runners_yaml = load_runners_yaml(yaml_path)

    log.inf(f'zephyr runners which support "west {command.name}":',
            colorize=True)
    dump_wrapped_lines(', '.join(all_cls.keys()), INDENT)
    log.inf()
    dump_wrapped_lines('Note: not all may work with this board and build '
                       'directory. Available runners are listed below.',
                       INDENT)

    log.inf(f'available runners in runners.yaml:',
            colorize=True)
    dump_wrapped_lines(', '.join(available), INDENT)
    log.inf(f'default runner in runners.yaml:', colorize=True)
    log.inf(INDENT + default_runner)
    log.inf('common runner configuration:', colorize=True)
    runner_config = get_runner_config(build_dir, yaml_path, runners_yaml)
    for field, value in zip(runner_config._fields, runner_config):
        log.inf(f'{INDENT}- {field}: {value}')
    log.inf('runner-specific context:', colorize=True)
    for cls in available_cls.values():
        dump_runner_context(command, cls, runners_yaml, INDENT)

    if len(available) > 1:
        log.inf()
        log.inf('Note: use -r RUNNER to limit information to one runner.')

def dump_wrapped_lines(text, indent):
    for line in textwrap.wrap(text, initial_indent=indent,
                              subsequent_indent=indent,
                              break_on_hyphens=False,
                              break_long_words=False):
        log.inf(line)