Lines Matching +full:west +full:- +full:commands
1 .. _west-release-notes:
3 West Release Notes
11 - New ``west grep`` command for running a "grep tool" in your west workspace's
18 .. code-block:: console
20 west grep foo
22 Here are some other examples for running different grep commands
23 with ``west grep``:
25 .. list-table::
27 * - ``git grep --untracked``
28 - ``west grep --untracked foo``
29 * - ``ripgrep``
30 - ``west grep --tool ripgrep foo``
31 * - ``grep --recursive``
32 - ``west grep --tool grep foo``
37 .. list-table::
39 * - ``ripgrep``
40 - ``west config grep.tool ripgrep``
41 * - ``grep``
42 - ``west config grep.tool grep``
44 For more details, run ``west help grep``.
48 - The manifest file format now supports a ``description`` field in each
49 ``projects:`` element. See :ref:`west-manifests-projects` for examples.
51 - ``west list --format`` now accepts ``{description}`` in the format
54 - ``west compare`` now always prints information about
55 :ref:`west-manifest-rev`.
59 - ``west init`` aborts if the destination directory already exists.
63 - ``west.commands.WestCommand`` methods ``check_call()`` and
67 - ``west.commands.WestCommand.run_subprocess()``: new wrapper
71 - ``west.commands.WestCommand`` methods ``dbg()``, ``inf()``,
75 - ``west.manifest.Project`` now has a ``description`` attribute,
86 - ``west compare``: new command that compares the state of the
89 - Support for a new ``manifest.project-filter`` configuration option.
90 See :ref:`west-config-index` for details. The ``west manifest --freeze``
91 and ``west manifest --resolve`` commands currently cannot be used when
94 - Project names which contain comma (``,``) or whitespace now generate
95 warnings. These warnings are errors if the new ``manifest.project-filter``
97 future major version of west.
101 - ``west forall`` now takese a ``--group`` argument that can be used
103 ``west help forall`` for details.
105 - All west commands will now output log messages from west API modules at
106 warning level or higher. In addition, the ``--verbose`` argument to west
108 debug messages, from all commands.
112 - Various improvements to error messages, debug logging, and error handling.
116 - ``west.manifest.Manifest.is_active()`` now respects the
117 ``manifest.project-filter`` configuration option's value.
124 - Manifest schema version "1.0" is now available for use in this release. This
127 field. See :ref:`west-manifest-schema-version` for details on this feature.
131 - West no longer exits with a successful error code when sent an
132 interrupt signal. Instead, it exits with a platform-specific
141 - The :ref:`west-apis` are now declared stable. Any breaking changes will be
144 - West v1.0 no longer works with the Zephyr v1.14 LTS releases. This LTS has
146 must use west v0.14 or earlier.
148 - Like the rest of Zephyr, west now requires Python v3.8 or later
150 - West commands no longer accept abbreviated command line arguments. For
151 example, you must now specify ``west update --keep-descendants`` instead of
152 using an abbreviation like ``west update --keep-d``. This is part of a change
153 applied to all of Zephyr's Python scripts' command-line interfaces. The
154 abbreviations were causing problems in practice when commands were updated to
159 - All built-in west functions have stopped using ``west.log``
161 - ``west update``: new ``--submodule-init-config`` option.
166 - West extension commands that failed to load properly sometimes dumped stack.
167 This has been fixed and west now prints a sensible error message in this case.
169 - ``west config`` now fails on malformed configuration option arguments
174 - The west package now contains the metadata files necessary for some static
175 analyzers (such as `mypy`_) to auto-detect its type annotations.
178 - the deprecated ``west.build`` module used for Zephyr v1.14 LTS compatibility was
181 - the deprecated ``west.cmake`` module used for Zephyr v1.14 LTS compatibility was
184 - the ``west.log`` module is now deprecated. This module uses global state,
188 - The :ref:`west-apis-commands` module got some new APIs which lay groundwork
190 and work to remove global state from the ``west`` package's API:
192 - New ``west.commands.WestCommand.__init__()`` keyword argument: ``verbosity``
193 - New ``west.commands.WestCommand`` property: ``color_ui``
194 - New ``west.commands.WestCommand`` methods, which should be used to print output
195 from extension commands instead of writing directly to sys.stdout or
198 - New ``west.commands.VERBOSITY`` enum
200 .. _9ba92b05: https://github.com/zephyrproject-rtos/west/commit/9ba92b054500d75518ff4c4646590bfe134…
201 .. _d9f00e24: https://github.com/zephyrproject-rtos/west/commit/d9f00e242b8cb297b56e941982adf231281…
202 .. _mypy: https://www.mypy-lang.org/
209 - West commands that were run with a bad local configuration file dumped stack
210 in a confusing way. This has been fixed and west now prints a sensible error
213 - A bug in the way west looks for the zephyr repository was fixed. The bug
214 itself usually appeared when running an extension command like ``west build``
219 - West now prints sensible error messages when the user lacks permission to
224 - The ``west.manifest.MalformedConfig`` exception type has been moved to the
225 ``west.configuration`` module
227 - The ``west.manifest.MalformedConfig`` exception type has been moved to the
228 :ref:`west.configuration <west-apis-configuration>` module
230 - The ``west.configuration.Configuration`` class now raises ``MalformedConfig``
238 - When calling west.manifest.Manifest.from_file() when outside of a
239 workspace, west again falls back on the ZEPHYR_BASE environment
247 - You can now associate arbitrary user data with the manifest repository
250 .. code-block:: YAML
258 - The path to the manifest repository reported by west could be incorrect in
260 #572](https://github.com/zephyrproject-rtos/west/issues/572). This has been
262 ``west.manifest`` API module.
264 - The ``west.Manifest.ManifestProject.__repr__`` return value was fixed
266 :ref:`API <west-apis>` changes:
268 - ``west.configuration.Configuration``: new object-oriented interface to the
269 current configuration. This reflects the system, global, and workspace-local
273 - ``west.commands.WestCommand``:
275 - ``config``: new attribute, returns a ``Configuration`` object or aborts the
278 - ``has_config``: new boolean attribute, which is ``True`` if and only if
281 - The path handling in the ``west.manifest`` package has been overhauled in a
282 backwards-incompatible way. For more details, see commit
283 …[56cfe8d1d1](https://github.com/zephyrproject-rtos/west/commit/56cfe8d1d1f3c9b45de3e793c738acd62db…
285 - ``west.manifest.Manifest.validate()``: this now returns the validated data as
289 - ``west.manifest.Manifest``: new:
291 - path attributes ``abspath``, ``posixpath``, ``relative_path``,
293 - ``userdata`` attribute, which contains the parsed value
295 - ``from_topdir()`` factory method
297 - ``west.manifest.ManifestProject``: new ``userdata`` attribute, which also
300 - ``west.manifest.ManifestImportFailed``: the constructor can now take any
302 <west-manifest-import-map>` or other compound value.
304 - Deprecated configuration APIs:
311 - ``west.configuration.config``
312 - ``west.configuration.read_config``
313 - ``west.configuration.update_config``
314 - ``west.configuration.delete_config``
321 - West now works on the `MSYS2 <https://www.msys2.org/>`_ platform.
323 - West manifest files can now contain arbitrary user data associated with each
324 project. See :ref:`west-project-userdata` for details.
328 - The ``west list`` command's ``{sha}`` format key has been fixed for
332 :ref:`API <west-apis>` changes:
334 - The ``west.manifest.Project.userdata`` attribute was added to support
342 - ``west status`` now only prints output for projects which have a nonempty
347 - The manifest file parser was incorrectly allowing project names which contain
353 relative to its remote ``url-base:``, use ``repo-path:``. See
354 :ref:`west-manifests-projects` for examples.
356 - The changes made in west v0.10.1 to the ``west init --manifest-rev`` option
361 - The ``WEST_CONFIG_LOCAL`` environment variable now correctly
362 overrides the default location, :file:`<workspace topdir>/.west/config`.
364 - ``west update --fetch=smart`` (``smart`` is the default) now correctly skips
371 - The fix for issue #522 mentioned above introduces a new restriction. The
372 ``west init --manifest-rev`` option value, if given, must now be either a
373 branch or a tag. In particular, "pseudo-branches" like GitHub's
375 request can no longer be passed to ``--manifest-rev``. Users must now fetch
376 and check out such revisions manually after running ``west init``.
378 :ref:`API <west-apis>` changes:
380 - ``west.manifest.Manifest.get_projects()`` avoids incorrect results in
383 - ``west.manifest.Project.sha()`` now works correctly for tag revisions.
386 .. _lightweight tags: https://git-scm.com/book/en/v2/Git-Basics-Tagging
387 .. _issue #522: https://github.com/zephyrproject-rtos/west/issues/522
388 .. _issue #523: https://github.com/zephyrproject-rtos/west/issues/523
395 - ``west update`` now supports ``--narrow``, ``--name-cache``, and
396 ``--path-cache`` options. These can be influenced by the ``update.narrow``,
397 ``update.name-cache``, and ``update.path-cache`` :ref:`west-config` options.
399 - ``west update`` now supports a ``--fetch-opt`` option that will be passed to
405 - ``west update`` now synchronizes Git submodules in projects by default. This
408 ``update.sync-submodules`` configuration option to ``false``.
412 - the :ref:`west-apis-manifest` module has fixed docstrings for the Project
420 - The :ref:`west-init` command's ``--manifest-rev`` (``--mr``) option no longer
433 - The ``name`` key in a project's :ref:`submodules list
434 <west-manifest-submodules>` is now optional.
438 - West now checks that the manifest schema version is one of the explicitly
439 allowed values documented in :ref:`west-manifest-schema-version`. The old
440 behavior was just to check that the schema version was newer than the west
446 - A manifest file's ``group-filter`` is now propagated through an ``import``.
447 This is a change from how west v0.9.x handled this. In west v0.9.x, only the
448 top level manifest file's ``group-filter`` had any effect; the group filter
451 Starting with west v0.10.0, the group filter lists from imported manifests
452 are also imported. For details, see :ref:`west-group-filter-imports`.
457 :ref:`west-manifest-schema-version` for more information on schema versions.
459 See `west pull request #482
460 <https://github.com/zephyrproject-rtos/west/pull/482>`_ for the motivation
468 - Commands like ``west manifest --resolve`` now correctly include group and
473 - West now warns if you combine ``import`` with ``group-filter``. Semantics for
484 The ``west config`` fix described below comes at a cost: any comments or
486 configuration option via that command or the ``west.configuration`` API.
490 Combining the ``group-filter`` feature introduced in this release with
491 manifest imports is discouraged. The resulting behavior has changed in west
496 - West manifests now support :ref:`west-manifest-submodules`. This allows you
498 <https://git-scm.com/book/en/v2/Git-Tools-Submodules>`_ into a west project
501 - West manifests now support :ref:`west-manifest-groups`. Project groups can be
503 will be acted upon by the following commands: ``west update``, ``west list``,
504 ``west diff``, ``west status``, ``west forall``.
506 - ``west update`` no longer updates inactive projects by default. It now
507 supports a ``--group-filter`` option which allows for one-time modifications
510 - Running ``west list``, ``west diff``, ``west status``, or ``west forall``
515 These commands also now support ``--all`` arguments to include all
518 - ``west list`` now supports a ``{groups}`` format string key in its
519 ``--format`` argument.
523 - The ``west config`` command and ``west.configuration`` API did not correctly
526 <https://github.com/zephyrproject-rtos/west/commit/36f3f91e270782fb05f6da13800f433a9c48f130>`_
529 - A manifest file with an empty ``manifest: self: path:`` value is invalid, but
530 west used to let it pass silently. West now rejects such manifests.
532 - A bug affecting the behavior of the ``west init -l .`` command was fixed; see
533 `issue #435 <https://github.com/zephyrproject-rtos/west/issues/435>`_.
535 :ref:`API <west-apis>` changes:
537 - added ``west.manifest.Manifest.is_active()``
538 - added ``west.manifest.Manifest.group_filter``
539 - added ``submodules`` attribute to ``west.manifest.Project``, which has
540 newly added type ``west.manifest.Submodule``
544 - The :ref:`west-manifest-import` feature now supports the terms ``allowlist``
554 for a ``path-prefix:`` key in an ``import:`` mapping, along with some other
557 - Manifest import mappings now support a ``path-prefix:`` key, which places
559 See :ref:`west-manifest-ex3.4` for an example.
560 - The west command line application can now also be run using ``python3 -m
561 west``. This makes it easier to run west under a particular Python
563 - :ref:`west manifest --path <west-manifest-path>` prints the absolute path to
564 west.yml
565 - ``west init`` now supports an ``--mf foo.yml`` option, which initializes the
566 workspace using :file:`foo.yml` instead of :file:`west.yml`.
567 - ``west list`` now prints the manifest repository's path using the
568 ``manifest.path`` :ref:`configuration option <west-config>`, which may differ
570 still available, but requires passing a new ``--manifest-path-from-yaml``
572 - Various Python API changes; see :ref:`west-apis` for details.
579 - Fix an error where a failed import could leave the workspace in an unusable
580 state (see [PR #415](https://github.com/zephyrproject-rtos/west/pull/415) for
588 - Filter out duplicate extension commands brought in by manifest imports
589 - Fix ``west.Manifest.get_projects()`` when finding the manifest repository by
597 - ``west update --stats`` now prints timing for operations which invoke a
598 subprocess, time spent in west's Python process for each project, and total
600 - ``west topdir`` always prints a POSIX style path
601 - minor console output changes
606 The main user-visible feature in west 0.7 is the :ref:`west-manifest-import`
607 feature. This allows users to load west manifest data from multiple different
610 Additional user-visible changes:
612 - The idea of a "west installation" has been renamed to "west workspace" in
613 this documentation and in the west API documentation. The new term seems to
615 - West manifests now support a :ref:`schema version
616 <west-manifest-schema-version>`.
617 - The "west config" command can now be run outside of a workspace, e.g.
618 to run ``west config --global section.key value`` to set a configuration
620 - There is a new :ref:`west topdir <west-built-in-misc>` command, which
621 prints the root directory of the current west workspace.
622 - The ``west -vv init`` command now prints the git operations being performed,
624 - The restriction that no project can be named "manifest" is now enforced; the
626 such in commands like ``west list manifest``, instead of ``west list
627 path-to-manifest-repository`` being the only way to say that
628 - It's no longer an error if there is no project named "zephyr". This is
629 part of an effort to make west generally usable for non-Zephyr use cases.
630 - Various bug fixes.
632 The developer-visible changes to the :ref:`west-apis` are:
634 - west.build and west.cmake: deprecated; this is Zephyr-specific functionality
635 and should never have been part of west. Since Zephyr v1.14 LTS relies on it,
638 - west.commands:
640 - WestCommand.requires_installation: deprecated; use requires_workspace instead
641 - WestCommand.requires_workspace: new
642 - WestCommand.has_manifest: new
643 - WestCommand.manifest: this is now settable
644 - west.configuration: callers can now identify the workspace directory
646 - west.log:
648 - msg(): new
649 - west.manifest:
651 - The module now uses the standard logging module instead of west.log
652 - QUAL_REFS_WEST: new
653 - SCHEMA_VERSION: new
654 - Defaults: removed
655 - Manifest.as_dict(): new
656 - Manifest.as_frozen_yaml(): new
657 - Manifest.as_yaml(): new
658 - Manifest.from_file() and from_data(): these factory methods are more
660 - Manifest.validate(): new
661 - ManifestImportFailed: new
662 - ManifestProject: semi-deprecated and will likely be removed later.
663 - Project: the constructor now takes a topdir argument
664 - Project.format() and its callers are removed. Use f-strings instead.
665 - Project.name_and_path: new
666 - Project.remote_name: new
667 - Project.sha() now captures stderr
668 - Remote: removed
670 West now requires Python 3.6 or later. Additionally, some features may rely on
671 Python dictionaries being insertion-ordered; this is only an implementation
679 ``west.cmake`` module.
684 This point release fixes an error in the behavior of ``west
685 update --fetch=smart``, introduced in v0.6.1.
696 The user-visible features in this point release are:
698 - The :ref:`west-update` command has a new ``--fetch``
700 <west-config>`. The default value, "smart", skips fetching SHAs and tags
702 - Better and more consistent error-handling in the ``west diff``, ``west
703 status``, ``west forall``, and ``west update`` commands. Each of these
704 commands can operate on multiple projects; if a subprocess related to one
705 project fails, these commands now continue to operate on the rest of the
706 projects. All of them also now report a nonzero error code from the west
708 ``west forall`` in particular).
709 - The :ref:`west manifest <west-built-in-misc>` command also handles errors
711 - The :ref:`west list <west-built-in-misc>` command now works even when the
716 - Commands and options which operate on git revisions now accept abbreviated
717 SHAs. For example, ``west init --mr SHA_PREFIX`` now works. Previously, the
718 ``--mr`` argument needed to be the entire 40 character SHA if it wasn't a
721 The developer-visible changes to the :ref:`west-apis` are:
723 - west.log.banner(): new
724 - west.log.small_banner(): new
725 - west.manifest.Manifest.get_projects(): new
726 - west.manifest.Project.is_cloned(): new
727 - west.commands.WestCommand instances can now access the parsed
731 - west.manifest.Project.git() now has a capture_stderr kwarg
737 - No separate bootstrapper
739 In west v0.5.x, the program was split into two components, a bootstrapper and
740 a per-installation clone. See `Multiple Repository Management in the v1.14
743 This is similar to how Google's Repo tool works, and lets west iterate quickly
744 at first. It caused confusion, however, and west is now stable enough to be
747 From v0.6.x onwards, all of the core west commands and helper classes are
748 part of the west package distributed via PyPI. This eliminates complexity
749 and makes it possible to import west modules from anywhere in the system,
750 not just extension commands.
751 - The ``selfupdate`` command still exists for backwards compatibility, but
753 - Manifest syntax changes
755 - A west manifest file's ``projects`` elements can now specify their fetch
758 .. code-block:: yaml
762 - name: example-project-name
763 url: https://github.com/example/example-project
767 - Project names must be unique: this restriction is needed to support future
768 work, but was not possible in west v0.5.x because distinct projects may
771 .. code-block:: yaml
775 - name: remote-1
776 url-base: https://github.com/remote-1
777 - name: remote-2
778 url-base: https://github.com/remote-2
780 - name: project
781 remote: remote-1
782 path: remote-1-project
783 - name: project
784 remote: remote-2
785 path: remote-2-project
790 .. code-block:: yaml
794 - name: remote-1-project
795 url: https://github.com/remote-1/project
796 - name: remote-2-project
797 url: https://github.com/remote-2/project
799 - The ``west list`` command now supports a ``{sha}`` format string key
801 - The default format string for ``west list`` was changed to ``"{name:12}
804 - The command ``west manifest --validate`` can now be run to load and validate
805 the current manifest file, among other error-handling fixes related to
808 - Incompatible API changes were made to west's APIs. Further changes are
809 expected until API stability is declared in west v1.0.
811 - The ``west.manifest.Project`` constructor's ``remote`` and ``defaults``
816 - ``west.manifest.MANIFEST_SECTIONS`` was removed. There is only one section
818 ``west.manifest.Manifest`` factory methods and constructor were also
821 - The ``west.manifest.SpecialProject`` class was removed. Use
822 ``west.manifest.ManifestProject`` instead.
828 West v0.5.x is the first version used widely by the Zephyr Project as part of
829 its v1.14 Long-Term Support (LTS) release. The `west v0.5.x documentation`_ is
832 West's main features in v0.5.x are:
834 - Multiple repository management using Git repositories, including self-update
835 of west itself
836 - Hierarchical configuration files
837 - Extension commands
842 Tags in the west repository before v0.5.x are prototypes which are of
846 https://docs.zephyrproject.org/1.14.0/guides/west/repo-tool.html
849 https://docs.zephyrproject.org/1.14.0/guides/west/index.html