With the documentation for west 0.9, the 'basics' page is completely
out of control. Reorganize it so it fits in a few pages, moving many
details out into other pages for the truly curious.
As part of this, create new pages for built-in commands (built-in.rst)
and esoteric details about workspaces (workspaces.rst).
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
This is a new feature that allows you to associate projects with
groups, then force west to ignore a subset of the projects list by
disabling project groups. This can be selectively overridden via
configuration file to make west stop ignoring the projects within an
individual workspace.
An example use case is to define a project whose Git repository
requires credentials to pull. Putting such a project in a group named
"foo" and disabling group "foo" would make "west update" ignore the
project unless the user specifically configures the workspace to allow
"foo". After that, "west update" will pull the project as usual.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
Various improvements to the west repo-tool.rst page and pages that
link to it:
Rename the page title to "Basics", since it documents, well the
basics, including built-in commands like "help" an "config" that are
not directly related to multiple repositories.
The "multi-repo" term was invented before we started using
"workspace". Drop it from the text and rework things using words like
"workspace", "basics", or "built-ins" instead, which read better.
We've been using west for a long enough time that justifying its
existence prominently at the start of this page is no longer
necessary; move that to the "dustbin of history" page (why.rst).
Try harder to clarify exactly what a "project" is, along with other
workspace related clarifications.
Improve the documentation for the west init and west update commands,
and create :ref: targets for linking directly to them for convenience
elsewhere in the docs.
Slim down the usages for other built-in commands, so we don't have to
keep those up to date as carefully each release. This is about to be
important for west 0.9, which is going to change the detailed
semantics for the "[PROJECT ...]" part of each command synopsis in a
way that will be inconvenient to duplicate for each of these.
Move the "Topologies supported" content lower down. Try to help the
reading flow by letting people get familiar with a workspace and what
you can do with it using the Zephyr GSG workspace that they probably
already have before overwhelming them with other possibilities and
choices.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
This nomenclature change was done in west 0.7 because it seems to be a
lot easier for people to understand. Propagate it to all the west
documentation.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
West v0.6.1 has been released. The main feature is that "west update"
now avoids communicating with the network by default when project
revisions have already been fetched.
This allows for offline operation and significantly speeds up the
command (it's 10 times faster on my machine and home network).
There are other miscellaneous changes as well; document them also.
Signed-off-by: Marti Bolivar <marti.bolivar@nordicsemi.no>
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 <marti.bolivar@nordicsemi.no>
- 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 <marti.bolivar@nordicsemi.no>
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 <carles.cufi@nordicsemi.no>
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 <carles.cufi@nordicsemi.no>
- 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 <marti@foundries.io>
