West documentation #860
Draft
West documentation #860
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This covers its design and scope, and provides usage and some implementation documentation on the existing flashing and debugging commands. Signed-off-by: Marti Bolivar <[email protected]>
Update to the latest west. This includes a new 'attach' command. There are also multi-repo commands, but those won't get exposed to the user unless they install Zephyr using "west init" + "west fetch" (and not, say, "git clone"). Replace the launchers; they now detect whether zephyr is part of a multi-repo installation, and run the west code in its own repository if that is the case. This also requires an update to: - the flash/debug CMakeLists.txt, as the new west package is no longer executable as a module and must have its main script run by the interpreter instead. - the documentation, to reflect a rename and with a hack to fix the automodule directive in flash-debug.rst for now Signed-off-by: Marti Bolivar <[email protected]>
Explain multi-repo concepts like manifests and projects, give an overview of the currently implemented commands, and give an example of a potential workflow. There's no way to submit a multi-repo change for review yet, so this is still experimental. Signed-off-by: Ulf Magnusson <[email protected]>
With the new theme we are able to have more section in the top level. Move things around and expose the most important sections in the top table of content. Signed-off-by: Anas Nashif <[email protected]>
Since west is no longer part of the Zephyr tree, we can no longer hardcode its path anymore. Instead, use west itself to retrieve its path, in order to point the documentation build to the correct active west installation. This is optional, and the documentation build will still work if west is not installed on the system. Signed-off-by: Carles Cufi <[email protected]>
Since west is no longer included in the Zephyr repository, instruct users to install and use west in order to obtain the Zephyr source code. Signed-off-by: Carles Cufi <[email protected]> Signed-off-by: Torsten Rasmussen <[email protected]>
West documentation files now belong in doc/tools/west and not doc/west. Signed-off-by: Carles Cufi <[email protected]>
Overhaul the west documentation so that it matches the model that is currently implemented in the west repository. This model is no longer subject to change in the short or mid term, since it has been selected as the only viable one for multi-repo management using west. Signed-off-by: Carles Cufi <[email protected]>
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 <[email protected]>
In order to be able to merge the topic branch, we require a few fixes to CI. Signed-off-by: Anas Nashif <[email protected]> Signed-off-by: Carles Cufi <[email protected]>
Miscellaneous formatting fixes in the west documentation. Signed-off-by: Carles Cufi <[email protected]>
In case west is not present or was not used to initialize the local zephyr repository, avoid failing the documentation build by including a placeholder file. Signed-off-by: Carles Cufi <[email protected]>
Reorganize the entry page so it's not as jarring of a landing by reorganizing the content a bit in the rest of the toctree. This makes it easier to read more progressively without having to jump around as much. Signed-off-by: Marti Bolivar <[email protected]>
Fix some correctness issues. Signed-off-by: Marti Bolivar <[email protected]>
Move guides and APIs into separate directories and cleanup naming introducing index files rather than named section files. Signed-off-by: Anas Nashif <[email protected]>
Document the `west build` command in the section corresponding to the west commands that deal with the CMake cache, which is now named "Building, flashing and debugging" for consistency. Signed-off-by: Carles Cufi <[email protected]>
In order to simplify the usage of `west build`, take a positional argument with the source directory instead of requiring the `-s, --source-dir` flag. This makes it easier and quicker to invoke west when building, as well as being consistent with CMake. Signed-off-by: Carles Cufi <[email protected]>
A new role :zephyr_file: is available that renders to a link to the file or folder in GitHub. Find appropriate references using :file: and convert to :zephyr_file: to take advantage of its linking capability. Signed-off-by: David B. Kinder <[email protected]>
Fixes a typo in board_porting.rst Fixes wrong syntax for file markup element in build-flash-debug.rst Signed-off-by: Suryansh Sharma <[email protected]>
Fix misspellings missed during regular reviews. Signed-off-by: David B. Kinder <[email protected]>
- add glossary terms for important concepts we have to explain often, like "west installation" - add autodoc directives for pulling in west API docs - add missing documentation for built-in features like west's configuration, extension commands, etc. - add missing documentation for "west sign" extension - describe the manifest in a self-contained way rather than linking to the relevant pykwalify schema, also adding a missing reference to "west manifest" in the miscellaneous multi-repo commands list - move various details regarding history and motivation to why.rst among other changes to repo-tool.rst, leaving it closer to a "tell me what I really need to know" style overview - update planned features Fixes: #14992 Signed-off-by: Marti Bolivar <[email protected]>
Add a missing reference to how west is used to set ZEPHYR_MODULES in without-west.rst, augmenting the application development guide a bit to include this in the list of important variables, cleaning that up a bit while we are here and adding some more west details. Add a big fat warning in the getting started guide that using Zephyr without west is not for the faint of heart. Signed-off-by: Marti Bolivar <[email protected]>
This commit extends existing documentation by providing an example of how to build Hello World sample application for MCUboot using west. Signed-off-by: Piotr Mienkowski <[email protected]>
All docs should have a label at the top that would permit cross-document linking via :ref:`labelname`. Update "testing" label that would have conflicted and fix the only reference to the old "testing" label in development process documentation. Signed-off-by: David B. Kinder <[email protected]>
Add a new command-line and build config option, `pristine`, that the user can pass to `west build` or set in its configuration file(s) in order to automatically trigger a pristine build on every build or whenever west considers it required. The option can take the following values: - never: Never run the target - always: Always run the pristine target before building - auto: Run the pristine target when required With `auto`, the pristine target will be run when running west with an existing build folder containing a build system and: - Selecting a different board from the one currently in the build system - Selecting a different application from the one currently in the build system Signed-off-by: Carles Cufi <[email protected]>
When making a build folder pristine until now we were running the 'pristine' build target. The issue with that is that ninja/make or whatever build tool is being used might decide to re-run CMake itself if some of the dependencies have changes. This might trigger an error that is unfriendly and unnecessary, since the user is explicitly asking for the build folder to be wiped before starting a fresh build. To avoid this issue restor to running directly the CMake script that the 'pristine' build target itself uses, so as to make sure that the build folder is wiped unconditionally regardless of changes made to the tree. Signed-off-by: Carles Cufi <[email protected]>
Add a new "boards" command that is able to list all the boards in the upstream tree. There is currently no support for out-of-tree boards. The command executes cmake to use the built-in CMake script, boards.cmake, to list the boards, and then stores the information retrieved and allows the user to present it in a user-definable format. Fixes zephyrproject-rtos#53 Signed-off-by: Carles Cufi <[email protected]>
- Respect the BOARD environment setting. - Don't require --force if the board can't be figured out: it might be set in CMakeLists.txt, for example. Instead, downgrade to a warning which can be disabled with "west config build.board_warn false". - Add a build.board configuration option used as a final BOARD fallback after CACHED_BOARD (in the CMake cache), --board (command line), and BOARD (environment). - Keep the config docs up to date. Signed-off-by: Marti Bolivar <[email protected]>
Try to make the language simpler. Introduce each example with a paragraph that says "To <DO XYZ>" to make them easier to find. Move the config options to the documentation for that command to make them easier to find. Add some more examples for use cases we've gotten questions about. Signed-off-by: Marti Bolivar <[email protected]>
This can be used to override the default CMake generator permanently. Its values are the same as those acceptable to cmake's -G option. Signed-off-by: Marti Bolivar <[email protected]>
Add an example west alias for automatically excluding certain platforms when running Twister via west. This is especially useful for excluding the 32-bit native_sim target when running on hosts systems without a 32-bit host C library (i.e. Linux/AArch64). Signed-off-by: Henrik Brix Andersen <[email protected]>
When building in CI for specific SOCs, it's useful to only have `west blobs fetch` pull a selected set of blob objects. This is especially helpful on `hal_espressif`, which currently has 78 blob objects. Add a `--allow-regex` arg to the `west blobs fetch` subcommand to filter only specified blobs, for example: ```bash # only download esp32 blobs, skip the other variants ❯ west blobs fetch hal_espressif --allow-regex 'lib/esp32/.*' ``` Also, replace all `str.format()` invocations with f-strings per review feedback. Signed-off-by: Noah Pendleton <[email protected]>
west 0.6.0 and 0.7.0 were released in 2019 and 2020 ; keeping troubleshooting information for these versions is not needed anymore (there isn't even a currently maintained LTS that would remotely be concerned by this). Signed-off-by: Benjamin Cabé <[email protected]>
Converting a "pre-west" Zephyr setup is not something we officially support anymore so drop associated documentation. Signed-off-by: Benjamin Cabé <[email protected]>
Add a section to the west release notes for v1.5.0. Signed-off-by: Pieter De Gendt <[email protected]>
Add an entry to the west configuration table for auto-cache. Signed-off-by: Pieter De Gendt <[email protected]>
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #860 +/- ##
=======================================
Coverage 84.44% 84.44%
=======================================
Files 11 11
Lines 3394 3394
=======================================
Hits 2866 2866
Misses 528 528 |
mbolivar
reviewed
Oct 7, 2025
Contributor
mbolivar
left a comment
mbolivar
left a comment
There was a problem hiding this comment.
Cool! I saw y'all had plans about this in @carlescufi's talk at ZDS, excited to see it.
Merged
mbolivar
reviewed
Oct 7, 2025
doc/index.rst
Outdated
| @@ -0,0 +1,55 @@ | |||
| .. _west: | |||
|
|
|||
| West (Zephyr's meta-tool) | |||
Contributor
There was a problem hiding this comment.
If part of the reason for this is that west is big enough to deserve its own documentation separate from zephyr, perhaps it's finally time to revisit this tag line.
Personally, I think "West: an extensible workspace manager" is more descriptive for the standalone tool itself. What do you think @marc-hb @pdgendt ?
Add a west config option to skip rebuilds by default or not when doing west flash. Also add corresponding symmetrical CLI options. Signed-off-by: Declan Snyder <[email protected]>
Add a new 'west bindesc extract' subcommand that dumps all binary descriptors into a separate binary file. It will also report the range (offset and length) of the dumped data within the original image. Signed-off-by: Luca Burelli <[email protected]>
new format arguments for config option build.dir-fmt are documented accordingly. Signed-off-by: Thorsten Klein <[email protected]>
Collaborator
|
We do not have to lose the history, attribution, git blame etc. See below. The pipx install git-filter-repo # or https://github.com/newren/git-filter-repo/ - I used today's main which I already had for other reasons.
cd /tmp
git clone zephyr
git clone west
cd zephyr/
time ~/git-filter-repo/git-filter-repo --path doc/develop/west --path doc/guides/west --path doc/tools/west --path doc/west
# => less than 10 seconds
git mv doc/develop/west doc/; git commit ...
cd ../west
du -sh .git/ # 21M
git fetch ../zephyr/ main
du -sh .git/ # 21M => near zero disk cost. Only 217 commits with just plain text docs.
git merge --allow-unrelated-histories FETCH_HEAD |
Collaborator
Just in case anyone finds this git feature scary: I did exactly this in thesofproject/sof@fd497c906a41 and thesofproject/sof#8297 and there was no issue whatsoever. Most people did not even notice. |
Add the sphinx package to a separate dependency group. Signed-off-by: Pieter De Gendt <[email protected]>
Transfer the west documentation from the Zephyr doc/develop/west directory to the West doc/ location. Signed-off-by: Pieter De Gendt <[email protected]>
pdgendt
force-pushed
the
docs
branch
2 times, most recently
from
e85502d to
57acf19
Compare
Remove files that document west extensions from the Zephyr repository. Signed-off-by: Pieter De Gendt <[email protected]>
pdgendt
force-pushed
the
docs
branch
3 times, most recently
from
29c8568 to
2eebb71
Compare
Add necessary sphinx files to build the West documentation. Signed-off-by: Pieter De Gendt <[email protected]>
Update documentation content for West. Signed-off-by: Pieter De Gendt <[email protected]>
Build the documentation as part of CI. Signed-off-by: Pieter De Gendt <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
43 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
WIP