diff options
Diffstat (limited to 'documentation/dev-manual/quilt.rst')
-rw-r--r-- | documentation/dev-manual/quilt.rst | 90 |
1 files changed, 90 insertions, 0 deletions
diff --git a/documentation/dev-manual/quilt.rst b/documentation/dev-manual/quilt.rst new file mode 100644 index 0000000000..d1b605bcd5 --- /dev/null +++ b/documentation/dev-manual/quilt.rst | |||
@@ -0,0 +1,90 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-SA-2.0-UK | ||
2 | |||
3 | Using Quilt in Your Workflow | ||
4 | **************************** | ||
5 | |||
6 | `Quilt <https://savannah.nongnu.org/projects/quilt>`__ is a powerful tool | ||
7 | that allows you to capture source code changes without having a clean | ||
8 | source tree. This section outlines the typical workflow you can use to | ||
9 | modify source code, test changes, and then preserve the changes in the | ||
10 | form of a patch all using Quilt. | ||
11 | |||
12 | .. note:: | ||
13 | |||
14 | With regard to preserving changes to source files, if you clean a | ||
15 | recipe or have :ref:`rm_work <ref-classes-rm-work>` enabled, the | ||
16 | :ref:`devtool workflow <sdk-manual/extensible:using \`\`devtool\`\` in your sdk workflow>` | ||
17 | as described in the Yocto Project Application Development and the | ||
18 | Extensible Software Development Kit (eSDK) manual is a safer | ||
19 | development flow than the flow that uses Quilt. | ||
20 | |||
21 | Follow these general steps: | ||
22 | |||
23 | 1. *Find the Source Code:* Temporary source code used by the | ||
24 | OpenEmbedded build system is kept in the :term:`Build Directory`. See the | ||
25 | ":ref:`dev-manual/temporary-source-code:finding temporary source code`" section to | ||
26 | learn how to locate the directory that has the temporary source code for a | ||
27 | particular package. | ||
28 | |||
29 | 2. *Change Your Working Directory:* You need to be in the directory that | ||
30 | has the temporary source code. That directory is defined by the | ||
31 | :term:`S` variable. | ||
32 | |||
33 | 3. *Create a New Patch:* Before modifying source code, you need to | ||
34 | create a new patch. To create a new patch file, use ``quilt new`` as | ||
35 | below:: | ||
36 | |||
37 | $ quilt new my_changes.patch | ||
38 | |||
39 | 4. *Notify Quilt and Add Files:* After creating the patch, you need to | ||
40 | notify Quilt about the files you plan to edit. You notify Quilt by | ||
41 | adding the files to the patch you just created:: | ||
42 | |||
43 | $ quilt add file1.c file2.c file3.c | ||
44 | |||
45 | 5. *Edit the Files:* Make your changes in the source code to the files | ||
46 | you added to the patch. | ||
47 | |||
48 | 6. *Test Your Changes:* Once you have modified the source code, the | ||
49 | easiest way to test your changes is by calling the :ref:`ref-tasks-compile` | ||
50 | task as shown in the following example:: | ||
51 | |||
52 | $ bitbake -c compile -f package | ||
53 | |||
54 | The ``-f`` or ``--force`` option forces the specified task to | ||
55 | execute. If you find problems with your code, you can just keep | ||
56 | editing and re-testing iteratively until things work as expected. | ||
57 | |||
58 | .. note:: | ||
59 | |||
60 | All the modifications you make to the temporary source code disappear | ||
61 | once you run the :ref:`ref-tasks-clean` or :ref:`ref-tasks-cleanall` | ||
62 | tasks using BitBake (i.e. ``bitbake -c clean package`` and | ||
63 | ``bitbake -c cleanall package``). Modifications will also disappear if | ||
64 | you use the :ref:`rm_work <ref-classes-rm-work>` feature as described in | ||
65 | the ":ref:`dev-manual/disk-space:conserving disk space during builds`" | ||
66 | section. | ||
67 | |||
68 | 7. *Generate the Patch:* Once your changes work as expected, you need to | ||
69 | use Quilt to generate the final patch that contains all your | ||
70 | modifications. | ||
71 | :: | ||
72 | |||
73 | $ quilt refresh | ||
74 | |||
75 | At this point, the | ||
76 | ``my_changes.patch`` file has all your edits made to the ``file1.c``, | ||
77 | ``file2.c``, and ``file3.c`` files. | ||
78 | |||
79 | You can find the resulting patch file in the ``patches/`` | ||
80 | subdirectory of the source (:term:`S`) directory. | ||
81 | |||
82 | 8. *Copy the Patch File:* For simplicity, copy the patch file into a | ||
83 | directory named ``files``, which you can create in the same directory | ||
84 | that holds the recipe (``.bb``) file or the append (``.bbappend``) | ||
85 | file. Placing the patch here guarantees that the OpenEmbedded build | ||
86 | system will find the patch. Next, add the patch into the :term:`SRC_URI` | ||
87 | of the recipe. Here is an example:: | ||
88 | |||
89 | SRC_URI += "file://my_changes.patch" | ||
90 | |||