Running a Build
- You can find information on how to build an image using the Yocto Project in the
+ You can find general information on how to build an image using the
+ Yocto Project in the
Building an Image section of the
Yocto Project Quick Start.
- This section provides a quick overview.
+ This section provides a summary of the build process and provides information
+ for less obvious aspects of the build process.
-
- The first thing you need to do is set up the Yocto Project build environment by sourcing
- the environment setup script as follows:
-
- $ source oe-init-build-env [build_dir];
-
-
+
+ Build Overview
-
- The build_dir is optional and specifies the directory Yocto Project
- uses for the build.
- If you do not specify a build directory it defaults to build
- in the Yocto Project files directory structure.
- A common practice is to use a different build directory for different targets.
- For example, ~/build/x86 for a qemux86
- target, and ~/build/arm for a qemuarm target.
- See oe-init-build-env
- for more information on this script.
-
+
+ The first thing you need to do is set up the Yocto Project build environment by sourcing
+ the environment setup script as follows:
+
+ $ source oe-init-build-env [build_dir]
+
+
-
- Once the Yocto Project build environment is set up, you can build a target using:
-
+
+ The build_dir is optional and specifies the directory Yocto Project
+ uses for the build.
+ If you do not specify a build directory it defaults to build
+ in your current working directory.
+ A common practice is to use a different build directory for different targets.
+ For example, ~/build/x86 for a qemux86
+ target, and ~/build/arm for a qemuarm target.
+ See oe-init-build-env
+ for more information on this script.
+
+
+
+ Once the Yocto Project build environment is set up, you can build a target using:
+
$ bitbake <target>
-
-
+
+
-
- The target is the name of the recipe you want to build.
- Common targets are the images in meta/recipes-core/images,
- /meta/recipes-sato/images, etc. all found in the Yocto Project
- files.
- Or, the target can be the name of a recipe for a specific piece of software such as
- busybox.
- For more details about the images Yocto Project supports, see the
- 'Reference: Images' appendix.
-
+
+ The target is the name of the recipe you want to build.
+ Common targets are the images in meta/recipes-core/images,
+ /meta/recipes-sato/images, etc. all found in the Yocto Project
+ files.
+ Or, the target can be the name of a recipe for a specific piece of software such as
+ busybox.
+ For more details about the images Yocto Project supports, see the
+ 'Reference: Images' appendix.
+
-
- Building an image without GNU Public License Version 3 (GPLv3) components is
- only supported for minimal and base images.
- See 'Reference: Images' for more information.
-
+
+ Building an image without GNU Public License Version 3 (GPLv3) components is
+ only supported for minimal and base images.
+ See 'Reference: Images' for more information.
+
+
-
- When building an image using GPL components, you need to maintain your original
- settings and not switch back and forth applying different versions of the GNU
- Public License.
- If you rebuild using different versions of GPL, dependency errors might occur
- due to some components not being rebuilt.
-
+
+ Building an Image Using GPL Components
+
+
+ When building an image using GPL components, you need to maintain your original
+ settings and not switch back and forth applying different versions of the GNU
+ Public License.
+ If you rebuild using different versions of GPL, dependency errors might occur
+ due to some components not being rebuilt.
+
+
+
+
+ Considering Shared State Cache
+
+
+ By design, the Yocto Project builds everything from scratch unless it can determine that
+ a given task's inputs have not changed.
+ While building from scratch ensures that everything is current, it does also
+ mean that a lot of time could be spent rebuiding things that don't necessarily need built.
+
+
+
+ The Yocto Project build process uses a shared state caching scheme to avoid having to
+ rebuild software when it is not necessary.
+ Because the build time for a Yocto image can be significant, it is helpful to try and
+ determine what really needs built and what can be skipped given a particular project's
+ build process.
+
+
+
+ The scheme that the Yocto Project uses involves checksum generation and comparison for
+ a task's inputs.
+ The scheme also employs an area of memory called the shared state cache that is
+ pointed to by the SSTATE_DIR variable.
+ This area contains task output generated from a previous build.
+ If a given task's checksum matches the checksum of a previous build for the same
+ task, the build process uses the state of the cache rather than rerunning that
+ task.
+
+
+
+ The previous paragraph is a simplistic explanation of how the build process
+ uses checksums and shared state memory cache to avoide building tasks that
+ don't need built.
+ If you want a bit more explanation on the topic,
+ see "Shared
+ State - What does it mean and why should I care?" from the Yocto
+ Project discussion archives.
+
+
+
+ As with all schemes, this one has some drawbacks.
+ It is possible that you could make implicit changes that are not factored into the checksum
+ calculation, but do affect a task's output.
+ A good example is perhaps when a tool changes its output.
+ Let's say that the output of rpmdeps needed to change.
+ The result of the change should be that all the "package", "package_write_rpm",
+ and "package_deploy-rpm" sstate-cache items would become invalid.
+ But, because this is a change that is external to the code and therefore implicit,
+ the associated sstate-cache items do not become invalidated.
+ In this case, the build process would use the cache items rather than running the
+ task again.
+ Obviously, these types of implicit changes can cause problems.
+
+
+
+ To avoid these problems during the build, you need to understand the effects of any
+ change you make.
+ Note that any changes you make directly to a function automatically are factored into
+ the checksum calculation and thus, will invalidate the associated area of sstate cache.
+ You need to be aware of any implicit changes that are not obvious changes to the
+ code and could affect the output of a given task.
+ Once you are aware of such a change, you can take steps to invalidate the cache
+ and force the task to run.
+ The step to take is as simple as changing a function's comments in the source code.
+ For example, to invalidate package sstate files, change the comment statments
+ of do_package or one of the functions it calls.
+ The change is purely cosmetic, but it causes the checksum to be recalculated and
+ forces the task to be run again.
+
+
+
+ For an example of a commit that makes a cosmetic change to invalidate an sstate,
+ see this
+ commit.
+
+
+
+
+
+
Installing and Using the Result