diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index a3e0725808..f792c7694f 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -7,12 +7,11 @@ Common Tasks This chapter describes standard tasks such as adding new - software packages, extending or customizing images or porting the Yocto Project to + software packages, extending or customizing images, and porting the Yocto Project to new hardware (adding a new machine). - The chapter also describes ways to modify package source code, combine multiple - versions of library files into a single image, and handle a package name alias. - Finally, the chapter contains advice about how to make changes to the - Yocto Project to achieve the best results. + The chapter also describes how to combine multiple + versions of library files into a single image, how to handle a package name alias, and + gives advice about how to make changes to the Yocto Project to achieve the best results.
@@ -1189,324 +1188,6 @@ so that there are some definite steps on how to do this. I need more detail her
-
- Modifying Temporary Source Code - - - 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. - - -
- Finding the Temporary Source Code - - - 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. - Below is the default value for the S variable as defined in the - meta/conf/bitbake.conf configuration file in the - Yocto Project Files: - - S = ${WORKDIR}/${BP} - - You should be aware that many recipes override the S variable. - For example, recipes that fetch their source from Git usually set - S to ${WORKDIR}/git. - - BP represents the "Base Package", which is the base package - name and the package version: - - BP = ${BPN}-${PV} - - - - - - The path to the work directory for the recipe - (WORKDIR) depends - on the package name and the architecture of the target device. - For example, here is the work directory for packages whose targets are not device-dependent: - - ${TMPDIR}/work/${PACKAGE_ARCH}-poky-${TARGET_OS}/${PN}-${PV}-${PR} - - Let's look at an example without variables. - Assuming a Yocto Project Files top-level directory named poky - and a default Yocto Project Build Directory of poky/build, - the following is the work directory for the acl package: - - ~/poky/build/tmp/work/i586-poky-linux/acl-2.2.51-r3 - - - - - If your package is dependent on the target device, the work directory 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 work directory 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 - - - - - 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. - - - - Now that you know where to locate the directory that has the temporary source code, you can use a - Quilt or Git workflow to make your edits, test the changes, and preserve the - changes in the form of patches. - -
- -
- Using a Quilt Workflow - - - Quilt - 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. - - - - 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 the directory that has the 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. - Create a New Patch: - Before modifying source code, you need to create a new patch. - To create a new patch file, use quilt new as below: - - $ quilt new my_changes.patch - - Notify Quilt and Add Files: - After creating the patch, you need to notify Quilt about the files you will - be changing. - Add the files you will be modifying into the patch you just created: - - $ 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 simplicity, copy the patch file into a directory named files, - which you can create in the same directory as the recipe. - Placing the patch here guarantees that the Yocto Project build system will find - the patch. - Next, add the patch 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 - - 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. - - - - This workflow uses Git only for its ability to manage local changes to the source code - and produce patches independent of any version control used on the Yocto Project - Files. - - - - 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 the directory that has the 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. - Initialize a Git Repository: - Use the git init command to initialize a new local repository - that is based on the work directory: - - $ git init - - Stage all the files: - Use the git add * command to stage all the files in the source - code directory so that they can be committed: - - $ git add * - - Commit the Source Files: - Use the git commit command to initially commit all the files in - the work directory: - - $ git commit - - At this point, your Git repository is aware of all the source code files. - Any edits you now make to files will be tracked by Git. - 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, 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 current directory. - The patch file ends with .patch. - Copy the Patch File: - For simplicity, copy the patch file into a directory named files, - which you can create in the same directory as the recipe. - Placing the patch here guarantees that the Yocto Project build system will find - the patch. - Next, add the patch 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. - - -
-
-
Combining Multiple Versions of Library Files into One Image diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml index bbedf6b5bd..69e09e6466 100644 --- a/documentation/dev-manual/dev-manual-model.xml +++ b/documentation/dev-manual/dev-manual-model.xml @@ -8,32 +8,35 @@ Many development models exist for which you can use the Yocto Project. - However, for the purposes of this manual we are going to focus on two common models: - System Development and User Application Development. - System Development covers Board Support Package (BSP) development and kernel modification - or configuration. - User Application Development covers development of applications that you intend to run on some - target hardware. - - - - This chapter presents overviews of both system and application models. - If you want to examine specific examples of the system development models, - see the "BSP Development Example" - appendix and the - "Kernel Modification Example" appendix. - For a user-space application development example that uses the - Eclipse IDE, - see the - - The Yocto Project Application Development Toolkit (ADT) User's Guide. - - - - Aside from these two models, this chapter will also briefly introduce and discuss - development using - Hob, which is a graphical interface - to the Yocto Project build system. + This chapter overviews the following methods: + + System Development: + System Development covers Board Support Package (BSP) development and kernel + modification or configuration. + If you want to examine specific examples of the system development models, + see the "BSP Development Example" + appendix and the + "Kernel Modification Example" appendix. + + User Application Development: + User Application Development covers development of applications that you intend + to run on some target hardware. + For a user-space application development example that uses the + Eclipse IDE, + see the + + The Yocto Project Application Development Toolkit (ADT) User's Guide. + + Temporary Source Code Modification: + Direct modification of temporary source code is a convenient development model + to quickly iterate and develop towards a solution. + Once the solution has been implemented, you should of course take steps to + get the changes upstream and applied in the affected recipes. + Image Development using Hob: + You can use the Hob to build + custom operating system images within the Yocto Project build environment. + Hob provides an efficient interface to the Yocto Project build system. +
@@ -58,7 +61,7 @@ Developing a Board Support Package (BSP) - A BSP is a package of recipes that, when applied, during a build results in + A BSP is a packageof recipes that, when applied, during a build results in an image that you can run on a particular board. Thus, the package, when compiled into the new image, supports the operation of the board. @@ -700,6 +703,323 @@ WRITER NOTE: The areas to get the kernel and root filesystem are located in the
+
+ Modifying Temporary Source Code + + + 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. + + +
+ Finding the Temporary Source Code + + + 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. + Below is the default value for the S variable as defined in the + meta/conf/bitbake.conf configuration file in the + Yocto Project Files: + + S = ${WORKDIR}/${BP} + + You should be aware that many recipes override the S variable. + For example, recipes that fetch their source from Git usually set + S to ${WORKDIR}/git. + + BP represents the "Base Package", which is the base package + name and the package version: + + BP = ${BPN}-${PV} + + + + + + The path to the work directory for the recipe + (WORKDIR) depends + on the package name and the architecture of the target device. + For example, here is the work directory for packages whose targets are not device-dependent: + + ${TMPDIR}/work/${PACKAGE_ARCH}-poky-${TARGET_OS}/${PN}-${PV}-${PR} + + Let's look at an example without variables. + Assuming a Yocto Project Files top-level directory named poky + and a default Yocto Project Build Directory of poky/build, + the following is the work directory for the acl package: + + ~/poky/build/tmp/work/i586-poky-linux/acl-2.2.51-r3 + + + + + If your package is dependent on the target device, the work directory 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 work directory 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 + + + + + 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. + + + + Now that you know where to locate the directory that has the temporary source code, you can use a + Quilt or Git workflow to make your edits, test the changes, and preserve the + changes in the form of patches. + +
+ +
+ Using a Quilt Workflow + + + Quilt + 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. + + + + 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 the directory that has the 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. + Create a New Patch: + Before modifying source code, you need to create a new patch. + To create a new patch file, use quilt new as below: + + $ quilt new my_changes.patch + + Notify Quilt and Add Files: + After creating the patch, you need to notify Quilt about the files you will + be changing. + Add the files you will be modifying into the patch you just created: + + $ 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 simplicity, copy the patch file into a directory named files, + which you can create in the same directory as the recipe. + Placing the patch here guarantees that the Yocto Project build system will find + the patch. + Next, add the patch 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 + + 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. + + + + This workflow uses Git only for its ability to manage local changes to the source code + and produce patches independent of any version control used on the Yocto Project + Files. + + + + 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 the directory that has the 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. + Initialize a Git Repository: + Use the git init command to initialize a new local repository + that is based on the work directory: + + $ git init + + Stage all the files: + Use the git add * command to stage all the files in the source + code directory so that they can be committed: + + $ git add * + + Commit the Source Files: + Use the git commit command to initially commit all the files in + the work directory: + + $ git commit + + At this point, your Git repository is aware of all the source code files. + Any edits you now make to files will be tracked by Git. + 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, 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 current directory. + The patch file ends with .patch. + Copy the Patch File: + For simplicity, copy the patch file into a directory named files, + which you can create in the same directory as the recipe. + Placing the patch here guarantees that the Yocto Project build system will find + the patch. + Next, add the patch 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. + + +
+
+
Image Development Using Hob