From 452d2764c9d650d7b7d90579062133b2835b010c Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Thu, 16 Feb 2012 15:22:44 -0600 Subject: documentation/dev-manual/dev-manual-common-tasks.xml: re-write to 4.4 Complete re-write to the "Modifying Temporary Source Code" section, Section 4.4. This strategy now comprises telling the user where this temporary source code is, how to change it within a Quilt workflow, and how to change it within a Git workflow. I consulted with Paul Eggleton quite a bit to come to this conclusion that the section needed more attention. (From yocto-docs rev: 8c6c80121c1eeb1ec6f79e1efb6aa27aa9fd111f) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-common-tasks.xml | 318 +++++++++++++++------ 1 file changed, 231 insertions(+), 87 deletions(-) (limited to 'documentation') diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index be639f76b8..5fcc69cbd0 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -746,48 +746,51 @@ so that there are some definite steps on how to do this. I need more detail her -
- Modifying Package Source Code +
+ Modifying Temporary Source Code - This section describes how to modify package source code in the - Yocto Project's Build Directory - and also how to then use - Quilt to manage - the resulting patches. + Although the Yocto Project is typically used to build software, you might + find it helpful during development to modify the temporary source code used by recipes + to build packages. + For example, suppose you are developing a patch and you need to experiment a bit + to figure out your solution. + After you have initially built the package, you can iteratively tweak the + source code, which is located in the + Yocto Project's Build Directory, and then + you can force a re-compile and quickly test your altered code. + Once you settle on a solution, you can then preserve your changes in the form of + patches. + You can accomplish these steps all within either a + Quilt or + Git workflow. -
- Working with Source Code in the Build Directory +
+ Finding the Temporary Source Code - Although the Yocto Project is typically used to build software, you might - find it helpful during development to modify the temporary package source code - found within the Yocto Project's Build Directory. - For example, suppose you are developing a patch and you need to experiment a bit - to figure out your solution. - After you have initially built the package, you can iteratively tweak the - source code, which is located in the Yocto Project build directory, and then - you can force a re-compile and test your altered code. - Once you settle on a solution, you can then copy the updated source code - to its more permanent location. + During a build, the unpacked temporary source code used by recipes + to build packages is available in the Yocto Project build directory as + defined by the + S variable: + + S = ${WORKDIR}/${PN}-${PV} + - During a build, this temporary source code is available in the Yocto - Project build directory, which is defined by the - TMPDIR variable. - The actual location within the build directory for the package source code - is defined by the - WORKDIR - variable and depends on the package name and the architecture of the target device. - Here is the source code location for packages that are not target device-dependent: + The actual location within the build directory for the temporary source code + depends on the package name and the architecture of the target device. + Here is the temporary source code location for packages whose targets are not + device-dependent: ${TMPDIR}/work/${PACKAGE_ARCH}-poky-${TARGET_OS}/${PN}-${PV}-${PR} + Let's look at an example. Assuming a Yocto Project Files top-level directory named poky and a default Yocto Project build directory of poky/build, - the following is the temporary package source code location for the + the following is the temporary source code location for the acl package: ~/poky/build/tmp/work/i586-poky-linux/acl-2.2.51-r3 @@ -795,96 +798,237 @@ so that there are some definite steps on how to do this. I need more detail her - If your package is target device-dependent, the source code location varies slightly: + If your package is dependent on the target device, the temporary + source code location varies slightly: ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}-${PV}-${PR} Again, assuming a Yocto Project Files top-level directory named poky and a default Yocto Project build directory of poky/build, the - following is the temporary package source code location for the + following is the temporary source code location for the acl package that is being built for a MIPS-based device: ~/poky/build/tmp/work/mips-poky-linux/acl-2.2.51-r2 - - Once you have modified the package source code, the easiest way to test your changes - is by calling the compile task as shown in the following example: - - $ bitbake -c compile -f <name_of_package> - - + + To better understand how the Yocto Project build system resolves directories during the + build process, see the glossary entries for the + WORKDIR, + TMPDIR, + TOPDIR, + PACKAGE_ARCH, + TARGET_OS, + PN, + PV, + and + PR + variables in the Yocto Project Reference Manual. + - The -f or --force - option forces re-execution of the specified task. - You can call other tasks this way as well. - All the modifications you make to the temporary package source code - disappear once you -c clean or - -c cleanall with BitBake for the package. - Modifications will also disappear if you use the rm_work - feature as described in the - "Building an Image" section - of the Yocto Project Quick Start. - + Now that you know where to locate the temporary source files, you can use a + Quilt or Git workflow to make your edits, test the changes, and preserve the + changes in the form of patches.
-
- Modifying Package Source Code with Quilt +
+ Using a Quilt Workflow - By default, the Yocto Project build system (Poky) uses Quilt - to manage patches while executing the do_patch task. - Quilt is a powerful tool that you can use to track all modifications to package sources. - - - - Before modifying source code, it is important to notify Quilt so it can track the changes - into a new patch file. - To create a new patch, use quilt new as below: - - $ quilt new NAME-OF-PATCH.patch - + is a powerful tool that allows you to capture source code changes without having + a clean source tree. + This section outlines the typical workflow you can use to modify temporary source code, + test changes, and then preserve the changes in the form of a patch all using Quilt. - After creating the patch, add all the files you will be modifying into that patch - as follows: - - $ quilt add file1 file2 file3 - + Follow these general steps: + + Find the Source Code: + The temporary source code used by the Yocto Project build system is kept in the + Yocto Project build directory. + See the + "Finding the Temporary Source Code" + section to learn how to locate temporary source code for a + particular package. + Change Your Working Directory: + You need to be in the directory that has the temporary source code. + That directory is defined by the + S + variable. + Notify Quilt: + Before modifying source code, it is important to notify Quilt so it can track changes + into a new patch file. + To create a new patch file, use quilt new as below: + + $ quilt new my_changes.patch + + Add Files: + After creating the patch, add the files you will be modifying into that patch + as follows: + + $ quilt add file1.c file2.c file3.c + + Edit the Files: + Make the changes to the temporary source code. + Test Your Changes: + Once you have modified the source code, the easiest way to test your changes + is by calling the compile task as shown in the following example: + + $ bitbake -c compile -f <name_of_package> + + The -f or --force + option forces re-execution of the specified task. + If you find problems with your code, you can just keep editing and + re-testing iteratively until things work as expected. + All the modifications you make to the temporary source code + disappear once you -c clean or + -c cleanall with BitBake for the package. + Modifications will also disappear if you use the rm_work + feature as described in the + "Building an Image" + section of the Yocto Project Quick Start. + + Generate the Patch: + Once your changes work as expected, you need to use Quilt to generate the final patch that + contains all your modifications. + + $ quilt refresh + + At this point the my_changes.patch file has all your edits made + to the file1.c, file2.c, and + file3.c files. + You can find the resulting patch file in the patches/ + subdirectory of the source (S) directory. + Copy the Patch File: + For future builds, you should copy the patch file into the + Yocto Project Files metadata and add it + into the + SRC_URI + of the recipe. + Here is an example: + + SRC_URI += "file://my_changes.patch" + + Increment the Package Revision Number: + Finally, don't forget to 'bump' the + PR + value in the same recipe since the resulting packages have changed. + +
+
+ Using a Git Workflow - You can now start editing the source code. - Once you are done editing, you need to use Quilt to generate the final patch that - contains all your modifications. - - $ quilt refresh - + Git is an even more powerful tool that allows you to capture source code changes without having + a clean source tree. + This section outlines the typical workflow you can use to modify temporary source code, + test changes, and then preserve the changes in the form of a patch all using Git. + For general information on Git as it is used in the Yocto Project, see the + "Git" section. - You can find the resulting patch file in the - patches/ subdirectory of the source - (S) directory. - For future builds, you should copy the patch into the - Yocto Project Files metadata and add it - into the - SRC_URI of the recipe. - Here is an example: - - SRC_URI += "file://NAME-OF-PATCH.patch" - + The steps in this section assume that you have already created a local Git repository of + the Yocto Project Files and have checked them + out into an appropriate local working branch. + If you need more explanation on setting up the Yocto Project Files, see the + "Getting Setup" section. + Also, if you need information on Git workflows in general, see the + Workflows section. - Finally, don't forget to 'bump' the - PR - value in the same recipe since the resulting packages have changed. + Follow these general steps: + + Find the Source Code: + The temporary source code used by the Yocto Project build system is kept in the + Yocto Project build directory. + See the + "Finding the Temporary Source Code" + section to learn how to locate temporary source code for a + particular package. + Change Your Working Directory: + You need to be in the directory that has the temporary source code. + That directory is defined by the + S + variable. + Edit the Files: + Make the changes to the temporary source code. + Test Your Changes: + Once you have modified the source code, the easiest way to test your changes + is by calling the compile task as shown in the following example: + + $ bitbake -c compile -f <name_of_package> + + The -f or --force + option forces re-execution of the specified task. + If you find problems with your code, you can just keep editing and + re-testing iteratively until things work as expected. + All the modifications you make to the temporary source code + disappear once you -c clean or + -c cleanall with BitBake for the package. + Modifications will also disappear if you use the rm_work + feature as described in the + "Building an Image" + section of the Yocto Project Quick Start. + + See the List of Files You Changed: + Use the Git status command to see what files you have actually edited. + The ability to have Git track the files you have changed is an advantage that this + workflow has over the Quilt workflow. + Here is the Git command to list your changed files: + + $ git status + + Stage the Modified Files: + Use the Git add command to stage the changed files so they + can be committed as follows: + + $ git add file1.c file2.c file3.c + + Commit the Staged Files and View Your Changes: + Use the Git commit command to commit the changes to the + local repository. + Once you have committed the files, you can use the Git log + command to see your changes: + + $ git commit + $ git log + + Generate the Patch: + Once the changes are committed, you use the Git format-patch + command to generate a patch file: + + $ git format-patch HEAD~1 + + The HEAD~1 part of the command causes Git to generate the + patch file for the most recent commit. + At this point, the patch file has all your edits made + to the file1.c, file2.c, and + file3.c files. + You can find the resulting patch file in the patches/ + subdirectory of the source (S) directory. + Copy the Patch File: + For future builds, you should copy the patch file into the + Yocto Project Files metadata and add it + into the + SRC_URI + of the recipe. + Here is an example: + + SRC_URI += "file://my_changes.patch" + + Increment the Package Revision Number: + Finally, don't forget to 'bump' the + PR + value in the same recipe since the resulting packages have changed. +
-- cgit v1.2.3-54-g00ecf