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