</para>
<para>
- The example assumes a clean build exists for the <filename>x86qemu</filename>
+ The example assumes a clean build exists for the <filename>qemux86</filename>
machine in a Source Directory named <filename>poky</filename>.
Furthermore, the <link linkend='build-directory'>Build Directory</link> is
<filename>build</filename> and is located in <filename>poky</filename> and
<title>Create a Layer for your Changes</title>
<para>
- 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:
<literallayout class='monospaced'>
$cd ~/poky
$mkdir meta-mylayer
</literallayout>
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
<para>
Each time you build a kernel image, the kernel source code is fetched
- and unpacked into a temporary location in the <link linkend='build-directory'>Build Directory</link>.
- See the "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>"
- 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:
<literallayout class='monospaced'>
- ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}-${PV}-${PR}
+ ${S}/linux
</literallayout>
+ See the "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>"
+ section and the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink> 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:
<literallayout class='monospaced'>
- ~/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
</literallayout>
- Within the <filename>linux</filename> directory, you find directories for
- the source.
</para>
<para>
- For this example, we are going to patch the <filename>init/calibrate.c</filename> file
+ For this example, we are going to patch the
+ <filename>init/calibrate.c</filename> file
by adding some simple console <filename>printk</filename> statements that we can
see when we boot the image using QEMU.
</para>
<title>Creating the Patch</title>
<para>
- 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:
+ <link linkend='using-a-git-workflow'>Git workflow</link> and
+ <link linkend='using-a-quilt-workflow'>Quilt workflow</link>.
For kernel patches, the Git workflow is more appropriate.
- This section assumes the Git workflow.
- </para>
-
- <para>
- To create the patch for the <filename>calibrate.c</filename>, follow steps
- 3 through 12 outlined in the
- "<link linkend='using-a-git-workflow'>Using a Git Workflow</link>"
- section.
- For step 6 (Edit the Files), do the following:
- </para>
-
- <para>
- Locate the <filename>void __cpuinit calibrate_delay(void)</filename>
- function:
- <literallayout class='monospaced'>
- 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)) {
- .
- .
- .
- </literallayout>
- </para>
-
- <para>
- Alter the code as follows:
- <literallayout class='monospaced'>
+ This section assumes the Git workflow and shows the steps specific to
+ this example.
+ <orderedlist>
+ <listitem><para><emphasis>Change the working directory</emphasis>:
+ Change to where the kernel source code is before making
+ your edits to the <filename>calibrate.c</filename> file:
+ <literallayout class='monospaced'>
+ $ cd ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-${PV}-${PR}/linux
+ </literallayout>
+ 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.
+ <note>The <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> and
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> variables
+ represent the version and revision for the
+ <filename>linux-yocto</filename> recipe.
+ </note></para></listitem>
+ <listitem><para><emphasis>Edit the source file</emphasis>:
+ Edit the <filename>init/calibrate.c</filename> file to have the
+ following changes:
+ <literallayout class='monospaced'>
void __cpuinit calibrate_delay(void)
{
unsigned long lpj;
.
.
.
- </literallayout>
+ </literallayout></para></listitem>
+ <listitem><para><emphasis>Stage and commit your changes</emphasis>:
+ These Git commands list out the changed file, stage it, and then
+ commit the files:
+ <literallayout class='monospaced'>
+ $ git status
+ $ git add init/calibrate.c
+ $ git commit
+ </literallayout></para></listitem>
+ <listitem><para><emphasis>Generate the patch file</emphasis>:
+ This Git command creates the a patch file named
+ <filename>0001-calibrate.c.patch</filename> in the current directory.
+ <literallayout class='monospaced'>
+ $ git format-patch HEAD~1
+ </literallayout>
+ <note>The name of the patch file is based on your commit summary
+ line.</note>
+ </para></listitem>
+ </orderedlist>
</para>
</section>
<section id='get-your-layer-setup-for-the-build'>
<title>Get Your Layer Setup for the Build</title>
- <para>
- 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 <filename>.patch</filename>.
- For this example, it is named <filename>0001-calibrate.c.patch</filename>.
- </para>
-
- <para>
- You need to move the patch file to your layer next.
- The patch file needs to reside in the
- <filename>meta-mylayer/recipes-kernel/linux/linux-yocto</filename> 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 (<filename>poky</filename>).
- <literallayout class='monospaced'>
+ <para>These steps get your layer set up for the build:
+ <orderedlist>
+ <listitem><para><emphasis>Create additional structure</emphasis>:
+ Create the additional layer structure:
+ <literallayout class='monospaced'>
$ cd ~/poky/meta-mylayer
+ $ mkdir conf
$ mkdir recipes-kernel
$ mkdir recipes-kernel/linux
$ mkdir recipes-kernel/linux/linux-yocto
- </literallayout>
- </para>
-
- <para>
- Next, you need to create a <filename>conf</filename> directory in your layer
- and within it create the <filename>layer.conf</filename> file.
- You can find information on this in the
- "<link linkend='creating-your-own-layer'>Creating Your Own Layer</link>"
- section.
- Here is what your <filename>layer.conf</filename> should look like for this
- example:
- <literallayout class='monospaced'>
+ </literallayout>
+ The <filename>conf</filename> directory holds your configuration files, while the
+ <filename>recipes-kernel</filename> directory holds your append file and
+ your patch file.</para></listitem>
+ <listitem><para><emphasis>Create the layer configuration file</emphasis>:
+ Move to the <filename>meta-mylayer/conf</filename> directory and create
+ the <filename>layer.conf</filename> file as follows:
+ <literallayout class='monospaced'>
# We have a conf and classes directory, add to BBPATH
BBPATH := "${LAYERDIR}:${BBPATH}"
BBFILE_COLLECTIONS += "mylayer"
BBFILE_PATTERN_mylayer := "^${LAYERDIR}/"
BBFILE_PRIORITY_mylayer = "5"
- </literallayout>
- </para>
-
- <para>
- 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:
- <itemizedlist>
- <listitem><para><emphasis>Build for the Correct Target Architecture:</emphasis> The
- <filename>local.conf</filename> file in the build directory defines the build's
- target architecture.
- By default, <filename>MACHINE</filename> is set to
- <filename>qemux86</filename>, which specifies a 32-bit
- <trademark class='registered'>Intel</trademark> Architecture
- target machine suitable for the QEMU emulator.
- In this example, <filename>MACHINE</filename> is correctly configured.
- </para></listitem>
- <listitem><para><emphasis>Optimize Build Time:</emphasis> Also in the
- <filename>local.conf</filename> file are two variables that can speed your
- build time if your host supports multi-core and multi-thread capabilities:
- <filename>BB_NUMBER_THREADS</filename> and <filename>PARALLEL_MAKE</filename>.
- If the host system has multiple cores then you can optimize build time
- by setting both these variables to twice the number of
- cores.</para></listitem>
- <listitem><para><emphasis>Identify Your <filename>meta-mylayer</filename>
- Layer:</emphasis> The <filename>BBLAYERS</filename> variable in the
- <filename>bblayers.conf</filename> file found in the
- <filename>poky/build/conf</filename> directory needs to have the path to your local
- <filename>meta-mylayer</filename> layer.
- By default, the <filename>BBLAYERS</filename> variable contains paths to
- <filename>meta</filename>, <filename>meta-yocto</filename>, and
- <filename>meta-yocto-bsp</filename> in the
- <filename>poky</filename> Git repository.
- Add the path to your <filename>meta-mylayer</filename> location.
- Be sure to substitute your user information in the statement.
- Here is an example:
- <literallayout class='monospaced'>
- BBLAYERS = " \
- /home/scottrif/poky/meta \
- /home/scottrif/poky/meta-yocto \
- /home/scottrif/poky/meta-yocto-bsp \
- /home/scottrif/poky/meta-mylayer \
- "
- </literallayout></para></listitem>
- <listitem><para><emphasis>Create a bbappend File:</emphasis> You need to create
- an append file for the main 3.4 kernel recipe.
- Create the append file in the <filename>linux</filename> directory you
- created earlier within your layer.
- Assuming the patch file is named
- <filename>0001-documentation-calibrate.c.patch</filename>, your append
- file, which must be named <filename>linux-yocto_3.4.bbappend</filename>,
- has these statements:
- <literallayout class='monospaced'>
+ </literallayout>
+ Notice <filename>mylayer</filename> as part of the last three
+ statements.</para></listitem>
+ <listitem><para><emphasis>Create the kernel recipe append file</emphasis>:
+ Move to the <filename>meta-mylayer/recipes-kernel/linux</filename> directory and create
+ the <filename>linux-yocto_3.4.bbappend</filename> file as follows:
+ <literallayout class='monospaced'>
FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
- SRC_URI += "file://0001-documentation-calibrate.c.patch"
+ SRC_URI += "file://0001-calibrate.c.patch"
PRINC := "${@int(PRINC) + 1}"
- </literallayout>
- The <filename>FILESEXTRAPATHS</filename> and <filename>SRC_URI</filename>
- statements ensure the OpenEmbedded build system picks up the patch file.
- </para></listitem>
- </itemizedlist>
- </para>
- </section>
+ </literallayout>
+ The <filename>FILESEXTRAPATHS</filename> and <filename>SRC_URI</filename>
+ statements enable the OpenEmbedded build system to find the patch file.
+ </para></listitem>
+ <listitem><para><emphasis>Put the patch file in your layer</emphasis>:
+ Move the <filename>0001-calibrate.c.patch</filename> file to
+ the <filename>meta-mylayer/recipes-kernel/linux/linux-yocto</filename>
+ directory.</para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+
+ <section id='set-up-for-the-build'>
+ <title>Set Up for the Build</title>
+
+ <para>
+ 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:
+ <itemizedlist>
+ <listitem><para><emphasis>Build for the Correct Target Architecture:</emphasis> The
+ <filename>local.conf</filename> file in the build directory defines the build's
+ target architecture.
+ By default, <filename>MACHINE</filename> is set to
+ <filename>qemux86</filename>, which specifies a 32-bit
+ <trademark class='registered'>Intel</trademark> Architecture
+ target machine suitable for the QEMU emulator.
+ In this example, <filename>MACHINE</filename> is correctly configured.
+ </para></listitem>
+ <listitem><para><emphasis>Optimize Build Time:</emphasis> Also in the
+ <filename>local.conf</filename> file are two variables that can speed your
+ build time if your host supports multi-core and multi-thread capabilities:
+ <filename>BB_NUMBER_THREADS</filename> and <filename>PARALLEL_MAKE</filename>.
+ If the host system has multiple cores then you can optimize build time
+ by setting both these variables to twice the number of
+ cores.</para></listitem>
+ <listitem><para><emphasis>Identify Your <filename>meta-mylayer</filename>
+ Layer:</emphasis> The <filename>BBLAYERS</filename> variable in the
+ <filename>bblayers.conf</filename> file found in the
+ <filename>poky/build/conf</filename> directory needs to have the path to your local
+ <filename>meta-mylayer</filename> layer.
+ By default, the <filename>BBLAYERS</filename> variable contains paths to
+ <filename>meta</filename>, <filename>meta-yocto</filename>, and
+ <filename>meta-yocto-bsp</filename> in the
+ <filename>poky</filename> Git repository.
+ Add the path to your <filename>meta-mylayer</filename> location.
+ Be sure to substitute your user information in the statement:
+ <literallayout class='monospaced'>
+ BBLAYERS = " \
+ /home/<user>/poky/meta \
+ /home/<user>/poky/meta-yocto \
+ /home/<user>/poky/meta-yocto-bsp \
+ /home/<user>/poky/meta-mylayer \
+ "
+ </literallayout></para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
- <section id='building-and-booting-the-modified-qemu-kernel-image'>
- <title>Building and Booting the Modified QEMU Kernel Image</title>
+ <section id='build-and-booting-the-modified-qemu-kernel-image'>
+ <title>Build and Booting the Modified QEMU Kernel Image</title>
<para>
- Next, you need to build the modified image.
- Do the following:
+ The following steps build and boot your modified kernel image:
<orderedlist>
- <listitem><para>Your environment should be set up since you previously sourced
+ <listitem><para><emphasis>Be sure your build environment is initialized</emphasis>:
+ Your environment should be set up since you previously sourced
the <filename>&OE_INIT_FILE;</filename> script.
If it isn't, source the script again from <filename>poky</filename>.
<literallayout class='monospaced'>
$ source &OE_INIT_FILE;
</literallayout>
</para></listitem>
- <listitem><para>Be sure old images are cleaned out by running the
+ <listitem><para><emphasis>Clean up</emphasis>:
+ Be sure old images are cleaned out by running the
<filename>cleanall</filename> BitBake task as follows from your build directory:
<literallayout class='monospaced'>
$ bitbake -c cleanall linux-yocto
directory inside the build directory.
Always use the BitBake <filename>cleanall</filename> task to clear
out previous builds.</note></para></listitem>
- <listitem><para>Next, build the kernel image using this command:
+ <listitem><para><emphasis>Build the image</emphasis>:
+ Next, build the kernel image using this command:
<literallayout class='monospaced'>
$ bitbake -k linux-yocto
</literallayout></para></listitem>
- <listitem><para>Finally, boot the modified image in the QEMU emulator
- using this command:
- <literallayout class='monospaced'>
- $ runqemu qemux86
- </literallayout></para></listitem>
</orderedlist>
</para>
+ </section>
- <para>
- Log into the machine using <filename>root</filename> with no password and then
- use the following shell command to scroll through the console's boot output.
- <literallayout class='monospaced'>
- # dmesg | less
- </literallayout>
- </para>
+ <section id='verify-your-changes'>
+ <title>Verify Your Changes</title>
<para>
- You should see the results of your <filename>printk</filename> statements
- as part of the output.
+ These steps boot the image and allow you to see the changes
+ <orderedlist>
+ <listitem><para><emphasis>Boot the image</emphasis>:
+ Boot the modified image in the QEMU emulator
+ using this command:
+ <literallayout class='monospaced'>
+ $ runqemu qemux86
+ </literallayout></para></listitem>
+ <listitem><para><emphasis>Verify the changes</emphasis>:
+ Log into the machine using <filename>root</filename> with no password and then
+ use the following shell command to scroll through the console's boot output.
+ <literallayout class='monospaced'>
+ # dmesg | less
+ </literallayout>
+ You should see the results of your <filename>printk</filename> statements
+ as part of the output.</para></listitem>
+ </orderedlist>
</para>
</section>
</section>
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.
projects / thirdparty / openembedded / openembedded-core-contrib.git / commitdiff
