diff --git a/doc/guides/west/index.rst b/doc/guides/west/index.rst index e7828e22ac1..cc6c058dc0e 100644 --- a/doc/guides/west/index.rst +++ b/doc/guides/west/index.rst @@ -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 -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`. diff --git a/doc/guides/west/manifest.rst b/doc/guides/west/manifest.rst index d0762e9048b..b7b9b69fb71 100644 --- a/doc/guides/west/manifest.rst +++ b/doc/guides/west/manifest.rst @@ -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: # 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: diff --git a/doc/guides/west/planned.rst b/doc/guides/west/planned.rst deleted file mode 100644 index 11d5dcbbd27..00000000000 --- a/doc/guides/west/planned.rst +++ /dev/null @@ -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 diff --git a/doc/guides/west/release-notes.rst b/doc/guides/west/release-notes.rst index 3d00d7a0251..bd705813a1b 100644 --- a/doc/guides/west/release-notes.rst +++ b/doc/guides/west/release-notes.rst @@ -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 + `. +- 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 ` 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 ****** diff --git a/doc/guides/west/repo-tool.rst b/doc/guides/west/repo-tool.rst index 2e06c37e14c..84216788f12 100644 --- a/doc/guides/west/repo-tool.rst +++ b/doc/guides/west/repo-tool.rst @@ -262,6 +262,17 @@ Miscellaneous Commands West has a few more commands for managing the multi-repo, which are briefly discussed here. Run ``west -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 --options'``. Note that ``west forall`` can be used + to run any command, though, not just Git commands. + +- ``west help ``: this is equivalent to ``west -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 -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 --options'``. Note that ``west forall`` can be used - to run any command, though, not just Git commands. - -- ``west help ``: this is equivalent to ``west -h``. +- ``west topdir``: Prints the top directory of the west workspace. .. _PyPI: https://pypi.org/project/west/ diff --git a/doc/guides/west/west-apis.rst b/doc/guides/west/west-apis.rst index b474edfab90..41328d1c0fd 100644 --- a/doc/guides/west/west-apis.rst +++ b/doc/guides/west/west-apis.rst @@ -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 `. 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