From 1fc7ccbf9682471fc3478c6be5521d7856ecf3c5 Mon Sep 17 00:00:00 2001 From: Chris Friedt Date: Fri, 9 May 2025 12:19:23 -0400 Subject: [PATCH] doc: west: add documentation for west patch Add documentation for the `west patch` command. Signed-off-by: Chris Friedt --- doc/develop/west/zephyr-cmds.rst | 120 +++++++++++++++++++++++++++++++ 1 file changed, 120 insertions(+) diff --git a/doc/develop/west/zephyr-cmds.rst b/doc/develop/west/zephyr-cmds.rst index 0a0a9ed12dd..e40093c3dd1 100644 --- a/doc/develop/west/zephyr-cmds.rst +++ b/doc/develop/west/zephyr-cmds.rst @@ -281,3 +281,123 @@ Additional tips: separate ``west global`` command since ``global`` already searches for the ``GTAGS`` file starting from your current working directory. This is why you need to run ``global`` from inside the workspace. + +.. _west-patch: + +Working with patches: ``west patch`` +************************************ + +The ``patch`` command allows users to apply patches to Zephyr or Zephyr modules +in a controlled manner that makes automation and tracking easier for external applications that +use the :ref:`T2 star topology `. The :ref:`patches.yml ` file stores +metadata about patch files and fills-in the gaps between official Zephyr releases, so that users +can easily see the status of any upstreaming efforts, and determine which patches to drop before +upgrading to the next Zephyr release. + +There are several sub-commands available to manage patches for Zephyr or other modules in the +workspace: + +* ``apply``: apply patches listed in ``patches.yml`` +* ``clean``: remove all patches that have been applied, and reset to the manifest checkout state +* ``list``: list all patches in ``patches.yml`` +* ``gh-fetch``: fetch patches from a GitHub pull request + +.. code-block:: none + + west-workspace/ + └── application/ + ... + ├── west.yml + └── zephyr + ├── module.yml + ├── patches + │ ├── bootloader + │ │ └── mcuboot + │ │ └── my-tweak-for-mcuboot.patch + │ └── zephyr + │ └── my-zephyr-change.patch + └── patches.yml + +In this example, the :ref:`west manifest ` file, ``west.yml``, would pin to a +specific Zephyr revision (e.g. ``v4.1.0``) and apply patches against that revision of Zephyr and +the specific revisions of other modules used in the application. However, this application needs +two changes in order to meet requirements; one for Zephyr and another for MCUBoot. + +.. _patches-yml: + +.. code-block:: yaml + + patches: + - path: zephyr/my-zephyr-change.patch + sha256sum: c676cd376a4d19dc95ac4e44e179c253853d422b758688a583bb55c3c9137035 + module: zephyr + author: Obi-Wan Kenobi + email: obiwan@jedi.org + date: 2025-05-04 + upstreamable: false + comments: | + An application-specific change we need for Zephyr. + - path: bootloader/mcuboot/my-tweak-for-mcuboot.patch + sha256sum: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 + module: mcuboot + author: Darth Sidious + email: sidious@sith.org + date: 2025-05-04 + merge-pr: https://github.com/zephyrproject-rtos/zephyr/pull/ + issue: https://github.com/zephyrproject-rtos/zephyr/issues/ + merge-status: true + merge-commit: 1234567890abcdef1234567890abcdef12345678 + merge-date: 2025-05-06 + apply-command: git apply + comments: | + A change to mcuboot that has been merged already. We can remove this + patch when we are ready to upgrade to the next Zephyr release. + +Patches can easily be applied in an automated manner. For example: + +.. code-block:: bash + + west init -m + cd + west update + west patch apply + +When it is time to update to a newer version of Zephyr, the ``west.yml`` file can be updated to +point at the next Zephyr release, e.g. ``v4.2.0``. Patches that are no longer needed, like +``my-tweak-for-mcuboot.patch`` in the example above, can be removed from ``patches.yml`` and from +the external application repository, and then the following commands can be run. + +.. code-block:: bash + + west patch clean + west update + west patch apply --roll-back # roll-back all patches if one does not apply cleanly + +If a patch needs to be reworked, remember to update the ``patches.yml`` file with the new SHA256 +checksum. + +.. code-block:: bash + + sha256sum zephyr/patches/zephyr/my-zephyr-change.patch + 7d57ca78d5214f422172cc47fed9d0faa6d97a0796c02485bff0bf29455765e9 + +It is also possible to use ``west patch gh-fetch`` to fetch patches from a GitHub pull request and +automatically create or update the ``patches.yml`` file. This can be useful when the author already +has a number of changes captured in existing upstream pull requests. + +.. code-block:: bash + + west patch gh-fetch --owner zephyrproject-rtos --repo zephyr --pull-request \ + --module zephyr --split-commits + +The above command will create the directory and file structure below, which includes patches for +each individual commit associated with the given pull request. + +.. code-block:: none + + zephyr + ├── patches + │ ├── first-commit-from-pr.patch + │ ├── second-commit-from-pr.patch + │ └── third-commit-from-pr.patch + └── patches.yml