michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: west: 0.7.0 documentation

Browse source 
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:
Martí Bolívar 2019-10-11 13:51:46 -07:00 • committed by Kumar Gala
commit b4fde33243
6 changed files with 282 additions and 97 deletions
Download patch file Download diff file Expand all files Collapse all files

3
doc/guides/west/index.rst
View file

@ -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`.

24
doc/guides/west/manifest.rst
View file

@ -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:

24
doc/guides/west/planned.rst
View file

@ -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

78
doc/guides/west/release-notes.rst
View file

@ -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
******

22
doc/guides/west/repo-tool.rst
View file

@ -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/

228
doc/guides/west/west-apis.rst
View file

@ -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