summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual/dev-manual-common-tasks.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/dev-manual/dev-manual-common-tasks.xml')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml324
1 files changed, 166 insertions, 158 deletions
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 @@
1626 </para> 1626 </para>
1627 1627
1628 <para> 1628 <para>
1629 The example assumes a clean build exists for the <filename>x86qemu</filename> 1629 The example assumes a clean build exists for the <filename>qemux86</filename>
1630 machine in a Source Directory named <filename>poky</filename>. 1630 machine in a Source Directory named <filename>poky</filename>.
1631 Furthermore, the <link linkend='build-directory'>Build Directory</link> is 1631 Furthermore, the <link linkend='build-directory'>Build Directory</link> is
1632 <filename>build</filename> and is located in <filename>poky</filename> and 1632 <filename>build</filename> and is located in <filename>poky</filename> and
@@ -1637,13 +1637,13 @@
1637 <title>Create a Layer for your Changes</title> 1637 <title>Create a Layer for your Changes</title>
1638 1638
1639 <para> 1639 <para>
1640 The first step is to isolate your changes into a layer: 1640 The first step is to create a layer so you can isolate your changes:
1641 <literallayout class='monospaced'> 1641 <literallayout class='monospaced'>
1642 $cd ~/poky 1642 $cd ~/poky
1643 $mkdir meta-mylayer 1643 $mkdir meta-mylayer
1644 </literallayout> 1644 </literallayout>
1645 Creating a directory that follows the Yocto Project layer naming 1645 Creating a directory that follows the Yocto Project layer naming
1646 conventions sets up the area for your changes. 1646 conventions sets up the layer for your changes.
1647 The layer is where you place your configuration files, append 1647 The layer is where you place your configuration files, append
1648 files, and patch files. 1648 files, and patch files.
1649 To learn more about creating a layer and filling it with the 1649 To learn more about creating a layer and filling it with the
@@ -1657,26 +1657,24 @@
1657 1657
1658 <para> 1658 <para>
1659 Each time you build a kernel image, the kernel source code is fetched 1659 Each time you build a kernel image, the kernel source code is fetched
1660 and unpacked into a temporary location in the <link linkend='build-directory'>Build Directory</link>. 1660 and unpacked into the following directory:
1661 See the "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>"
1662 section for a description of where the OpenEmbedded build system places
1663 kernel source files during a build.
1664 Following is where machine-specific source code is temporarily stored
1665 during the build:
1666 <literallayout class='monospaced'> 1661 <literallayout class='monospaced'>
1667 ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}-${PV}-${PR} 1662 ${S}/linux
1668 </literallayout> 1663 </literallayout>
1664 See the "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>"
1665 section and the
1666 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink> variable
1667 for more information about where source is kept during a build.
1669 For this example, the directory that 1668 For this example, the directory that
1670 holds the temporary source code is here: 1669 holds the temporary source code is here:
1671 <literallayout class='monospaced'> 1670 <literallayout class='monospaced'>
1672 ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-3.4.11+git1+5bdc...85f-r4.3 1671 ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-3.4.11+git1+5bdc...85f-r4.3/linux
1673 </literallayout> 1672 </literallayout>
1674 Within the <filename>linux</filename> directory, you find directories for
1675 the source.
1676 </para> 1673 </para>
1677 1674
1678 <para> 1675 <para>
1679 For this example, we are going to patch the <filename>init/calibrate.c</filename> file 1676 For this example, we are going to patch the
1677 <filename>init/calibrate.c</filename> file
1680 by adding some simple console <filename>printk</filename> statements that we can 1678 by adding some simple console <filename>printk</filename> statements that we can
1681 see when we boot the image using QEMU. 1679 see when we boot the image using QEMU.
1682 </para> 1680 </para>
@@ -1686,39 +1684,31 @@
1686 <title>Creating the Patch</title> 1684 <title>Creating the Patch</title>
1687 1685
1688 <para> 1686 <para>
1689 Two methods exist by which you can create the patch: Git workflow and Quilt workflow. 1687 Two methods exist by which you can create the patch:
1688 <link linkend='using-a-git-workflow'>Git workflow</link> and
1689 <link linkend='using-a-quilt-workflow'>Quilt workflow</link>.
1690 For kernel patches, the Git workflow is more appropriate. 1690 For kernel patches, the Git workflow is more appropriate.
1691 This section assumes the Git workflow. 1691 This section assumes the Git workflow and shows the steps specific to
1692 </para> 1692 this example.
1693 1693 <orderedlist>
1694 <para> 1694 <listitem><para><emphasis>Change the working directory</emphasis>:
1695 To create the patch for the <filename>calibrate.c</filename>, follow steps 1695 Change to where the kernel source code is before making
1696 3 through 12 outlined in the 1696 your edits to the <filename>calibrate.c</filename> file:
1697 "<link linkend='using-a-git-workflow'>Using a Git Workflow</link>" 1697 <literallayout class='monospaced'>
1698 section. 1698 $ cd ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-${PV}-${PR}/linux
1699 For step 6 (Edit the Files), do the following: 1699 </literallayout>
1700 </para> 1700 Because you are working in an established Git repository,
1701 1701 you must be in this directory in order to commit your changes
1702 <para> 1702 and create the patch file.
1703 Locate the <filename>void __cpuinit calibrate_delay(void)</filename> 1703 <note>The <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> and
1704 function: 1704 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> variables
1705 <literallayout class='monospaced'> 1705 represent the version and revision for the
1706 void __cpuinit calibrate_delay(void) 1706 <filename>linux-yocto</filename> recipe.
1707 { 1707 </note></para></listitem>
1708 unsigned long lpj; 1708 <listitem><para><emphasis>Edit the source file</emphasis>:
1709 static bool printed; 1709 Edit the <filename>init/calibrate.c</filename> file to have the
1710 int this_cpu = smp_processor_id(); 1710 following changes:
1711 1711 <literallayout class='monospaced'>
1712 if (per_cpu(cpu_loops_per_jiffy, this_cpu)) {
1713 .
1714 .
1715 .
1716 </literallayout>
1717 </para>
1718
1719 <para>
1720 Alter the code as follows:
1721 <literallayout class='monospaced'>
1722 void __cpuinit calibrate_delay(void) 1712 void __cpuinit calibrate_delay(void)
1723 { 1713 {
1724 unsigned long lpj; 1714 unsigned long lpj;
@@ -1735,44 +1725,49 @@
1735 . 1725 .
1736 . 1726 .
1737 . 1727 .
1738 </literallayout> 1728 </literallayout></para></listitem>
1729 <listitem><para><emphasis>Stage and commit your changes</emphasis>:
1730 These Git commands list out the changed file, stage it, and then
1731 commit the files:
1732 <literallayout class='monospaced'>
1733 $ git status
1734 $ git add init/calibrate.c
1735 $ git commit
1736 </literallayout></para></listitem>
1737 <listitem><para><emphasis>Generate the patch file</emphasis>:
1738 This Git command creates the a patch file named
1739 <filename>0001-calibrate.c.patch</filename> in the current directory.
1740 <literallayout class='monospaced'>
1741 $ git format-patch HEAD~1
1742 </literallayout>
1743 <note>The name of the patch file is based on your commit summary
1744 line.</note>
1745 </para></listitem>
1746 </orderedlist>
1739 </para> 1747 </para>
1740 </section> 1748 </section>
1741 1749
1742 <section id='get-your-layer-setup-for-the-build'> 1750 <section id='get-your-layer-setup-for-the-build'>
1743 <title>Get Your Layer Setup for the Build</title> 1751 <title>Get Your Layer Setup for the Build</title>
1744 1752
1745 <para> 1753 <para>These steps get your layer set up for the build:
1746 At this point, you have a patch file in the kernel's source code directory. 1754 <orderedlist>
1747 The patch file is named according to the commit's summary line and ends 1755 <listitem><para><emphasis>Create additional structure</emphasis>:
1748 with <filename>.patch</filename>. 1756 Create the additional layer structure:
1749 For this example, it is named <filename>0001-calibrate.c.patch</filename>. 1757 <literallayout class='monospaced'>
1750 </para>
1751
1752 <para>
1753 You need to move the patch file to your layer next.
1754 The patch file needs to reside in the
1755 <filename>meta-mylayer/recipes-kernel/linux/linux-yocto</filename> directory.
1756 Create this directory path within your layer and move the patch file.
1757 This directory path mirrors that used by the main kernel recipe in
1758 the Source Directory (<filename>poky</filename>).
1759 <literallayout class='monospaced'>
1760 $ cd ~/poky/meta-mylayer 1758 $ cd ~/poky/meta-mylayer
1759 $ mkdir conf
1761 $ mkdir recipes-kernel 1760 $ mkdir recipes-kernel
1762 $ mkdir recipes-kernel/linux 1761 $ mkdir recipes-kernel/linux
1763 $ mkdir recipes-kernel/linux/linux-yocto 1762 $ mkdir recipes-kernel/linux/linux-yocto
1764 </literallayout> 1763 </literallayout>
1765 </para> 1764 The <filename>conf</filename> directory holds your configuration files, while the
1766 1765 <filename>recipes-kernel</filename> directory holds your append file and
1767 <para> 1766 your patch file.</para></listitem>
1768 Next, you need to create a <filename>conf</filename> directory in your layer 1767 <listitem><para><emphasis>Create the layer configuration file</emphasis>:
1769 and within it create the <filename>layer.conf</filename> file. 1768 Move to the <filename>meta-mylayer/conf</filename> directory and create
1770 You can find information on this in the 1769 the <filename>layer.conf</filename> file as follows:
1771 "<link linkend='creating-your-own-layer'>Creating Your Own Layer</link>" 1770 <literallayout class='monospaced'>
1772 section.
1773 Here is what your <filename>layer.conf</filename> should look like for this
1774 example:
1775 <literallayout class='monospaced'>
1776 # We have a conf and classes directory, add to BBPATH 1771 # We have a conf and classes directory, add to BBPATH
1777 BBPATH := "${LAYERDIR}:${BBPATH}" 1772 BBPATH := "${LAYERDIR}:${BBPATH}"
1778 1773
@@ -1783,80 +1778,85 @@
1783 BBFILE_COLLECTIONS += "mylayer" 1778 BBFILE_COLLECTIONS += "mylayer"
1784 BBFILE_PATTERN_mylayer := "^${LAYERDIR}/" 1779 BBFILE_PATTERN_mylayer := "^${LAYERDIR}/"
1785 BBFILE_PRIORITY_mylayer = "5" 1780 BBFILE_PRIORITY_mylayer = "5"
1786 </literallayout> 1781 </literallayout>
1787 </para> 1782 Notice <filename>mylayer</filename> as part of the last three
1788 1783 statements.</para></listitem>
1789 <para> 1784 <listitem><para><emphasis>Create the kernel recipe append file</emphasis>:
1790 Do the following to make sure the build parameters are set up for the example. 1785 Move to the <filename>meta-mylayer/recipes-kernel/linux</filename> directory and create
1791 Once you set up these build parameters, they do not have to change unless you 1786 the <filename>linux-yocto_3.4.bbappend</filename> file as follows:
1792 change the target architecture of the machine you are building: 1787 <literallayout class='monospaced'>
1793 <itemizedlist>
1794 <listitem><para><emphasis>Build for the Correct Target Architecture:</emphasis> The
1795 <filename>local.conf</filename> file in the build directory defines the build's
1796 target architecture.
1797 By default, <filename>MACHINE</filename> is set to
1798 <filename>qemux86</filename>, which specifies a 32-bit
1799 <trademark class='registered'>Intel</trademark> Architecture
1800 target machine suitable for the QEMU emulator.
1801 In this example, <filename>MACHINE</filename> is correctly configured.
1802 </para></listitem>
1803 <listitem><para><emphasis>Optimize Build Time:</emphasis> Also in the
1804 <filename>local.conf</filename> file are two variables that can speed your
1805 build time if your host supports multi-core and multi-thread capabilities:
1806 <filename>BB_NUMBER_THREADS</filename> and <filename>PARALLEL_MAKE</filename>.
1807 If the host system has multiple cores then you can optimize build time
1808 by setting both these variables to twice the number of
1809 cores.</para></listitem>
1810 <listitem><para><emphasis>Identify Your <filename>meta-mylayer</filename>
1811 Layer:</emphasis> The <filename>BBLAYERS</filename> variable in the
1812 <filename>bblayers.conf</filename> file found in the
1813 <filename>poky/build/conf</filename> directory needs to have the path to your local
1814 <filename>meta-mylayer</filename> layer.
1815 By default, the <filename>BBLAYERS</filename> variable contains paths to
1816 <filename>meta</filename>, <filename>meta-yocto</filename>, and
1817 <filename>meta-yocto-bsp</filename> in the
1818 <filename>poky</filename> Git repository.
1819 Add the path to your <filename>meta-mylayer</filename> location.
1820 Be sure to substitute your user information in the statement.
1821 Here is an example:
1822 <literallayout class='monospaced'>
1823 BBLAYERS = " \
1824 /home/scottrif/poky/meta \
1825 /home/scottrif/poky/meta-yocto \
1826 /home/scottrif/poky/meta-yocto-bsp \
1827 /home/scottrif/poky/meta-mylayer \
1828 "
1829 </literallayout></para></listitem>
1830 <listitem><para><emphasis>Create a bbappend File:</emphasis> You need to create
1831 an append file for the main 3.4 kernel recipe.
1832 Create the append file in the <filename>linux</filename> directory you
1833 created earlier within your layer.
1834 Assuming the patch file is named
1835 <filename>0001-documentation-calibrate.c.patch</filename>, your append
1836 file, which must be named <filename>linux-yocto_3.4.bbappend</filename>,
1837 has these statements:
1838 <literallayout class='monospaced'>
1839 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" 1788 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
1840 1789
1841 SRC_URI += "file://0001-documentation-calibrate.c.patch" 1790 SRC_URI += "file://0001-calibrate.c.patch"
1842 1791
1843 PRINC := "${@int(PRINC) + 1}" 1792 PRINC := "${@int(PRINC) + 1}"
1844 </literallayout> 1793 </literallayout>
1845 The <filename>FILESEXTRAPATHS</filename> and <filename>SRC_URI</filename> 1794 The <filename>FILESEXTRAPATHS</filename> and <filename>SRC_URI</filename>
1846 statements ensure the OpenEmbedded build system picks up the patch file. 1795 statements enable the OpenEmbedded build system to find the patch file.
1847 </para></listitem> 1796 </para></listitem>
1848 </itemizedlist> 1797 <listitem><para><emphasis>Put the patch file in your layer</emphasis>:
1849 </para> 1798 Move the <filename>0001-calibrate.c.patch</filename> file to
1850 </section> 1799 the <filename>meta-mylayer/recipes-kernel/linux/linux-yocto</filename>
1800 directory.</para></listitem>
1801 </orderedlist>
1802 </para>
1803 </section>
1804
1805 <section id='set-up-for-the-build'>
1806 <title>Set Up for the Build</title>
1807
1808 <para>
1809 Do the following to make sure the build parameters are set up for the example.
1810 Once you set up these build parameters, they do not have to change unless you
1811 change the target architecture of the machine you are building:
1812 <itemizedlist>
1813 <listitem><para><emphasis>Build for the Correct Target Architecture:</emphasis> The
1814 <filename>local.conf</filename> file in the build directory defines the build's
1815 target architecture.
1816 By default, <filename>MACHINE</filename> is set to
1817 <filename>qemux86</filename>, which specifies a 32-bit
1818 <trademark class='registered'>Intel</trademark> Architecture
1819 target machine suitable for the QEMU emulator.
1820 In this example, <filename>MACHINE</filename> is correctly configured.
1821 </para></listitem>
1822 <listitem><para><emphasis>Optimize Build Time:</emphasis> Also in the
1823 <filename>local.conf</filename> file are two variables that can speed your
1824 build time if your host supports multi-core and multi-thread capabilities:
1825 <filename>BB_NUMBER_THREADS</filename> and <filename>PARALLEL_MAKE</filename>.
1826 If the host system has multiple cores then you can optimize build time
1827 by setting both these variables to twice the number of
1828 cores.</para></listitem>
1829 <listitem><para><emphasis>Identify Your <filename>meta-mylayer</filename>
1830 Layer:</emphasis> The <filename>BBLAYERS</filename> variable in the
1831 <filename>bblayers.conf</filename> file found in the
1832 <filename>poky/build/conf</filename> directory needs to have the path to your local
1833 <filename>meta-mylayer</filename> layer.
1834 By default, the <filename>BBLAYERS</filename> variable contains paths to
1835 <filename>meta</filename>, <filename>meta-yocto</filename>, and
1836 <filename>meta-yocto-bsp</filename> in the
1837 <filename>poky</filename> Git repository.
1838 Add the path to your <filename>meta-mylayer</filename> location.
1839 Be sure to substitute your user information in the statement:
1840 <literallayout class='monospaced'>
1841 BBLAYERS = " \
1842 /home/&lt;user&gt;/poky/meta \
1843 /home/&lt;user&gt;/poky/meta-yocto \
1844 /home/&lt;user&gt;/poky/meta-yocto-bsp \
1845 /home/&lt;user&gt;/poky/meta-mylayer \
1846 "
1847 </literallayout></para></listitem>
1848 </itemizedlist>
1849 </para>
1850 </section>
1851 1851
1852 <section id='building-and-booting-the-modified-qemu-kernel-image'> 1852 <section id='build-and-booting-the-modified-qemu-kernel-image'>
1853 <title>Building and Booting the Modified QEMU Kernel Image</title> 1853 <title>Build and Booting the Modified QEMU Kernel Image</title>
1854 1854
1855 <para> 1855 <para>
1856 Next, you need to build the modified image. 1856 The following steps build and boot your modified kernel image:
1857 Do the following:
1858 <orderedlist> 1857 <orderedlist>
1859 <listitem><para>Your environment should be set up since you previously sourced 1858 <listitem><para><emphasis>Be sure your build environment is initialized</emphasis>:
1859 Your environment should be set up since you previously sourced
1860 the <filename>&OE_INIT_FILE;</filename> script. 1860 the <filename>&OE_INIT_FILE;</filename> script.
1861 If it isn't, source the script again from <filename>poky</filename>. 1861 If it isn't, source the script again from <filename>poky</filename>.
1862 <literallayout class='monospaced'> 1862 <literallayout class='monospaced'>
@@ -1864,7 +1864,8 @@
1864 $ source &OE_INIT_FILE; 1864 $ source &OE_INIT_FILE;
1865 </literallayout> 1865 </literallayout>
1866 </para></listitem> 1866 </para></listitem>
1867 <listitem><para>Be sure old images are cleaned out by running the 1867 <listitem><para><emphasis>Clean up</emphasis>:
1868 Be sure old images are cleaned out by running the
1868 <filename>cleanall</filename> BitBake task as follows from your build directory: 1869 <filename>cleanall</filename> BitBake task as follows from your build directory:
1869 <literallayout class='monospaced'> 1870 <literallayout class='monospaced'>
1870 $ bitbake -c cleanall linux-yocto 1871 $ bitbake -c cleanall linux-yocto
@@ -1873,29 +1874,36 @@
1873 directory inside the build directory. 1874 directory inside the build directory.
1874 Always use the BitBake <filename>cleanall</filename> task to clear 1875 Always use the BitBake <filename>cleanall</filename> task to clear
1875 out previous builds.</note></para></listitem> 1876 out previous builds.</note></para></listitem>
1876 <listitem><para>Next, build the kernel image using this command: 1877 <listitem><para><emphasis>Build the image</emphasis>:
1878 Next, build the kernel image using this command:
1877 <literallayout class='monospaced'> 1879 <literallayout class='monospaced'>
1878 $ bitbake -k linux-yocto 1880 $ bitbake -k linux-yocto
1879 </literallayout></para></listitem> 1881 </literallayout></para></listitem>
1880 <listitem><para>Finally, boot the modified image in the QEMU emulator
1881 using this command:
1882 <literallayout class='monospaced'>
1883 $ runqemu qemux86
1884 </literallayout></para></listitem>
1885 </orderedlist> 1882 </orderedlist>
1886 </para> 1883 </para>
1884 </section>
1887 1885
1888 <para> 1886 <section id='verify-your-changes'>
1889 Log into the machine using <filename>root</filename> with no password and then 1887 <title>Verify Your Changes</title>
1890 use the following shell command to scroll through the console's boot output.
1891 <literallayout class='monospaced'>
1892 # dmesg | less
1893 </literallayout>
1894 </para>
1895 1888
1896 <para> 1889 <para>
1897 You should see the results of your <filename>printk</filename> statements 1890 These steps boot the image and allow you to see the changes
1898 as part of the output. 1891 <orderedlist>
1892 <listitem><para><emphasis>Boot the image</emphasis>:
1893 Boot the modified image in the QEMU emulator
1894 using this command:
1895 <literallayout class='monospaced'>
1896 $ runqemu qemux86
1897 </literallayout></para></listitem>
1898 <listitem><para><emphasis>Verify the changes</emphasis>:
1899 Log into the machine using <filename>root</filename> with no password and then
1900 use the following shell command to scroll through the console's boot output.
1901 <literallayout class='monospaced'>
1902 # dmesg | less
1903 </literallayout>
1904 You should see the results of your <filename>printk</filename> statements
1905 as part of the output.</para></listitem>
1906 </orderedlist>
1899 </para> 1907 </para>
1900 </section> 1908 </section>
1901 </section> 1909 </section>
@@ -2625,8 +2633,8 @@
2625 One of the concerns for a development organization using open source 2633 One of the concerns for a development organization using open source
2626 software is how to maintain compliance with various open source 2634 software is how to maintain compliance with various open source
2627 licensing during the lifecycle of the product. 2635 licensing during the lifecycle of the product.
2628 While this section is not meant to be legal advice or to 2636 While this section does not provide legal advice or
2629 comprehensively cover all scenarios, it is meant to 2637 comprehensively cover all scenarios, it does
2630 present methods that you can use to 2638 present methods that you can use to
2631 meet the compliance requirements during a software 2639 meet the compliance requirements during a software
2632 release. 2640 release.