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
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #860 +/- ##
=======================================
Coverage 84.93% 84.93%
=======================================
Files 11 11
Lines 3444 3444
=======================================
Hits 2925 2925
Misses 519 519 |
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 ?
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. |
pdgendt
force-pushed
the
docs
branch
6 times, most recently
from
2eebb71 to
bbbf70d
Compare
Add the sphinx package to a separate dependency group. Signed-off-by: Pieter De Gendt <[email protected]>
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]>
Windows powershell can by default not autocomplete known boards when tapping which can cause frustration when you can't quite remember the exact name or you don't want to type it out. west build .\path\to\application\ -p -b stm<tab> will search for available board including 'stm' in their name. Signed-off-by: Tais Hjortshøj <[email protected]>
when following the example it was not clear that BUILD_DIR needs to point to application for sysbuild builds Signed-off-by: Tobias Meyer <[email protected]>
Add documentation for the `west patch` command. Signed-off-by: Chris Friedt <[email protected]>
Add release notes for v1.3.0 and v1.4.0. Signed-off-by: Pieter De Gendt <[email protected]>
Update the west API documentation for the added active_only arguments to as_dict/as_frozen_dict/as_yaml/as_frozen_yaml. Signed-off-by: Pieter De Gendt <[email protected]>
s/manidest/manifest. Signed-off-by: Carles Cufi <[email protected]>
When support for SPDX 2.3 was added, it effectively dropped support for SPDX 2.2, which in retrospect was a bad idea since SPDX 2.2 is the version that is the current ISO/IEC standard. This commit adds a `--spdx-version` option to the `west spdx` command so that users can generate SPDX 2.2 documents if they want. Default is 2.3 given that's effectively what shipped for a few releases now, including latest LTS. Signed-off-by: Benjamin Cabé <[email protected]>
Generating SPDX SBOMs for the ``native_sim`` platform has propably never worked, but at least now it will be documented. Signed-off-by: Benjamin Cabé <[email protected]>
use REUSE to extract copyright text from source files and include in SBOM documents Signed-off-by: Benjamin Cabé <[email protected]>
Add the relevant documentation for the silabs_commander runner. Co-developed-by: Aasim Shaik <[email protected]> Signed-off-by: Aasim Shaik <[email protected]> Signed-off-by: Jérôme Pouiller <[email protected]>
update a couple of links to use https instead of http Signed-off-by: Thomas Stranger <[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]>
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]>
Transfer the west documentation from the Zephyr doc/develop/west directory to the West doc/ location. Signed-off-by: Pieter De Gendt <[email protected]>
Remove files that document west extensions from the Zephyr repository. Signed-off-by: Pieter De Gendt <[email protected]>
kartben
reviewed
Dec 2, 2025
pdgendt
force-pushed
the
docs
branch
2 times, most recently
from
8344c0f to
63ea53f
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
20 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