doc: west: 0.7.0 documentation
Reflect changes in the APIs made since 0.6.0. These will also need to be added to the release notes. Some automatic directives weren't generating the desired output, so either do it by hand or let new 0.7.0 docstrings supply the information. Try to better group the content into sections. Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
This commit is contained in:
parent
c20a081423
commit
b4fde33243
6 changed files with 282 additions and 97 deletions
|
@ -27,7 +27,7 @@ You can run ``west --help`` (or ``west -h`` for short) to get top-level help
|
|||
for available west commands, and ``west <command> -h`` for detailed help on
|
||||
each command.
|
||||
|
||||
The following pages document west's ``v0.6.x`` releases, and provide additional
|
||||
The following pages document west's ``v0.7.x`` releases, and provide additional
|
||||
context about the tool.
|
||||
|
||||
.. toctree::
|
||||
|
@ -45,7 +45,6 @@ context about the tool.
|
|||
zephyr-cmds.rst
|
||||
why.rst
|
||||
without-west.rst
|
||||
planned.rst
|
||||
release-notes.rst
|
||||
|
||||
For details on west's Python APIs, see :ref:`west-apis`.
|
||||
|
|
|
@ -89,6 +89,7 @@ top-level ``manifest`` section with some subsections, like this:
|
|||
self:
|
||||
# configuration related to the manifest repository itself,
|
||||
# i.e. the repository containing west.yml (optional)
|
||||
version: <schema-version> # optional
|
||||
|
||||
In YAML terms, the manifest file contains a mapping, with a ``manifest``
|
||||
key. Any other keys and their contents are ignored (west v0.5 also required a
|
||||
|
@ -249,7 +250,7 @@ so far using ``defaults`` is:
|
|||
url: https://github.com/user/project-three
|
||||
revision: abcde413a111
|
||||
|
||||
Finally, the ``self`` subsection can be used to control the behavior of the
|
||||
The ``self`` subsection can be used to control the behavior of the
|
||||
manifest repository itself. Its value is a map with the following keys:
|
||||
|
||||
- ``path``: Optional. The path to clone the manifest repository into, relative
|
||||
|
@ -283,8 +284,27 @@ zephyr repository does contain extension commands, its ``self`` entry declares
|
|||
the location of the corresponding :file:`west-commands.yml` relative to the
|
||||
repository root.
|
||||
|
||||
.. _west-manifest-schema-version:
|
||||
|
||||
The ``version`` subsection can be used to mark the lowest version of the
|
||||
manifest file schema that can parse this file's data:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
manifest:
|
||||
version: 0.7
|
||||
# marks that this manifest uses features available in west 0.7 and
|
||||
# up, like manifest imports
|
||||
|
||||
The pykwalify schema :file:`manifest-schema.yml` in the west source code
|
||||
repository is used to validate the manifest section.
|
||||
repository is used to validate the manifest section. The current manifest
|
||||
``version`` is 0.7, which corresponds to west version 0.7. This is the only
|
||||
value this field can currently take.
|
||||
|
||||
If a later version of west, say version ``21.0``, includes changes to the
|
||||
manifest schema that cannot be parsed by west 0.7, then setting ``version:
|
||||
21.0`` will cause west to print an error when attempting to parse the manifest
|
||||
data.
|
||||
|
||||
.. _west-manifest-import:
|
||||
|
||||
|
|
|
@ -1,24 +0,0 @@
|
|||
.. _west-planned-features:
|
||||
|
||||
Planned Features
|
||||
================
|
||||
|
||||
Additional west features are under development for future versions of
|
||||
Zephyr. These include:
|
||||
|
||||
- Multiple manifest files: support for having multiple files which have
|
||||
manifest data, instead of the single :file:`west.yml` supported today.
|
||||
See `west #221`_.
|
||||
|
||||
- Toolchain awareness: see `west #180`_.
|
||||
|
||||
See the `west repository issues`_ page for more.
|
||||
|
||||
.. _west #221:
|
||||
https://github.com/zephyrproject-rtos/west/issues/221
|
||||
|
||||
.. _west #180:
|
||||
https://github.com/zephyrproject-rtos/west/issues/180
|
||||
|
||||
.. _west repository issues:
|
||||
https://github.com/zephyrproject-rtos/west/issues
|
|
@ -1,6 +1,84 @@
|
|||
West Release Notes
|
||||
##################
|
||||
|
||||
v0.7.0
|
||||
******
|
||||
|
||||
The main user-visible feature in west 0.7 is the :ref:`west-manifest-import`
|
||||
feature. This allows users to load west manifest data from multiple different
|
||||
files, resolving the results into a single logical manifest.
|
||||
|
||||
Additional user-visible changes:
|
||||
|
||||
- The idea of a "west installation" has been renamed to "west workspace" in
|
||||
this documentation and in the west API documentation. The new term seems to
|
||||
be easier for most people to work with than the old one.
|
||||
- West manifests now support a :ref:`schema version
|
||||
<west-manifest-schema-version>`.
|
||||
- The "west config" command can now be run outside of a workspace, e.g.
|
||||
to run ``west config --global section.key value`` to set a configuration
|
||||
option's value globally.
|
||||
- There is a new :ref:`west topdir <west-multi-repo-misc>` command, which
|
||||
prints the root directory of the current west workspace.
|
||||
- The ``west -vv init`` command now prints the git operations being performed,
|
||||
and their results.
|
||||
- The restriction that no project can be named "manifest" is now enforced; the
|
||||
name "manifest" is reserved for the manifest repository, and is usable as
|
||||
such in commands like ``west list manifest``, instead of ``west list
|
||||
path-to-manifest-repository`` being the only way to say that
|
||||
- It's no longer an error if there is no project named "zephyr". This is
|
||||
part of an effort to make west generally usable for non-Zephyr use cases.
|
||||
- Various bug fixes.
|
||||
|
||||
The developer-visible changes to the :ref:`west-apis` are:
|
||||
|
||||
- west.build and west.cmake: deprecated; this is Zephyr-specific functionality
|
||||
and should never have been part of west. Since Zephyr v1.14 LTS relies on it,
|
||||
it will continue to be included in the distribution, but will be removed
|
||||
when that version of Zephyr is obsoleted.
|
||||
- west.commands:
|
||||
|
||||
- WestCommand.requires_installation: deprecated; use requires_workspace instead
|
||||
- WestCommand.requires_workspace: new
|
||||
- WestCommand.has_manifest: new
|
||||
- WestCommand.manifest: this is now settable
|
||||
- west.configuration: callers can now identify the workspace directory
|
||||
when reading and writing configuration files
|
||||
- west.log:
|
||||
|
||||
- msg(): new
|
||||
- west.manifest:
|
||||
|
||||
- The module now uses the standard logging module instead of west.log
|
||||
- QUAL_REFS_WEST: new
|
||||
- SCHEMA_VERSION: new
|
||||
- Defaults: removed
|
||||
- Manifest.as_dict(): new
|
||||
- Manifest.as_frozen_yaml(): new
|
||||
- Manifest.as_yaml(): new
|
||||
- Manifest.from_file() and from_data(): these factory methods are more
|
||||
flexible to use and less reliant on global state
|
||||
- Manifest.validate(): new
|
||||
- ManifestImportFailed: new
|
||||
- ManifestProject: semi-deprecated and will likely be removed later.
|
||||
- Project: the constructor now takes a topdir argument
|
||||
- Project.format() and its callers are removed. Use f-strings instead.
|
||||
- Project.name_and_path: new
|
||||
- Project.remote_name: new
|
||||
- Project.sha() now captures stderr
|
||||
- Remote: removed
|
||||
|
||||
West now requires Python 3.6 or later. Additionally, some features may rely on
|
||||
Python dictionaries being insertion-ordered; this is only an implementation
|
||||
detail in CPython 3.6, but is is part of the language specification as of
|
||||
Python 3.7.
|
||||
|
||||
v0.6.3
|
||||
******
|
||||
|
||||
This point release fixes an error in the behavior of the deprecated
|
||||
``west.cmake`` module.
|
||||
|
||||
v0.6.2
|
||||
******
|
||||
|
||||
|
|
|
@ -262,6 +262,17 @@ Miscellaneous Commands
|
|||
West has a few more commands for managing the multi-repo, which are briefly
|
||||
discussed here. Run ``west <command> -h`` for detailed help.
|
||||
|
||||
- ``west forall -c COMMAND [PROJECT ...]``: Runs the shell command ``COMMAND``
|
||||
within the top-level repository directory of each of the specified projects
|
||||
(default: all cloned projects). If ``COMMAND`` consists of more than one
|
||||
word, it must be quoted to prevent it from being split up by the shell.
|
||||
|
||||
To run an arbitrary Git command in each project, use something like ``west
|
||||
forall -c 'git <command> --options'``. Note that ``west forall`` can be used
|
||||
to run any command, though, not just Git commands.
|
||||
|
||||
- ``west help <command>``: this is equivalent to ``west <command> -h``.
|
||||
|
||||
- ``west list [-f FORMAT] [PROJECT ...]``: Lists project information from the
|
||||
manifest file, such as URL, revision, path, etc. The printed information can
|
||||
be controlled using the ``-f`` option.
|
||||
|
@ -278,16 +289,7 @@ discussed here. Run ``west <command> -h`` for detailed help.
|
|||
- ``west status [PROJECT ...]``: Like ``west diff``, for
|
||||
running ``git status``.
|
||||
|
||||
- ``west forall -c COMMAND [PROJECT ...]``: Runs the shell command ``COMMAND``
|
||||
within the top-level repository directory of each of the specified projects
|
||||
(default: all cloned projects). If ``COMMAND`` consists of more than one
|
||||
word, it must be quoted to prevent it from being split up by the shell.
|
||||
|
||||
To run an arbitrary Git command in each project, use something like ``west
|
||||
forall -c 'git <command> --options'``. Note that ``west forall`` can be used
|
||||
to run any command, though, not just Git commands.
|
||||
|
||||
- ``west help <command>``: this is equivalent to ``west <command> -h``.
|
||||
- ``west topdir``: Prints the top directory of the west workspace.
|
||||
|
||||
.. _PyPI:
|
||||
https://pypi.org/project/west/
|
||||
|
|
|
@ -15,6 +15,8 @@ the zephyr repository.
|
|||
These APIs should be considered unstable until west version 1.0 (see `west
|
||||
#38`_).
|
||||
|
||||
.. _west #38:
|
||||
https://github.com/zephyrproject-rtos/west/issues/38
|
||||
|
||||
**Contents**:
|
||||
|
||||
|
@ -37,29 +39,11 @@ All built-in and extension commands are implemented as subclasses of the
|
|||
:py:class:`WestCommand` class defined here. Some exception types are also
|
||||
provided.
|
||||
|
||||
WestCommand
|
||||
===========
|
||||
|
||||
.. py:class:: west.commands.WestCommand
|
||||
|
||||
.. automethod:: __init__
|
||||
|
||||
.. versionadded:: 0.6.0
|
||||
The *requires_installation* parameter.
|
||||
|
||||
Methods:
|
||||
|
||||
.. automethod:: run
|
||||
|
||||
.. versionchanged:: 0.6.0
|
||||
The *topdir* argument was added.
|
||||
|
||||
.. automethod:: add_parser
|
||||
|
||||
All subclasses must provide the following abstract methods, which are used
|
||||
to implement the above:
|
||||
|
||||
.. automethod:: do_add_parser
|
||||
|
||||
.. automethod:: do_run
|
||||
|
||||
Instance attributes:
|
||||
|
||||
.. py:attribute:: name
|
||||
|
@ -78,10 +62,12 @@ provided.
|
|||
|
||||
As passed to the constructor.
|
||||
|
||||
.. py:attribute:: requires_installation
|
||||
.. py:attribute:: requires_workspace
|
||||
|
||||
As passed to the constructor.
|
||||
|
||||
.. versionadded:: 0.7.0
|
||||
|
||||
.. py:attribute:: parser
|
||||
|
||||
The argument parser created by calling ``WestCommand.add_parser()``.
|
||||
|
@ -90,11 +76,46 @@ provided.
|
|||
|
||||
.. py:attribute:: manifest
|
||||
|
||||
A read-only property which returns the :py:class:`west.manifest.Manifest`
|
||||
A property which returns the :py:class:`west.manifest.Manifest`
|
||||
instance for the current manifest file or aborts the program if one was
|
||||
not provided. This is only safe to use from the ``do_run()`` method.
|
||||
|
||||
.. versionadded:: 0.6.1
|
||||
.. versionchanged:: 0.7.0
|
||||
This is now settable.
|
||||
|
||||
.. py:attribute:: has_manifest
|
||||
|
||||
True if reading the manifest property will succeed instead of erroring
|
||||
out.
|
||||
|
||||
Constructor:
|
||||
|
||||
.. automethod:: __init__
|
||||
|
||||
.. versionadded:: 0.6.0
|
||||
The *requires_installation* parameter.
|
||||
.. versionadded:: 0.7.0
|
||||
The *requires_workspace* parameter.
|
||||
|
||||
Methods:
|
||||
|
||||
.. automethod:: run
|
||||
|
||||
.. versionchanged:: 0.6.0
|
||||
The *topdir* argument was added.
|
||||
|
||||
.. automethod:: add_parser
|
||||
|
||||
All subclasses must provide the following abstract methods, which are used
|
||||
to implement the above:
|
||||
|
||||
.. automethod:: do_add_parser
|
||||
|
||||
.. automethod:: do_run
|
||||
|
||||
Exceptions
|
||||
==========
|
||||
|
||||
.. autoclass:: west.commands.CommandError
|
||||
:show-inheritance:
|
||||
|
@ -106,18 +127,6 @@ provided.
|
|||
.. autoclass:: west.commands.CommandContextError
|
||||
:show-inheritance:
|
||||
|
||||
.. autoclass:: west.commands.ExtensionCommandError
|
||||
:show-inheritance:
|
||||
|
||||
.. py:method:: ExtensionCommandError.__init__(hint=None, **kwargs)
|
||||
|
||||
If *hint* is given, it is a string indicating the cause of the problem.
|
||||
All other kwargs are passed to the super constructor.
|
||||
|
||||
.. py:attribute:: hint
|
||||
|
||||
As passed to the constructor.
|
||||
|
||||
.. _west-apis-configuration:
|
||||
|
||||
west.configuration
|
||||
|
@ -125,7 +134,10 @@ west.configuration
|
|||
|
||||
.. automodule:: west.configuration
|
||||
|
||||
.. autoclass:: west.configuration.ConfigFile
|
||||
This provides API access to west configuration files and data.
|
||||
|
||||
Reading and writing options
|
||||
===========================
|
||||
|
||||
.. autofunction:: west.configuration.read_config
|
||||
|
||||
|
@ -134,6 +146,11 @@ west.configuration
|
|||
|
||||
.. autofunction:: west.configuration.update_config
|
||||
|
||||
.. autoclass:: west.configuration.ConfigFile
|
||||
|
||||
Global configuration instance
|
||||
=============================
|
||||
|
||||
.. py:data:: west.configuration.config
|
||||
|
||||
Module-global ConfigParser instance for the current configuration. This
|
||||
|
@ -146,7 +163,42 @@ west.log
|
|||
********
|
||||
|
||||
.. automodule:: west.log
|
||||
:members: set_verbosity, VERBOSE_NONE, VERBOSE_NORMAL, VERBOSE_VERY, VERBOSE_EXTREME, dbg, inf, wrn, err, die, banner, small_banner
|
||||
|
||||
This module's functions are used whenever a running west command needs to print
|
||||
to standard out or error streams.
|
||||
|
||||
This is safe to use from extension commands if you want output that mirrors
|
||||
that of west itself.
|
||||
|
||||
Verbosity control
|
||||
=================
|
||||
|
||||
To set the global verbosity level, use ``set_verbosity()``.
|
||||
|
||||
.. autofunction:: set_verbosity
|
||||
|
||||
These verbosity levels are defined.
|
||||
|
||||
.. autodata:: VERBOSE_NONE
|
||||
.. autodata:: VERBOSE_NORMAL
|
||||
.. autodata:: VERBOSE_VERY
|
||||
.. autodata:: VERBOSE_EXTREME
|
||||
|
||||
Output functions
|
||||
================
|
||||
|
||||
The main functions are ``dbg()``, ``inf()``, ``wrn()``, ``err()``, and
|
||||
``die()``. Two special cases of ``inf()``, ``banner()`` and ``small_banner()``,
|
||||
are also available for grouping output into "sections".
|
||||
|
||||
.. autofunction:: dbg
|
||||
.. autofunction:: inf
|
||||
.. autofunction:: wrn
|
||||
.. autofunction:: err
|
||||
.. autofunction:: die
|
||||
|
||||
.. autofunction:: banner
|
||||
.. autofunction:: small_banner
|
||||
|
||||
.. _west-apis-manifest:
|
||||
|
||||
|
@ -155,75 +207,130 @@ west.manifest
|
|||
|
||||
.. automodule:: west.manifest
|
||||
|
||||
The main classes are `Manifest` and `Project`. These represent the contents of
|
||||
a :ref:`manifest file <west-manifests>`. The recommended methods for parsing
|
||||
west manifests are `Manifest.from_file` and `Manifest.from_data`.
|
||||
|
||||
Constants and functions
|
||||
=======================
|
||||
|
||||
.. autodata:: MANIFEST_PROJECT_INDEX
|
||||
|
||||
.. autodata:: MANIFEST_REV_BRANCH
|
||||
|
||||
.. autodata:: QUAL_MANIFEST_REV_BRANCH
|
||||
.. autodata:: QUAL_REFS_WEST
|
||||
.. autodata:: SCHEMA_VERSION
|
||||
|
||||
.. autofunction:: west.manifest.manifest_path
|
||||
|
||||
.. autofunction:: west.manifest.validate
|
||||
|
||||
Manifest and sub-objects
|
||||
========================
|
||||
|
||||
.. autoclass:: west.manifest.Manifest
|
||||
|
||||
.. automethod:: __init__
|
||||
.. versionchanged:: 0.7.0
|
||||
The ``importer`` and ``import_flags`` keyword arguments.
|
||||
|
||||
.. automethod:: from_file
|
||||
.. versionchanged:: 0.7.0
|
||||
``**kwargs`` added.
|
||||
|
||||
.. automethod:: from_data
|
||||
.. versionchanged:: 0.7.0
|
||||
``**kwargs`` added, and ``source_data`` may be a ``str``.
|
||||
|
||||
.. automethod:: __init__
|
||||
|
||||
.. automethod:: get_remote
|
||||
Conveniences for accessing sub-objects by name or other identifier:
|
||||
|
||||
.. automethod:: get_projects
|
||||
|
||||
.. versionadded:: 0.6.1
|
||||
|
||||
Additional methods:
|
||||
|
||||
.. automethod:: as_dict
|
||||
.. versionadded:: 0.7.0
|
||||
.. automethod:: as_frozen_dict
|
||||
.. automethod:: as_yaml
|
||||
.. versionadded:: 0.7.0
|
||||
.. automethod:: as_frozen_yaml
|
||||
.. versionadded:: 0.7.0
|
||||
|
||||
.. autoclass:: west.manifest.Defaults
|
||||
:members:
|
||||
:member-order: groupwise
|
||||
|
||||
.. autoclass:: west.manifest.Remote
|
||||
:members:
|
||||
:member-order: groupwise
|
||||
.. autoclass:: west.manifest.ImportFlag
|
||||
|
||||
.. autoclass:: west.manifest.Project
|
||||
|
||||
.. (note: attributes are part of the class docstring)
|
||||
|
||||
.. versionchanged:: 0.7.0
|
||||
The ``remote`` attribute was removed. Its semantics could no longer
|
||||
be preserved when support for manifest ``import`` keys was added.
|
||||
|
||||
.. versionadded:: 0.7.0
|
||||
The ``remote_name`` and ``name_and_path`` attributes.
|
||||
|
||||
Constructor:
|
||||
|
||||
.. automethod:: __init__
|
||||
|
||||
.. automethod:: as_dict
|
||||
.. versionchanged:: 0.7.0
|
||||
The parameters were incompatibly changed from previous versions.
|
||||
|
||||
.. automethod:: format
|
||||
Methods:
|
||||
|
||||
.. automethod:: as_dict
|
||||
.. versionadded:: 0.7.0
|
||||
|
||||
.. automethod:: git
|
||||
|
||||
.. versionchanged:: 0.6.1
|
||||
The ``capture_stderr`` kwarg.
|
||||
.. versionchanged:: 0.7.0
|
||||
The (now removed) ``Project.format`` method is no longer called on
|
||||
arguments.
|
||||
|
||||
.. automethod:: sha
|
||||
.. versionchanged:: 0.7.0
|
||||
Standard error is now captured.
|
||||
|
||||
.. automethod:: is_ancestor_of
|
||||
|
||||
.. automethod:: is_cloned
|
||||
|
||||
.. versionadded:: 0.6.1
|
||||
|
||||
.. automethod:: is_up_to_date_with
|
||||
|
||||
.. automethod:: is_up_to_date
|
||||
|
||||
.. automethod:: read_at
|
||||
.. versionadded:: 0.7.0
|
||||
|
||||
.. automethod:: listdir_at
|
||||
.. versionadded:: 0.7.0
|
||||
|
||||
.. autoclass:: west.manifest.ManifestProject
|
||||
:members:
|
||||
:member-order: groupwise
|
||||
|
||||
A limited subset of Project methods is supported.
|
||||
Results for calling others are not specified.
|
||||
|
||||
.. automethod:: as_dict
|
||||
|
||||
.. versionadded:: 0.6.0
|
||||
|
||||
Exceptions
|
||||
==========
|
||||
|
||||
.. autoclass:: west.manifest.MalformedManifest
|
||||
:show-inheritance:
|
||||
|
||||
.. autoclass:: west.manifest.MalformedConfig
|
||||
:show-inheritance:
|
||||
|
||||
.. autoclass:: west.manifest.ManifestVersionError
|
||||
:show-inheritance:
|
||||
|
||||
.. autoclass:: west.manifest.ManifestImportFailed
|
||||
:show-inheritance:
|
||||
|
||||
.. _west-apis-util:
|
||||
|
||||
west.util
|
||||
|
@ -233,12 +340,15 @@ west.util
|
|||
|
||||
.. automodule:: west.util
|
||||
|
||||
Functions
|
||||
=========
|
||||
|
||||
.. autofunction:: west.util.west_dir
|
||||
|
||||
.. autofunction:: west.util.west_topdir
|
||||
|
||||
Exceptions
|
||||
==========
|
||||
|
||||
.. autoclass:: west.util.WestNotFound
|
||||
:show-inheritance:
|
||||
|
||||
.. _west #38:
|
||||
https://github.com/zephyrproject-rtos/west/issues/38
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue