diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index fc7a535f85..ce41a28031 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -1626,7 +1626,7 @@
- The example assumes a clean build exists for the x86qemu
+ The example assumes a clean build exists for the qemux86
machine in a Source Directory named poky.
Furthermore, the Build Directory is
build and is located in poky and
@@ -1637,13 +1637,13 @@
Create a Layer for your Changes
- The first step is to isolate your changes into a layer:
+ The first step is to create a layer so you can isolate your changes:
$cd ~/poky
$mkdir meta-mylayer
Creating a directory that follows the Yocto Project layer naming
- conventions sets up the area for your changes.
+ conventions sets up the layer for your changes.
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
@@ -1657,26 +1657,24 @@
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:
+ and unpacked into the following directory:
- ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}-${PV}-${PR}
+ ${S}/linux
+ See the "Finding the Temporary Source Code"
+ section and the
+ S variable
+ for more information about where source is kept during a build.
For this example, the directory that
holds the temporary source code is here:
- ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-3.4.11+git1+5bdc...85f-r4.3
+ ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-3.4.11+git1+5bdc...85f-r4.3/linux
- Within the linux directory, you find directories for
- the source.
- For this example, we are going to patch the init/calibrate.c file
+ For this example, we are going to patch the
+ init/calibrate.c file
by adding some simple console printk statements that we can
see when we boot the image using QEMU.
@@ -1686,39 +1684,31 @@
Creating the Patch
- Two methods exist by which you can create the patch: Git workflow and Quilt workflow.
+ 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.
-
-
-
- To create the patch for the calibrate.c, follow steps
- 3 through 12 outlined in the
- "Using a Git Workflow"
- section.
- For step 6 (Edit the Files), do the following:
-
-
-
- Locate the void __cpuinit calibrate_delay(void)
- function:
-
- void __cpuinit calibrate_delay(void)
- {
- unsigned long lpj;
- static bool printed;
- int this_cpu = smp_processor_id();
-
- if (per_cpu(cpu_loops_per_jiffy, this_cpu)) {
- .
- .
- .
-
-
-
-
- Alter the code as follows:
-
+ This section assumes the Git workflow and shows the steps specific to
+ this example.
+
+ Change the working directory:
+ Change to where the kernel source code is before making
+ your edits to the calibrate.c file:
+
+ $ cd ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-${PV}-${PR}/linux
+
+ Because you are working in an established Git repository,
+ you must be in this directory in order to commit your changes
+ and create the patch file.
+ The PV and
+ PR variables
+ represent the version and revision for the
+ linux-yocto recipe.
+
+ Edit the source file:
+ Edit the init/calibrate.c file to have the
+ following changes:
+
void __cpuinit calibrate_delay(void)
{
unsigned long lpj;
@@ -1735,44 +1725,49 @@
.
.
.
-
+
+ Stage and commit your changes:
+ These Git commands list out the changed file, stage it, and then
+ commit the files:
+
+ $ git status
+ $ git add init/calibrate.c
+ $ git commit
+
+ Generate the patch file:
+ This Git command creates the a patch file named
+ 0001-calibrate.c.patch in the current directory.
+
+ $ git format-patch HEAD~1
+
+ The name of the patch file is based on your commit summary
+ line.
+
+
Get Your Layer Setup for the Build
-
- At this point, you have a patch file in the kernel's source code directory.
- The patch file is named according to the commit's summary line and ends
- with .patch.
- For this example, it is named 0001-calibrate.c.patch.
-
-
-
- You need to move the patch file to your layer next.
- The patch file needs to reside in the
- meta-mylayer/recipes-kernel/linux/linux-yocto directory.
- Create this directory path within your layer and move the patch file.
- This directory path mirrors that used by the main kernel recipe in
- the Source Directory (poky).
-
+ These steps get your layer set up for the build:
+
+ Create additional structure:
+ Create the additional layer structure:
+
$ cd ~/poky/meta-mylayer
+ $ mkdir conf
$ mkdir recipes-kernel
$ mkdir recipes-kernel/linux
$ mkdir recipes-kernel/linux/linux-yocto
-
-
-
-
- Next, you need to create a conf directory in your layer
- and within it 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:
-
+
+ The conf directory holds your configuration files, while the
+ recipes-kernel directory holds your append file and
+ your patch file.
+ Create the layer configuration file:
+ Move to the meta-mylayer/conf directory and create
+ the layer.conf file as follows:
+
# We have a conf and classes directory, add to BBPATH
BBPATH := "${LAYERDIR}:${BBPATH}"
@@ -1783,80 +1778,85 @@
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:
-
- Build for the Correct Target Architecture: The
- local.conf file in the build directory defines the build's
- target architecture.
- By default, MACHINE is set to
- qemux86, which specifies a 32-bit
- Intel Architecture
- target machine suitable for the QEMU emulator.
- In this example, MACHINE is correctly configured.
-
- Optimize Build Time: Also in the
- local.conf file are two variables that can speed your
- build time if your host supports multi-core and multi-thread capabilities:
- BB_NUMBER_THREADS and PARALLEL_MAKE.
- 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-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-mylayer layer.
- By default, the BBLAYERS variable contains paths to
- meta, meta-yocto, and
- meta-yocto-bsp in the
- poky Git repository.
- Add the path to your meta-mylayer location.
- Be sure to substitute your user information in the statement.
- Here is an example:
-
- BBLAYERS = " \
- /home/scottrif/poky/meta \
- /home/scottrif/poky/meta-yocto \
- /home/scottrif/poky/meta-yocto-bsp \
- /home/scottrif/poky/meta-mylayer \
- "
-
- Create a bbappend File: You need to create
- an append file for the main 3.4 kernel recipe.
- Create the append file in the linux directory you
- created earlier within your layer.
- Assuming the patch file is named
- 0001-documentation-calibrate.c.patch, your append
- file, which must be named linux-yocto_3.4.bbappend,
- has these statements:
-
+
+ Notice mylayer as part of the last three
+ statements.
+ Create the kernel recipe append file:
+ Move to the meta-mylayer/recipes-kernel/linux directory and create
+ the linux-yocto_3.4.bbappend file as follows:
+
FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
- SRC_URI += "file://0001-documentation-calibrate.c.patch"
+ SRC_URI += "file://0001-calibrate.c.patch"
PRINC := "${@int(PRINC) + 1}"
-
- The FILESEXTRAPATHS and SRC_URI
- statements ensure the OpenEmbedded build system picks up the patch file.
-
-
-
-
+
+ The FILESEXTRAPATHS and SRC_URI
+ statements enable the OpenEmbedded build system to find the patch file.
+
+ Put the patch file in your layer:
+ Move the 0001-calibrate.c.patch file to
+ the meta-mylayer/recipes-kernel/linux/linux-yocto
+ directory.
+
+
+
-
- Building and Booting the Modified QEMU Kernel Image
+
+ Set Up for the Build
- Next, you need to build the modified image.
- Do the following:
+ 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:
+
+ Build for the Correct Target Architecture: The
+ local.conf file in the build directory defines the build's
+ target architecture.
+ By default, MACHINE is set to
+ qemux86, which specifies a 32-bit
+ Intel Architecture
+ target machine suitable for the QEMU emulator.
+ In this example, MACHINE is correctly configured.
+
+ Optimize Build Time: Also in the
+ local.conf file are two variables that can speed your
+ build time if your host supports multi-core and multi-thread capabilities:
+ BB_NUMBER_THREADS and PARALLEL_MAKE.
+ 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-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-mylayer layer.
+ By default, the BBLAYERS variable contains paths to
+ meta, meta-yocto, and
+ meta-yocto-bsp in the
+ poky Git repository.
+ Add the path to your meta-mylayer location.
+ Be sure to substitute your user information in the statement:
+
+ BBLAYERS = " \
+ /home/<user>/poky/meta \
+ /home/<user>/poky/meta-yocto \
+ /home/<user>/poky/meta-yocto-bsp \
+ /home/<user>/poky/meta-mylayer \
+ "
+
+
+
+
+
+
+ Build and Booting the Modified QEMU Kernel Image
+
+
+ The following steps build and boot your modified kernel image:
- Your environment should be set up since you previously sourced
+ Be sure your build environment is initialized:
+ Your environment should be set up since you previously sourced
the &OE_INIT_FILE; script.
If it isn't, source the script again from poky.
@@ -1864,7 +1864,8 @@
$ source &OE_INIT_FILE;
- Be sure old images are cleaned out by running the
+ Clean up:
+ Be sure old images are cleaned out by running the
cleanall BitBake task as follows from your build directory:
$ bitbake -c cleanall linux-yocto
@@ -1873,29 +1874,36 @@
directory inside the build directory.
Always use the BitBake cleanall task to clear
out previous builds.
- Next, build the kernel image using this command:
+ Build the image:
+ Next, build the kernel image using this command:
$ bitbake -k linux-yocto
- Finally, boot the modified image in the QEMU emulator
+
+
+
+
+
+ Verify Your Changes
+
+
+ These steps boot the image and allow you to see the changes
+
+ Boot the image:
+ Boot the modified image in the QEMU emulator
using this command:
$ runqemu qemux86
-
-
-
-
- Log into the machine using root with no password and then
- use the following shell command to scroll through the console's boot output.
-
+ Verify the changes:
+ Log into the machine using root with no password and then
+ use the following shell command to scroll through the console's boot output.
+
# dmesg | less
-
-
-
-
- You should see the results of your printk statements
- as part of the output.
+
+ You should see the results of your printk statements
+ as part of the output.
+
@@ -2625,8 +2633,8 @@
One of the concerns for a development organization using open source
software is how to maintain compliance with various open source
licensing during the lifecycle of the product.
- While this section is not meant to be legal advice or to
- comprehensively cover all scenarios, it is meant to
+ While this section does not provide legal advice or
+ comprehensively cover all scenarios, it does
present methods that you can use to
meet the compliance requirements during a software
release.
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
index 436ecb6fb7..b61eeb0678 100644
--- a/documentation/dev-manual/dev-manual-model.xml
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -1688,10 +1688,12 @@ directory.
You need to be in the directory that has the temporary source code.
That directory is defined by the
S
- variable.
- For this discussion, assume that directory is linux.
- Initialize a Git Repository:
- Use the git init command to initialize a new local repository
+ variable.
+ If you are working with a kernel, you need to be in the
+ ${S}/linux directory.
+ If needed, initialize a Git Repository:
+ If you are not already in a Git repository, use the
+ git init command to initialize a new local repository
that is based on the work directory:
$ git init
@@ -1730,11 +1732,6 @@ directory.
"Building an Image"
section of the Yocto Project Quick Start.
- Change Your Working Directory:
- After making your edits, move back to the directory from which you
- initialized the Git repository.
- Returning to this directory ensures you are using the correct branch when
- you go to commit your changes.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
@@ -1749,7 +1746,7 @@ directory.
Again, for this discussion assume the files changed are in the linux
directory:
- $ git add linux/file1.c linux/file2.c linux/file3.c
+ $ git add <somepath>/file1.c <somepath>/file2.c <somepath>/file3.c
Commit the Staged Files and View Your Changes:
Use the git commit command to commit the changes to the