zephyr 构建、烧录与调试

 

Building, Flashing and Debugging

Zephyr provides several west extension commands for building, flashing, and interacting with Zephyr programs running on a board: build, flash, debug, debugserver and attach.

Zephyr 提供了几个 west 扩展命令,用于构建、烧录和与运行在板上的 Zephyr 程序交互: build, flash, debug, debugserverattach.

For information on adding board support for the flashing and debugging commands, see Flash and debug support in the board porting guide.

有关为烧录和调试命令添加板支持的信息,请参阅板移植指南中的 Flash 和调试支持。(2)

Building: west build

Run west build -h for a quick overview.

运行 west build-h 以获得一个快速概述。

The build command helps you build Zephyr applications from source. You can use west config to configure its behavior.

Build 命令可以帮助您从源代码构建 Zephyr 应用程序。

Its default behavior tries to “do what you mean”:

它的默认行为试图“做你想做的事情”:

  • If there is a Zephyr build directory named build in your current working directory, it is incrementally re-compiled. The same is true if you run west build from a Zephyr build directory.

    如果当前工作目录中有一个名为 build 的 Zephyr 构建目录,那么它将被递增地重新编译。如果从 Zephyr 构建目录运行 west build,情况也是如此

  • Otherwise, if you run west build from a Zephyr application’s source directory and no build directory is found, a new one is created and the application is compiled in it.

    否则,如果从 Zephyr 应用程序的源目录运行 west build,但没有找到任何构建目录,则创建一个新的目录,并在其中编译应用程序

Basics 基本知识

The easiest way to use west build is to go to an application’s root directory (i.e. the folder containing the application’s CMakeLists.txt) and then run:

使用 west build 最简单的方法是转到应用程序的根目录(即包含应用程序的 CMakeLists.txt 的文件夹) ,然后运行:

west build -b <BOARD>

Where <BOARD> is the name of the board you want to build for. This is exactly the same name you would supply to CMake if you were to invoke it with: cmake -DBOARD=<BOARD>.

其中 < board > 是要为其构建的主板的名称。如果您使用: cmake -DBOARD=<BOARD> 调用它,那么您将为 CMake 提供完全相同的名称。

You can use the west boards command to list all supported boards.

你可以使用 west boards 命令列出所有支持的 boards。

A build directory named build will be created, and the application will be compiled there after west build runs CMake to create a build system in that directory. If west build finds an existing build directory, the application is incrementally re-compiled there without re-running CMake. You can force CMake to run again with --cmake.

一个名为 “build “的构建目录将被创建,在west build运行CMake以在该目录中创建一个构建系统后,应用程序将被编译到那里。如果west build找到一个现有的构建目录,应用程序将在那里被逐步重新编译,而无需重新运行CMake。你可以用--cmake强制CMake再次运行。

You don’t need to use the --board option if you’ve already got an existing build directory; west build can figure out the board from the CMake cache. For new builds, the --board option, BOARD environment variable, or build.board configuration option are checked (in that order).

如果您已经有了一个现有的构建目录,那么您不需要使用 –board 选项; west build 可以从 CMake 缓存中算出这块板。对于新的构建,依次检查 --board 选项、 BOARD环境变量或 build.board 配置选项

Examples 例子

Here are some west build usage examples, grouped by area.

下面是一些按区域分组的 west 构建使用示例。

Forcing CMake to Run Again 强制 CMake 再次运行

To force a CMake re-run, use the --cmake (or -c) option:

若要强制 CMake 重新运行,请使用 –cmake (或-c)选项:

west build -c

Setting a Default Board 设置默认的主板

To configure west build to build for the reel_board by default:

默认情况下,配置 west build 为 reel_board 构建:

west config build.board reel_board

Setting Source and Build Directories 设置源文件和生成目录

To set the application source directory explicitly, give its path as a positional argument:

若要显式设置应用程序源目录,请将其路径作为位置参数提供:

west build -b <BOARD> path/to/source/directory

To set the build directory explicitly, use --build-dir (or -d):

要显式设置生成目录,请使用 --build-dir (或-d) :

west build -b <BOARD> --build-dir path/to/build/directory

To change the default build directory from build, use the build.dir-fmt configuration option. This lets you name build directories using format strings, like this:

要从 build 更改默认的 build 目录,请使用 build.dir-fmt 配置选项。这样可以使用格式字符串命名构建目录,如下所示:

west config build.dir-fmt "build/{board}/{app}"

With the above, running west build -b reel_board samples/hello_world will use build directory build/reel_board/hello_world. See Configuration Options for more details on this option.

有了上面的代码,运行 west build -b reel_board samples/hello_world 将使用 build/reel_board/hello_world。有关此选项的详细信息,请参阅配置选项。

Setting the Build System Target 设置生成系统目标

To specify the build system target to run, use --target (or -t).

若要指定要运行的生成系统目标,请使用 --target (或-t)。

For example, on host platforms with QEMU, you can use the run target to build and run the Hello World sample for the emulated qemu_x86 board in one command:

例如,在使用 QEMU 的主机平台上,您可以使用 run target 在一个命令中为模拟的 QEMU x86板构建并运行 Hello World 示例:

west build -b qemu_x86 -t run samples/hello_world

As another example, to use -t to list all build system targets:

另一个例子是,使用-t 列出所有的构建系统目标:

west build -t help

As a final example, to use -t to run the pristine target, which deletes all the files in the build directory:

最后一个例子,使用-t 运行原始目标,它会删除构建目录中的所有文件:

west build -t pristine

Pristine Builds 原始版本

A pristine build directory is essentially a new build directory. All byproducts from previous builds have been removed.

原始构建目录本质上是一个新的构建目录。以前构建的所有副产品都已被删除

To force west build make the build directory pristine before re-running CMake to generate a build system, use the --pristine=always (or -p=always) option.

要强制 west build 在重新运行 CMake 生成构建系统之前使构建目录处于原始状态,请使用 --pristine=always (或-p=always)选项。

Giving --pristine or -p without a value has the same effect as giving it the value always. For example, these commands are equivalent:

给予 --pristine 或者没有值的 -p 具有与赋值总是相同的效果。例如,这些命令是等价的:

west build -p -b reel_board samples/hello_world
west build -p=always -b reel_board samples/hello_world

By default, west build applies a heuristic to detect if the build directory needs to be made pristine. This is the same as using --pristine=auto.

默认情况下,west build 应用一种启发式方法来检测构建目录是否需要保持原样。这和使用 --pristine=auto 是一样的。

Tip 小贴士

You can run west config build.pristine always to always do a pristine build, or west config build.pristine never to disable the heuristic. See the west build Configuration Options for details.

你可以运行 west config build.pristine always执行一个原始构建,或者 west config build.pristine never永远不会禁用启发式。详细信息请参阅 west build Configuration Options。

Verbose Builds 详细构建

To print the CMake and compiler commands run by west build, use the global west verbosity option, -v:

要打印由 west build 运行的 CMake 和编译器命令,请使用 global west verbosity 选项-v:

west -v build -b reel_board samples/hello_world

One-Time CMake Arguments 一次性的 CMake Arguments

To pass additional arguments to the CMake invocation performed by west build, pass them after a -- at the end of the command line.

要向 west build 执行的 CMake 调用传递其他参数,请在命令行末尾的 -- 之后传递它们。

Important 重要事项

Passing additional CMake arguments like this forces west build to re-run CMake, even if a build system has already been generated.

传递额外的 CMake 参数(如本文所示)将迫使 west build 重新运行 CMake,即使已经生成了构建系统。

After using -- once to generate the build directory, use west build -d <build-dir> on subsequent runs to do incremental builds.

在使用 -- 一旦生成构建目录之后,在随后的运行中使用 west build-d <build-dir> 来执行增量构建。

For example, to use the Unix Makefiles CMake generator instead of Ninja (which west build uses by default), run:

例如,要使用 Unix makefile CMake 生成器而不是 Ninja (默认使用 west build) ,请运行:

west build -b reel_board -- -G'Unix Makefiles'

To use Unix Makefiles and set CMAKE_VERBOSE_MAKEFILE to ON:

使用 Unix makefile 并将 CMAKE_VERBOSE_MAKEFILE 设置为 ON:

west build -b reel_board -- -G'Unix Makefiles' -DCMAKE_VERBOSE_MAKEFILE=ON

Notice how the -- only appears once, even though multiple CMake arguments are given. All command-line arguments to west build after a -- are passed to CMake.

注意 -- 只出现一次,即使给出了多个 CMake 参数。在 -- 之后的 west build 的所有命令行参数都传递给 CMake。

To set DTC_OVERLAY_FILE to enable-modem.overlay, using that file as a devicetree overlay:

DTC_OVERLAY_FILE 设置为 enable-modem.overlay,使用该文件作为设备树覆盖:

west build -b reel_board -- -DDTC_OVERLAY_FILE=enable-modem.overlay

To merge the file.conf Kconfig fragment into your build’s .config:

将 file.conf Kconfig 片段合并到构建的.config 中:

west build -- -DOVERLAY_CONFIG=file.conf

Permanent CMake Arguments 永久的CMAKE参数

The previous section describes how to add CMake arguments for a single west build command. If you want to save CMake arguments for west build to use every time it generates a new build system instead, you should use the build.cmake-args configuration option. Whenever west build runs CMake to generate a build system, it splits this option’s value according to shell rules and includes the results in the cmake command line.

前面的部分描述了如何为单个 west build 命令添加 CMake 参数。如果希望在 west build 每次生成新的 build 系统时都使用 CMake 参数,应该使用 build.cmake-args 配置选项。每当 west build 运行 CMake 生成一个 build 系统时,它都会根据 shell 规则分割该选项的值,并在 CMake 命令行中包含结果。

Remember that, by default, west build tries to avoid generating a new build system if one is present in your build directory. Therefore, you need to either delete any existing build directories or do a pristine build after setting build.cmake-args to make sure it will take effect.

记住,默认情况下,如果构建目录中存在一个新的构建系统,west build 会尝试避免生成这样的系统。因此,您需要删除任何现有的构建目录,或者在设置 build.cmake-args 之后执行原始构建,以确保其生效。

For example, to always enable CMAKE_EXPORT_COMPILE_COMMANDS, you can run:

例如,为了总是启用 CMAKE_EXPORT_COMPILE_COMMANDS,你可以运行:

west config build.cmake-args -- -DCMAKE_EXPORT_COMPILE_COMMANDS=ON

(The extra -- is used to force the rest of the command to be treated as a positional argument. Without it, west config would treat the -DVAR=VAL syntax as a use of its -D option.)

(额外的 -- 用于强制将命令的其余部分视为位置参数。如果没有它,west config 将把 -DVAR=VAL 语法当作使用它的 -d 选项。)

To enable CMAKE_VERBOSE_MAKEFILE, so CMake always produces a verbose build system:

启用 CMAKE_VERBOSE_MAKEFILE,以便 CMAKE 总是生成一个详细的构建系统:

west config build.cmake-args -- -DCMAKE_VERBOSE_MAKEFILE=ON

To save more than one argument in build.cmake-args, use a single string whose value can be split into distinct arguments (west build uses the Python function shlex.split() internally to split the value).

要在 build.cmake-args 中保存多个参数,可以使用一个字符串,该字符串的值可以拆分为不同的参数(west build 在内部使用 Python 函数 shlex.split ()来拆分值)。

For example, to enable both CMAKE_EXPORT_COMPILE_COMMANDS and CMAKE_VERBOSE_MAKEFILE:

例如,同时启用 CMAKE_EXPORT_COMPILE_COMMANDS 和 CMAKE_VERBOSE_MAKEFILE:

west config build.cmake-args -- "-DCMAKE_EXPORT_COMPILE_COMMANDS=ON -DCMAKE_VERBOSE_MAKEFILE=ON"

If you want to save your CMake arguments in a separate file instead, you can combine CMake’s -C <initial-cache> option with build.cmake-args. For instance, another way to set the options used in the previous example is to create a file named ~/my-cache.cmake with the following contents:

如果希望将 CMake 参数保存到单独的文件中,可以将 CMake 的 -C <initial-cache> 选项与 build.cmake-args 结合起来。例如,设置前面示例中使用的选项的另一种方法是创建一个名为 ~/my-cache 的文件。内容如下:

set(CMAKE_EXPORT_COMPILE_COMMANDS ON CACHE BOOL "")
set(CMAKE_VERBOSE_MAKEFILE ON CACHE BOOL "")

Then run: 然后跑:

west config build.cmake-args "-C ~/my-cache.cmake"

See the cmake(1) manual page and the set() command documentation for more details.

有关详细信息,请参阅 cmake (1)手册页和 set ()命令文档。

Build tool arguments 构建工具参数

Use -o to pass options to the underlying build tool.

使用 -o 将选项传递给基础生成工具

This works with both ninja (the default) and make based build systems.

这对 ninja (默认)和基于 make 的构建系统都适用。

For example, to pass -dexplain to ninja:

例如,要传递-dexplain 给忍者:

west build -o=-dexplain

As another example, to pass --keep-going to make:

作为另一个例子,传递 –keep-going 给 make:

west build -o=--keep-going

Note that using -o=--foo instead of -o --foo is required to prevent --foo from being treated as a west build option.

请注意,使用 -o=--foo 而不是 -o --foo 是为了防止 --foo 被视为 west build 选项。

Build parallelism 构建并行性

By default, ninja uses all of your cores to build, while make uses only one. You can control this explicitly with the -j option supported by both tools.

默认情况下,忍者使用你所有的核心来构建,而 make 只使用一个。您可以使用两个工具都支持的-j 选项显式地控制它。

For example, to build with 4 cores: 例如,使用4个核构建:

west build -o=-j4

The -o option is described further in the previous section.

-o 选项将在前一节中进一步描述。

Configuration Options 配置选项

You can configure west build using these options.

您可以使用这些选项配置 west build。

Option 选择 Description 描述
build.board String. If given, this the board used by west build when --board is not given and BOARD is unset in the environment.
字符串。如果给定,这是西部建造时使用的板,当——板没有给定,主板在环境中没有设置。
build.board_warn Boolean, default true. If false, disables warnings when west build can’t figure out the target board.
布尔值,默认为真。如果为假,则在 west build 无法计算出目标板时禁用警告。
build.cmake-args String. If present, the value will be split according to shell rules and passed to CMake whenever a new build system is generated. See Permanent CMake Arguments.
字符串。如果存在,则该值将根据 shell 规则进行分割,并在生成新的构建系统时传递给 CMake。参见永久性 CMake 参数。
build.dir-fmt String, default build. The build folder format string, used by west whenever it needs to create or locate a build folder. The currently available arguments are: board: The board name
字符串,默认构建。生成文件夹格式字符串,west 在需要创建或定位生成文件夹时使用。目前可用的参数是:board: 主板名称
source_dir: The relative path from the current working directory to the source directory. If the current working directory is inside the source directory this will be set to an empty string.Source/dir:
当前工作目录目录到源目录的相对路径。如果当前的工作目录文件在源目录中,它将被设置为一个空字符串。
app: The name of the source directory.
app: 源目录的名称。
build.generator String, default Ninja. The CMake Generator to use to create a build system. (To set a generator for a single build, see the above example)
字符串,默认的忍者。用于创建生成系统的 CMake 生成器。(要为单个版本设置生成器,请参见上面的示例)
build.guess-dir String, instructs west whether to try to guess what build folder to use when build.dir-fmt is in use and not enough information is available to resolve the build folder name. Can take these values:
在使用 build.dir-fmt 时,指示 west 是否尝试猜测要使用的构建文件夹,但是没有足够的信息来解析构建文件夹名称。可以采取以下值:
never (default): Never try to guess, bail out instead and require the user to provide a build folder with -d.
never(默认值) : 不要试图猜测,而是退出,并要求用户提供一个-d 的构建文件夹。
runners: Try to guess the folder when using any of the ‘runner’ commands. These are typically all commands that invoke an external tool, such as flash and debug.
runner: 使用任何‘运动员’命令时,试着猜测文件夹。这些通常是所有调用外部工具(如 flash 和 debug)的命令。
build.pristine String. Controls the way in which west build may clean the build folder before building. Can take the following values:
字符串。控制 west 生成在生成之前清除生成文件夹的方式。可以采用下列值:never (default): Never automatically make the build folder pristine.
Never (默认值) : 永远不要自动使生成文件夹处于原始状态。
auto: west build will automatically make the build folder pristine before building, if a build system is present and the build would fail otherwise (e.g. the user has specified a different board or application from the one previously used to make the build directory).
如果一个构建系统已经存在并且构建会失败,那么在构建之前,west build 会自动使构建文件夹处于原始状态(例如,用户指定了一个与之前用于构建目录的不同的板或应用程序)。
always: Always make the build folder pristine before building, if a build system is present.
始终: 如果存在构建系统,则始终在构建之前使构建文件夹处于原始状态。

Flashing: west flash

Run west flash -h for additional help.

Basics 基本知识

From a Zephyr build directory, re-build the binary and flash it to your board:

从 Zephyr 构建目录中,重新构建二进制文件并将其flash到您的主板上:

west flash

Without options, the behavior is the same as ninja flash (or make flash, etc.).

没有选项,行为是相同的 ninja flash(或make flash,等)。

To specify the build directory, use --build-dir (or -d):

要指定构建目录,使用 --build-dir (或-d) :

west flash --build-dir path/to/build/directory

If you don’t specify the build directory, west flash searches for one in build, then the current working directory. If you set the build.dir-fmt configuration option (see Setting Source and Build Directories), west flash searches there instead of build.

如果你没有指定构建目录,west flash 会在 build 中搜索一个,然后是当前的 build/工作目录。如果您设置 Build.dir-fmt 配置选项(参见设置 Source 和 Build Directories) ,west flash 将在那里搜索而不是 Build。

Choosing a Runner

If your board’s Zephyr integration supports flashing with multiple programs, you can specify which one to use using the --runner (or -r) option. For example, if West flashes your board with nrfjprog by default, but it also supports JLink, you can override the default with:

如果您的主板的 Zephyr 集成支持多个程序烧录,您可以使用 –runner (或-r)选项指定使用哪一个。例如,如果 West 在默认情况下使用 nrfjprog 来烧录你的主板,但是它也支持 JLink,你可以使用以下命令来覆盖默认值:

west flash --runner jlink

You can override the default flash runner at build time by using the BOARD_FLASH_RUNNER CMake variable, and the debug runner with BOARD_DEBUG_RUNNER.

您可以在构建时使用 BOARD_FLASH_RUNNER CMake 变量覆盖默认的闪存运行程序,并使用 BOARD_DEBUG_RUNNER 覆盖调试运行程序。

For example: 例如:

# Set the default runner to "jlink", overriding the board's
# usual default.
west build [...] -- -DBOARD_FLASH_RUNNER=jlink

See One-Time CMake Arguments and Permanent CMake Arguments for more information on setting CMake arguments.

有关设置 CMake 参数的更多信息,请参见一次性 CMake 参数和永久性 CMake 参数。

See Flash and debug runners below for more information on the runner library used by West. The list of runners which support flashing can be obtained with west flash -H; if run from a build directory or with --build-dir, this will print additional information on available runners for your board.

有关 West 使用的runner程序库的更多信息,请参见下面的 Flash 和 debug 运行程序。支持烧录的runner列表可以通过 west flash -H 获得; 如果从构建目录或 –build-dir 运行,这将为您的板打印可用 runner 的附加信息。

Configuration Overrides 配置重写

The CMake cache contains default values West uses while flashing, such as where the board directory is on the file system, the path to the zephyr binaries to flash in several formats, and more. You can override any of this configuration at runtime with additional options.

CMake 缓存包含 West 在烧录时使用的默认值,例如文件系统中的主板目录、若干格式烧录的 zephyr 二进制文件的路径等等。您可以在运行时使用其他选项重写任何此配置。

For example, to override the HEX file containing the Zephyr image to flash (assuming your runner expects a HEX file), but keep other flash configuration at default values:

例如,为了将包含 Zephyr 镜像的 HEX 文件覆盖到 flash (假设您的运行程序需要一个 HEX 文件) ,但是保持其他 flash 配置为默认值:

west flash --hex-file path/to/some/other.hex

The west flash -h output includes a complete list of overrides supported by all runners.

West flash -h 输出包括所有 runner 支持的完整重写列表。

Runner-Specific Overrides

Each runner may support additional options related to flashing. For example, some runners support an --erase flag, which mass-erases the flash storage on your board before flashing the Zephyr image.

每个 runner 可能支持与烧录有关的附加选项。例如,一些 runner 支持 –erase 标志,它可以在烧录 Zephyr 镜像之前大规模清除你板上的闪存。

To view all of the available options for the runners your board supports, as well as their usage information, use --context (or -H):

要查看所有你的板子支持的 runner 的可用选项,以及他们的使用信息,请使用 –context (或-h) :

west flash --context

Important 重要事项

Note the capital H in the short option name. This re-runs the build in order to ensure the information displayed is up to date!

注意短选项名称中的大写 H。这将重新运行构建,以确保显示的信息是最新的!

When running West outside of a build directory, west flash -H just prints a list of runners. You can use west flash -H -r <runner-name> to print usage information for options supported by that runner.

当在构建目录之外运行 West 时,West flash -H 只打印一个 runner 列表。您可以使用 west flash -H -r <runner-name> 打印该运行程序支持的选项的使用信息

For example, to print usage information about the jlink runner:

例如,打印 jlink runner 的使用信息:

west flash -H -r jlink

Debugging: west debug, west debugserver

Tip 小贴士

Run west debug -h or west debugserver -h for additional help.

运行 west debug-h 或 west debugserver-h 以获得其他帮助。

Basics 基本知识

From a Zephyr build directory, to attach a debugger to your board and open up a debug console (e.g. a GDB session):

从 Zephyr 构建目录中,将调试器附加到您的主板并打开调试控制台(例如 GDB 会话) :

west debug

To attach a debugger to your board and open up a local network port you can connect a debugger to (e.g. an IDE debugger):

要将调试器附加到主板并打开局域网端口,可以将调试器连接到(例如 IDE 调试器) :

west debugserver

Without options, the behavior is the same as ninja debug and ninja debugserver (or make debug, etc.).

如果没有选项,则行为与忍者调试和忍者调试服务器相同(或者进行调试等)。

To specify the build directory, use --build-dir (or -d):

要指定构建目录,使用–build-dir (或-d) :

west debug --build-dir path/to/build/directory
west debugserver --build-dir path/to/build/directory

If you don’t specify the build directory, these commands search for one in build, then the current working directory. If you set the build.dir-fmt configuration option (see Setting Source and Build Directories), west debug searches there instead of build.

如果你没有指定构建目录,这些命令会搜索一个构建目录,然后是当前的工作目录目录。如果您设置 Build.dir-fmt 配置选项(请参阅设置 Source 和 Build Directories) ,则在该选项中使用 west debug 搜索而不是 Build。

Choosing a Runner 选择 runner

If your board’s Zephyr integration supports debugging with multiple programs, you can specify which one to use using the --runner (or -r) option. For example, if West debugs your board with pyocd-gdbserver by default, but it also supports JLink, you can override the default with:

如果您的主板的 Zephyr 集成支持使用多个程序进行调试,则可以使用–runner (或-r)选项指定使用哪个程序。例如,如果 West 在默认情况下使用 pyocd-gdbserver 来调试你的主板,但是它也支持 JLink,你可以使用以下命令来覆盖这个默认命令:

west debug --runner jlink
west debugserver --runner jlink

See Flash and debug runners below for more information on the runner library used by West. The list of runners which support debugging can be obtained with west debug -H; if run from a build directory or with --build-dir, this will print additional information on available runners for your board.

有关 West 使用的运行程序库的更多信息,请参见下面的 Flash 和 debug 运行程序。支持调试的 runner 列表可以通过 west debug-h 获得; 如果从构建目录或–build-dir 运行,这将为您的板打印可用 runner 的附加信息。

Configuration Overrides 配置重写

The CMake cache contains default values West uses for debugging, such as where the board directory is on the file system, the path to the zephyr binaries containing symbol tables, and more. You can override any of this configuration at runtime with additional options.

CMake 缓存包含 West 用于调试的默认值,例如文件系统中的 board 目录、包含符号表的 zephyr 二进制文件的路径等等。您可以在运行时使用其他选项重写任何此配置。

For example, to override the ELF file containing the Zephyr binary and symbol tables (assuming your runner expects an ELF file), but keep other debug configuration at default values:

例如,覆盖包含 Zephyr 二进制和符号表的 ELF 文件(假设您的运行程序需要一个 ELF 文件) ,但保持其他调试配置为默认值:

west debug --elf-file path/to/some/other.elf
west debugserver --elf-file path/to/some/other.elf

The west debug -h output includes a complete list of overrides supported by all runners.

West debug-h 输出包括所有参与者支持的重写的完整列表。

Runner-Specific Overrides

Each runner may support additional options related to debugging. For example, some runners support flags which allow you to set the network ports used by debug servers.

每个运行程序可能支持与调试相关的其他选项。例如,一些运行程序支持允许您设置调试服务器使用的网络端口的标志。

To view all of the available options for the runners your board supports, as well as their usage information, use --context (or -H):

要查看所有你的板子支持的 runner 的可用选项,以及他们的使用信息,请使用–context (或-h) :

west debug --context

(The command west debugserver --context will print the same output.)

(命令 west debugserver –context 将打印相同的输出。)

Important

重要事项

Note the capital H in the short option name. This re-runs the build in order to ensure the information displayed is up to date!

注意短选项名称中的大写 h。这将重新运行构建,以确保显示的信息是最新的!

When running West outside of a build directory, west debug -H just prints a list of runners. You can use west debug -H -r <runner-name> to print usage information for options supported by that runner.

在构建目录之外运行 West 时,West debug-h 只打印运行器列表。您可以使用 west debug-h-r < runner-name > 打印该运行程序支持的选项的使用信息。

For example, to print usage information about the jlink runner:

例如,打印 jlink runner 的使用信息:

west debug -H -r jlink

Flash and debug runners 闪存和调试运行程序

The flash and debug commands use Python wrappers around various Flash & Debug Host Tools. These wrappers are all defined in a Python library at scripts/west_commands/runners. Each wrapper is called a runner. Runners can flash and/or debug Zephyr programs.

Flash 和 Debug 命令使用各种 Flash 和 Debug 主机工具的 Python 包装器。这些包装器都在脚本/west _ commands/runners 的 Python 库中定义。每个包装器称为一个运行器。运行者可以闪存和/或调试 Zephyr 程序。

The central abstraction within this library is ZephyrBinaryRunner, an abstract class which represents runners. The set of available runners is determined by the imported subclasses of ZephyrBinaryRunner. ZephyrBinaryRunner is available in the runners.core module; individual runner implementations are in other submodules, such as runners.nrfjprog, runners.openocd, etc.

这个库中的中心抽象是 ZephyrBinaryRunner,一个表示 runner 的抽象类。可用 runner 的集合由 ZephyrBinaryRunner 的导入子类决定。可以在 runners.core 模块中使用 ZephyrBinaryRunner; 单个的 runner 实现可以在其他子模块中使用,比如 runners.nrfjprog、 runners.openocd 等。

Hacking 黑客

This section documents the runners.core module used by the flash and debug commands. This is the core abstraction used to implement support for these features.

本节记录 flash 和调试命令使用的 runners.core 模块。这是用于实现对这些特性支持的核心抽象。

Warning

警告

These APIs are provided for reference, but they are more “shared code” used to implement multiple extension commands than a stable API.

这些 API 是提供给参考的,但它们更多的是用于实现多个扩展命令的“共享代码”,而不是一个稳定的 API。

Developers can add support for new ways to flash and debug Zephyr programs by implementing additional runners. To get this support into upstream Zephyr, the runner should be added into a new or existing runners module, and imported from runners/__init__.py.

开发人员可以通过实现其他 runner 来增加对闪存和调试 Zephyr 程序的新方法的支持。为了获得上游 Zephyr 的支持,应该将 runner 添加到一个新的或现有的 runner 模块中,并从 runner /_ init _ 导入。Py.

Note

注意

The test cases in scripts/west_commands/tests add unit test coverage for the runners package and individual runner classes.

Scripts/west _ commands/tests 中的测试用例为 runner 包和单个 runner 类增加了单元测试覆盖率。

Please try to add tests when adding new runners. Note that if your changes break existing test cases, CI testing on upstream pull requests will fail.

请在添加新的 runner 时尝试添加测试。注意,如果您的更改破坏了现有的测试用例,那么在上游拉请求上的 CI 测试将会失败。

Doing it By Hand 手工操作

If you prefer not to use West to flash or debug your board, simply inspect the build directory for the binaries output by the build system. These will be named something like zephyr/zephyr.elf, zephyr/zephyr.hex, etc., depending on your board’s build system integration. These binaries may be flashed to a board using alternative tools of your choice, or used for debugging as needed, e.g. as a source of symbol tables.

如果您不愿意使用 West 来闪存或调试您的主板,只需要检查构建系统输出的二进制文件的构建目录。这些将被命名为 zephyr/zephyr.elf,zephyr/zephyr.hex 等等,这取决于您的主板的构建系统集成。这些二进制文件可以使用您选择的替代工具闪到一块板上,或者根据需要用于调试,例如作为一个符号表源。

By default, these West commands rebuild binaries before flashing and debugging. This can of course also be accomplished using the usual targets provided by Zephyr’s build system (in fact, that’s how these commands do it).

默认情况下,这些 West 命令在烧录和调试之前重新构建二进制文件。当然,也可以使用 Zephyr 的构建系统提供的通常目标(事实上,这些命令就是这样做的)来实现这一点。