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>
This commit message is a bit of a novel mostly:
- because the issues involved are longstanding
- as evidence this is not a capricious refactoring
The runners.core.RunnerConfig Python class holds common configuration
values used by multiple runners, such as the location of the build
outputs and board directory.
The runners code, first written in 2017-ish, replaced various shell
scripts that got this information from the environment. Avoiding
environment variables was a requirement, however. It's ghastly to set
environment variables for a single command invocation on Windows, and
the whole thing was part of a larger push to make Zephyr development
on Windows better.
I had a hammer (the argparse module). Finding a replacement naturally
looked like a nail, so the information that ends up in RunnerConfig
got shunted from the build system to Python in the form of 'west
flash' / 'west debug' command line options like '--board-dir',
'--elf-file', etc.
I initially stored the options and their values in the CMake cache.
This was chosen in hopes the build system maintainer would like
the strategy (which worked).
I knew the command line arguments approach was a bit hacky (this
wasn't a nail), but I also honestly didn't have a better idea at the
time.
It did indeed cause issues:
- users don't know that just because they specify --bin-file on the
command line doesn't mean that their runner respects the option, and
have gotten confused trying to flash alternate files, usually for
chain-loading by MCUboot (for example, see #15961)
- common options weren't possible to pass via board.cmake files
(#22563, fixed partly via introduction of runners.yaml and the west
flash/debug commands no longer relying on the cache)
- it is confusing that "west flash --help" prints information about
openocd related options even when the user's board has no openocd
support. The same could be said about gdb in potential future use
cases where debugging occurs via some other tool.
Over time, they've caused enough users enough problems that
improvements are a priority.
To work towards this, put these values into runners.yaml using a new
'config: ...' key/value instead of command line options.
For example, instead of this in the generated runners.yaml file:
args:
common:
- --hex-file=.../zephyr.hex
we now have:
config:
hex_file: zephyr.hex
and similarly for other values.
In Python, we still support the command line options, but they are not
generated by the build system for any in-tree boards. Further work is
needed to deprecate the confusing ones (like --hex-file) and move the
runner-specific host tool related options (like --openocd) to the
runners that need them.
Individual board.cmake files should now influence these values by
overriding the relevant target properties of the
runners_yaml_props_target.
For example, instead of:
board_runner_args(foo "--hex-file=bar.hex")
Do this:
set_target_properties(runners_yaml_props_target PROPERTIES
hex_file bar.hex)
This change additionally allows us to stitch cmake/mcuboot.cmake and
the runners together easily by having mcuboot.cmake override the
properties that set the hex or bin file to flash. (The command line
arguments are still supported as-is.)
Combined with 98e0c95d91ae16f14e4997fb64ccdf0956595712 ("build:
auto-generate signed mcuboot binaries"), this will allow users to
build and flash images to be chain loaded by mcuboot in a way that
avoids calling 'west sign' and passing 'west flash' its output files
entirely.
While we are here, rename runner_yml_write to runners_yaml_append().
This function doesn't actually write anything, and we're here
refactoring this file anyway, so we might as well improve the
situation while we're at it.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
The 'runner_config' variable name is particularly misleading because
there is a class called RunnerConfig, and that variable does not
contain one.
Rename it to 'runners_yaml' since it contains the parsed contents of
the runners.yaml file. Rename the variable that refers to the path
itself to 'runners_yaml_path'. No functional changes expected.
This is prep work for redoing how actual RunnerConfig objects get
made.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
This commit creates a list of a phony targets for each runner, that is:
`west_flash_depends`, `west_debug_depends`, and so on.
Those targets has identical dependencies as CMake runner target.
flash, debug, debugserver, attach targets.
As example `ninja flash` correctly ensures dependencies are taken into
consideration before calling `west flash`.
Unfortunately, calling `west flash` directly would not re-run the flash
dependencies, cause `west flash` would only build the default CMake
target.
Now, `west flash` calls the phony `west_flash_depends` target, ensuring
all deps are up-to-date before flashing (unless --skip-rebuild is given)
The same is true for the other mentioned runners.
Signed-off-by: Torsten Rasmussen <Torsten.Rasmussen@nordicsemi.no>
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>
Require all implementations to provide a do_create(), a new
ZephyrBinaryRunner abstract class method, and make create() itself
concrete.
This allows us to enforce common conventions related to individual
runner capabilities as each runner provides to the core via
RunnerCaps.
For now, just enforce that:
- common options related to capabilities are always added, so runners
can't reuse them for different ends
- common options provided for runners which don't support them emit
sensible error messages that should be easy to diagnose and support
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Originally reported in #23539 (though that seems to have been another
problem), west flash and friends are dumping stack when used with an
unconfigured runner.
Let's just promote the warning about this to an error. The idea that
this ever could have worked without explicit support has not worked
out in practice, to my knowledge.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
This is yet another bug introduced by the move to runners.yaml.
Sigh. I should have tested this better.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
This will also make the reason for a following bug fix easier to see.
Update a comment block to include all the work that needs doing.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
This makes its true value clearer, and will make a later bug fix patch
easier to understand.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Refactor the code to support the new runners.yaml file created by the
build system.
Compared to fishing around in the CMake cache, this makes it trivial
to put all the command line arguments to a runner-based command on
equal footing, regardless of if they're defined in the runners package
proper or defined in run_common.py.
This allows board.cmake files to do things like this:
board_set_runner_args(foo
--bin-file=${PROJECT_BINARY_DIR}/my-signed.bin)
While at it, make some other cleanups:
- Stop using the obsolete and deprecated west.cmake module while we're
here in favor of the zcmake.py module which was added to Zephyr a long
time ago. Yikes. I had forgotten this was still here.
- Stop using west.util's wrap function in favor of raw use of
textwrap. The west function splits on hyphens, which is breaking
runner names like "em-starterkit".
- Clean up the --context output a bit
Fixes: #22563
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
The 'command' variable points at a python command object, not a
string. Take its name so the help text for west flash -h correctly
says 'flash' instead of 'debug'.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Catch RuntimeError when calling runner.run() and print a message
instead of dumping stack unless in verbose mode.
This improves the command line interface when runners raise exceptions.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Should be wrn() instead of warn(). Reported by pylint.
Also remove a {} from the message. It's not being formatted.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
Fixes this pylint warning:
scripts/west_commands/run_common.py:175:12: R1719: The if expression
can be replaced with 'test' (simplifiable-if-expression)
Fixing pylint warnings for a CI check.
Signed-off-by: Ulf Magnusson <Ulf.Magnusson@nordicsemi.no>
When using a build folder format with build.dir-fmt that includes any
parameters that need resolving, the west runners cannot find the folder
since the required information (board, source dir or app) is not
available.
Add a very simple heuristic to support the case where a build folder
starts with a hardcoded prefix (for example 'build/') and a single build
is present under that prefix.
The heuristic is gated behind a new configuration option:
build.guess-dir
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
Print a friendlier error message on ValueError, but don't throw away
the stack trace.
Move another call to log.die().
Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
Having common log handlers now lets us improve our logging output so
that info messages are prefixed with the runner they came from, and
doing something similar with the high level steps as we go, like this:
-- west <command>: using runners
-- runners.RUNNER_NAME: doing something
<output from RUNNER_NAME subprocesses go here>
-- runners.RUNNER_NAME: all done, bye
We can also colorize the west output to make it stand out better from
subprocesses, using the same output formatting style that west
commands like west list do.
Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
I've had some requests to be able to use code in the runners package
without having west installed.
It turns out to be pretty easy to make this happen, as west is
currently only used for west.log and some trivial helper methods:
- To replace west log, use the standard logging module
- Add an appropriate handler for each runner's logger in
run_common.py which delegates to west.log, to keep
output working as expected.
Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
The runners/jlink.py script has a mechanism for erroring out if a host
tool is not installed. Abstract it into runners/core.py and handle it
from run_common.py. This will let it be used in more places.
Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
In the west flash/debug commands, if the user gives an invalid build
directory, they'll get a stack trace instead of a helpful error
message when the cache can't be built.
Fix that.
Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
Add the possibility of configuring the build folder format in west's
configuration system.
The build.dir-fmt configuration option controls how west will create
build folders when not specified, the following parameters are currently
accepted:
- board: The board name
- source_dir: The relative path from CWD to the source directory
- app: The name of the source directory
If CWD is below source_dir in the directory hierarchy then source_dir is
set to an empty string.
This means that if one sets:
[build]
dir-fmt = build/{board}/{source_dir}
Then when building samples/hello_world from zephyr's root for the
reel_board the build folder will be:
./build/reel_board/samples/hello_world
but when building it from inside the samples/hello_world folder it will
instead be:
./build/reel_board
Fixes https://github.com/zephyrproject-rtos/west/issues/124
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
In preparation for upcoming changes to the way the default build folder
is defined, switch to using the common find_build_dir() function in the
runners.
This actually changes the behavior for the west build command slightly,
since the current working directory (cwd) will now be checked after the
default build folder ('build'). This brings it in line with what is
used for the runners.
Signed-off-by: Carles Cufi <carles.cufi@nordicsemi.no>
Let's not mess with CommandContextError here, as the APIs have gotten
messed around a bit in various versions. Just use log.die() as that
will work with current and future west versions, and is clearer anyway.
Fixes west 247.
Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
West now supports a mechanism for extension commands. Use it to move
the command implementations that are tightly coupled with boards and
the zephyr build system back into the Zephyr repository.
This patch doesn't include test cases. Those will be moved over in a
subsequent patch.
Signed-off-by: Marti Bolivar <marti@foundries.io>
