diff --git a/documentation/Makefile b/documentation/Makefile
index ea59746ae4..e6185ece52 100644
--- a/documentation/Makefile
+++ b/documentation/Makefile
@@ -119,9 +119,7 @@ TARFILES = dev-style.css dev-manual.html dev-manual.pdf \
TARFILES = dev-style.css dev-manual.html dev-manual.pdf \
figures/app-dev-flow.png figures/bsp-dev-flow.png figures/dev-title.png \
figures/git-workflow.png figures/index-downloads.png figures/kernel-dev-flow.png \
- figures/kernel-example-repos-generic.png \
figures/kernel-overview-1.png figures/kernel-overview-2-generic.png \
- figures/kernel-overview-3-generic.png \
figures/source-repos.png figures/yp-download.png \
figures/wip.png
endif
@@ -184,9 +182,7 @@ TARFILES = mega-manual.html mega-style.css figures/yocto-environment.png figures
figures/kernel-title.png figures/kernel-architecture-overview.png \
figures/app-dev-flow.png figures/bsp-dev-flow.png figures/dev-title.png \
figures/git-workflow.png figures/index-downloads.png figures/kernel-dev-flow.png \
- figures/kernel-example-repos-generic.png \
figures/kernel-overview-1.png figures/kernel-overview-2-generic.png \
- figures/kernel-overview-3-generic.png \
figures/source-repos.png figures/yp-download.png \
figures/wip.png
endif
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 78c1f39e18..0215fcf21a 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -1625,30 +1625,77 @@
messages to appear on the emulator's console.
+
+ Create a Layer for your Changes
+
+
+ The first step is to isolate your changes into a layer:
+
+ $cd ~/poky
+ $mkdir meta-mylayer
+
+ Creating a directory that follows the Yocto Project layer naming
+ conventions sets up the area for your layer.
+ The layer is where you place your configuration files, append
+ files, and patch files.
+ To learn more about creating a layer and filling it with the
+ files you need, see the "Understanding
+ and Creating Layers" section.
+
+
+
+
+ Finding the Kernel Source Code
+
+
+ Each time you build a kernel image, the kernel source code is fetched
+ and unpacked into a temporary location in the Build Directory.
+ See the "Finding the Temporary Source Code"
+ section for a description of where the OpenEmbedded build system places
+ kernel source files during a build.
+ Following is where machine-specific source code is temporarily stored
+ during the build:
+
+ ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}-${PV}-${PR}
+
+ Assuming a recent build for the qemux86 machine
+ based on the Linux 3.4 kernel, a
+ Source Directory named poky, and
+ the existence of a default build directory, the directory that
+ holds the temporary source code would be here:
+
+ ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-3.4.11+git1+5bdc...85f-r4.3
+
+ Within the linux directory, you find the source directories.
+
+
+
+ For this example, we are going to patch the init/calibrate.c file
+ and add some simple console printk statements that we can
+ see when we boot the image using QEMU.
+
+
+
Creating the Patch
- Describe how to find the source files in the build area.
- We are not assuming they are using their own kernel tree.
-
-
-
-
-
-
- Changing the Source Code and Pushing it to the Bare Clone
-
-
- The file you change in this example is named calibrate.c
- and is located in the my-linux-yocto-3.4-work Git repository
- (the copy of the bare clone) in init.
- This example simply inserts several printk statements
- at the beginning of the calibrate_delay function.
+ Two methods exist by which you can create the patch: Git workflow and Quilt workflow.
+ For kernel patches, the Git workflow is more appropriate.
+ This section assumes the Git workflow.
- Here is the unaltered code at the start of this function:
+ To create the patch for the calibrate.c, follow the steps
+ outlined in the
+ "Using a Git Workflow"
+ section.
+ For the steps used to edit the source file, do the following:
+
+
+
+ Locate the void __cpuinit calibrate_delay(void)
+ function:
void __cpuinit calibrate_delay(void)
{
@@ -1660,12 +1707,11 @@
.
.
.
-
-
+
+
-
- Here is the altered code showing five new printk statements
- near the top of the function:
+
+ Alter the code as follows:
void __cpuinit calibrate_delay(void)
{
@@ -1683,51 +1729,47 @@
.
.
.
-
+
+
+
+
+
+ Get Your Layer Setup for the Build
+
+
+ At this point, you have a patch file in the same directory as your original
+ calibrate.c.
+ Move it to your layer and place it in a separate folder having the same
+ name as the recipe, which is linux-yocto in this case.
- After making and saving your changes, you need to stage them for the push.
- The following Git commands are one method of staging and committing your changes:
+ Next, you need to set up your conf directory in your layer.
+ Create the conf and create the layer.conf
+ file.
+ You can find information on this in the
+ "Creating Your Own Layer"
+ section.
+ Here is what your layer.conf should look like for this
+ example:
- $ git add calibrate.c
- $ git commit --signoff
-
-
+ # We have a conf and classes directory, add to BBPATH
+ BBPATH := "${LAYERDIR}:${BBPATH}"
-
- Once the source code has been modified, you need to use Git to push the changes to
- the bare clone.
- If you do not push the changes, then the OpenEmbedded build system will not pick
- up the changed source files.
-
+ # We have a packages directory, add to BBFILES
+ BBFILES := "${BBFILES} ${LAYERDIR}/recipes-*/*/*.bb \
+ ${LAYERDIR}/recipes-*/*/*.bbappend"
-
- The following command pushes the changes to the bare clone:
-
- $ git push origin standard-common-pc-base:standard/default/common-pc/base
-
-
-
-
-
- Changing Build Parameters for Your Build
-
-
- At this point, the source has been changed and pushed.
- The example now defines some variables used by the OpenEmbedded build system
- to locate your kernel source.
- You essentially need to identify where to find the kernel recipe and the changed source code.
- You also need to be sure some basic configurations are in place that identify the
- type of machine you are building and to help speed up the build should your host support
- multiple-core and thread capabilities.
+ BBFILE_COLLECTIONS += "mylayer"
+ BBFILE_PATTERN_mylayer := "^${LAYERDIR}/"
+ BBFILE_PRIORITY_mylayer = "5"
+
Do the following to make sure the build parameters are set up for the example.
Once you set up these build parameters, they do not have to change unless you
- change the target architecture of the machine you are building or you move
- the bare clone, copy of the clone, or the poky-extras repository:
+ change the target architecture of the machine you are building:
Build for the Correct Target Architecture: The
local.conf file in the build directory defines the build's
@@ -1745,15 +1787,16 @@
If the host system has multiple cores then you can optimize build time
by setting both these variables to twice the number of
cores.
- Identify Your meta-kernel-dev
+ Identify Your meta-mylayer
Layer: The BBLAYERS variable in the
bblayers.conf file found in the
poky/build/conf directory needs to have the path to your local
- meta-kernel-dev layer.
+ meta-mylayer layer.
By default, the BBLAYERS variable contains paths to
- meta and meta-yocto in the
+ meta, meta-yocto, and
+ meta-yocto-bsp in the
poky Git repository.
- Add the path to your meta-kernel-dev location.
+ Add the path to your meta-mylayer location.
Be sure to substitute your user information in the statement.
Here is an example:
@@ -1761,43 +1804,27 @@
/home/scottrif/poky/meta \
/home/scottrif/poky/meta-yocto \
/home/scottrif/poky/meta-yocto-bsp \
- /home/scottrif/poky/poky-extras/meta-kernel-dev \
+ /home/scottrif/poky/meta-mylayer \
"
- Identify Your Source Files: In the
- linux-yocto_3.4.bbappend file located in the
- poky-extras/meta-kernel-dev/recipes-kernel/linux
- directory, you need to identify the location of the
- local source code, which in this example is the bare clone named
- linux-yocto-3.4.git.
- To do this, set the KSRC_linux_yocto variable to point to your
- local linux-yocto-3.4.git Git repository by adding the
- following statement.
- Also, be sure the SRC_URI variable is pointing to
- your kernel source files by removing the comment.
- Finally, be sure to substitute your user information in the statement:
+ Create a bbappend File: You need to have
+ an append file to the main 3.4 kernel recipe.
+ Locate the append file in your meta-mylayer layer.
+ It needs to be in a meta-mylayer/recipes-kernel/linux directory.
+ Create the directory and use the following for the append file.
+ This example assumes patch file is named 0001-documentation-calibrate.c.patch:
- KSRC_linux_yocto_3_4 ?= "/home/scottrif/linux-yocto-3.4.git"
- SRC_URI = "git://${KSRC_linux_yocto_3_4};protocol=file;nocheckout=1;branch=${KBRANCH},meta;name=machine,meta"
-
+ FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
+
+ SRC_URI += "file://0001-documentation-calibrate.c.patch"
+
+ PRINC := "${@int(PRINC) + 1}"
+
+ The FILESEXTRAPATHS and SRC_URI
+ statements ensure the OpenEmbedded build system picks up the patch file.
+
-
-
- Before attempting to build the modified kernel, there is one more set of changes you
- need to make in the meta-kernel-dev layer.
- Because all the kernel .bbappend files are parsed during the
- build process regardless of whether you are using them or not, you should either
- comment out the COMPATIBLE_MACHINE statements in all
- unused .bbappend files, or simply remove (or rename) all the files
- except the one your are using for the build
- (i.e. linux-yocto_3.4.bbappend in this example).
- If you do not make one of these two adjustments, your machine will be compatible
- with all the kernel recipes in the meta-kernel-dev layer.
- When your machine is comapatible with all the kernel recipes, the build attempts
- to build all kernels in the layer.
- You could end up with build errors blocking your work.
-
@@ -1826,7 +1853,7 @@
out previous builds.
Next, build the kernel image using this command:
- $ bitbake -k core-image-minimal
+ $ bitbake -k linux-yocto
Finally, boot the modified image in the QEMU emulator
using this command:
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
index 9d73f8e4f5..03bb83096e 100644
--- a/documentation/dev-manual/dev-manual-model.xml
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -1688,7 +1688,8 @@ directory.
You need to be in the directory that has the temporary source code.
That directory is defined by the
S
- variable.
+ variable.
+ For this discussion, assume that directory is linux.
Initialize a Git Repository:
Use the git init command to initialize a new local repository
that is based on the work directory:
@@ -1739,9 +1740,11 @@ directory.Stage the Modified Files:
Use the git add command to stage the changed files so they
- can be committed as follows:
+ can be committed as follows.
+ Again, for this discussion assume the files changed are in the linux
+ directory:
- $ git add file1.c file2.c file3.c
+ $ git add linux/file1.c linux/file2.c linux/file3.c
Commit the Staged Files and View Your Changes:
Use the git commit command to commit the changes to the