summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual/dev-manual-model.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/dev-manual/dev-manual-model.xml')
-rw-r--r--documentation/dev-manual/dev-manual-model.xml872
1 files changed, 664 insertions, 208 deletions
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
index 59d6adb3fc..15b815d417 100644
--- a/documentation/dev-manual/dev-manual-model.xml
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -1242,7 +1242,7 @@
1242 <filename>aclocal</filename>, 1242 <filename>aclocal</filename>,
1243 <filename>autoconf</filename>, 1243 <filename>autoconf</filename>,
1244 <filename>autoheader</filename>, 1244 <filename>autoheader</filename>,
1245 <filename>automake --a</filename>, and 1245 <filename>automake &dash;&dash;a</filename>, and
1246 <filename>./configure</filename>. 1246 <filename>./configure</filename>.
1247 Click on the "Console" tab beneath your source code to 1247 Click on the "Console" tab beneath your source code to
1248 see the results of reconfiguring your project. 1248 see the results of reconfiguring your project.
@@ -1668,104 +1668,597 @@
1668 </section> 1668 </section>
1669</section> 1669</section>
1670 1670
1671<section id="modifying-temporary-source-code"> 1671<section id="dev-modifying-source-code">
1672 <title>Modifying Temporary Source Code</title> 1672 <title>Modifying Source Code</title>
1673 1673
1674 <para> 1674 <para>
1675 You might 1675 A common development workflow consists of modifying project source
1676 find it helpful during development to modify the temporary source code used by recipes 1676 files that are external to the Yocto Project and then integrating
1677 to build packages. 1677 that project's build output into an image built using the Yocto
1678 For example, suppose you are developing a patch and you need to experiment a bit 1678 Project.
1679 to figure out your solution. 1679 Given this scenario, development engineers typically want to stick
1680 After you have initially built the package, you can iteratively tweak the 1680 to their familiar project development tools and methods, which allows
1681 source code, which is located in the 1681 them to just focus on the project.
1682 <link linkend='build-directory'>Build Directory</link>, and then
1683 you can force a re-compile and quickly test your altered code.
1684 Once you settle on a solution, you can then preserve your changes in the form of
1685 patches.
1686 You can accomplish these steps all within either a
1687 <ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink> or
1688 <link linkend='git'>Git</link> workflow.
1689 </para> 1682 </para>
1690 1683
1691 <section id='finding-the-temporary-source-code'> 1684 <para>
1692 <title>Finding the Temporary Source Code</title> 1685 Several workflows exist that allow you to develop, build, and test
1686 code that is going to be integrated into an image built using the
1687 Yocto Project.
1688 This section describes two:
1689 <itemizedlist>
1690 <listitem><para><emphasis><filename>devtool</filename>:</emphasis>
1691 A set of tools and
1692 enhancements put together by the Yocto Project team that
1693 makes it easier for you to modify code that is external to
1694 the Yocto Project.
1695 Section
1696 "<link linkend='using-devtool-in-your-workflow'>Using <filename>devtool</filename> in Your Workflow</link>"
1697 describes this workflow.
1698 If you want more information that showcases the workflow, click
1699 <ulink url='https://drive.google.com/a/linaro.org/file/d/0B3KGzY5fW7laTDVxUXo3UDRvd2s/view'>here</ulink>
1700 for an excellent presentation by Trevor Woerner that
1701 provides detailed background information and a complete
1702 working tutorial.
1703 </para></listitem>
1704 <listitem><para><emphasis><ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink>:</emphasis>
1705 A powerful tool that allows you to capture source
1706 code changes without having a clean source tree.
1707 While Quilt is not the preferred workflow of the two, this
1708 section includes it for users that are committed to using
1709 the tool.
1710 See the
1711 "<link linkend='using-a-quilt-workflow'>Using Quilt in Your Workflow</link>"
1712 section for more information.
1713 </para></listitem>
1714 </itemizedlist>
1715 </para>
1716
1717 <section id='using-devtool-in-your-workflow'>
1718 <title>Using <filename>devtool</filename> in Your Workflow</title>
1693 1719
1694 <para> 1720 <para>
1695 During a build, the unpacked temporary source code used by recipes 1721 As mentioned earlier, <filename>devtool</filename> helps
1696 to build packages is available in the Build Directory as 1722 you easily develop projects whose build output must be part of
1697 defined by the 1723 an image built using the Yocto Project.
1698 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename> variable. 1724 The remainder of this section presents the workflow you would
1699 Below is the default value for the <filename>S</filename> variable as defined in the 1725 use that includes <filename>devtool</filename>.
1700 <filename>meta/conf/bitbake.conf</filename> configuration file in the
1701 <link linkend='source-directory'>Source Directory</link>:
1702 <literallayout class='monospaced'>
1703 S = "${WORKDIR}/${BP}"
1704 </literallayout>
1705 You should be aware that many recipes override the <filename>S</filename> variable.
1706 For example, recipes that fetch their source from Git usually set
1707 <filename>S</filename> to <filename>${WORKDIR}/git</filename>.
1708 <note> 1726 <note>
1709 The 1727 The workflow considers the entire build process for the
1710 <ulink url='&YOCTO_DOCS_REF_URL;#var-BP'><filename>BP</filename></ulink> 1728 image and not just modification of the external source
1711 represents the base recipe name, which consists of the name and version: 1729 code.
1712 <literallayout class='monospaced'>
1713 BP = "${BPN}-${PV}"
1714 </literallayout>
1715 </note> 1730 </note>
1716 </para> 1731 </para>
1717 1732
1718 <para> 1733 <section id='establish-the-reference-image'>
1719 The path to the work directory for the recipe 1734 <title>Establish the Reference Image</title>
1720 (<ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>)
1721 is defined as follows:
1722 <literallayout class='monospaced'>
1723 ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}
1724 </literallayout>
1725 The actual directory depends on several things:
1726 <itemizedlist>
1727 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>:
1728 The top-level build output directory</listitem>
1729 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></ulink>:
1730 The target system identifier</listitem>
1731 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>:
1732 The recipe name</listitem>
1733 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTENDPE'><filename>EXTENDPE</filename></ulink>:
1734 The epoch - (if
1735 <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>
1736 is not specified, which is usually the case for most
1737 recipes, then <filename>EXTENDPE</filename> is blank)</listitem>
1738 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>:
1739 The recipe version</listitem>
1740 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>:
1741 The recipe revision</listitem>
1742 </itemizedlist>
1743 </para>
1744 1735
1745 <para> 1736 <para>
1746 As an example, assume a Source Directory top-level folder 1737 Local repositories for both the Yocto Project and your
1747 name <filename>poky</filename>, a default Build Directory at 1738 project must exist in addition to the image built by
1748 <filename>poky/build</filename>, and a 1739 the OpenEmbedded build system.
1749 <filename>qemux86-poky-linux</filename> machine target 1740 The steps to clone the <filename>poky</filename> Git
1750 system. 1741 repository, build out an image, and test it using QEMU
1751 Furthermore, suppose your recipe is named 1742 are well documented as follows:
1752 <filename>foo_1.3.0.bb</filename>. 1743 <itemizedlist>
1753 In this case, the work directory the build system uses to 1744 <listitem><para>
1754 build the package would be as follows: 1745 For information on how to set up a local copy of the
1755 <literallayout class='monospaced'> 1746 <filename>poky</filename> repository and on how to
1756 poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0 1747 build a Yocto Project image, see the
1757 </literallayout> 1748 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
1758 </para> 1749 section in the Yocto Project Quick Start.
1750 </para></listitem>
1751 <listitem><para>
1752 For information on how to test an image using QEMU, see
1753 the
1754 "<link linkend='dev-manual-qemu'>Using the Quick EMUlator (QEMU)</link>"
1755 section.
1756 </para></listitem>
1757 </itemizedlist>
1758 </para>
1759
1760 <para>
1761 Before you start making modifications to your project's
1762 source code, you should be sure you have the appropriate
1763 local repositories and have a base image built using
1764 BitBake that you can run on QEMU.
1765 </para>
1766 </section>
1767
1768 <section id='update-your-external-source'>
1769 <title>Update Your External Source</title>
1770
1771 <para>
1772 Part of the development flow using
1773 <filename>devtool</filename> of course involves updating
1774 your source files.
1775 Several opportunities exist in the workflow to extract and
1776 work on the files.
1777 For now, just realize that you need to be able to have
1778 access to and edit files in your layer.
1779 One obvious solution is to initially extract the code into its
1780 own layer in preparation for modification.
1781 </para>
1782
1783 <para>
1784 Another option is to use the <filename>devtool</filename>
1785 command.
1786 <filename>devtool</filename> makes use of a
1787 "workspace" layer where much of the transitional work
1788 occurs, which is needed for setting up Metadata used by the
1789 OpenEmbedded build system that lets you build your software.
1790 Options exist using <filename>devtool</filename> that
1791 enable you to use the tool to extract source code.
1792 </para>
1793 </section>
1794
1795 <section id='use-devtool-to-integrate-your-code-with-the-image'>
1796 <title>Use <filename>dev-tool</filename> to Integrate Your Code with the Image</title>
1797
1798 <para>
1799 <filename>devtool</filename> automatically
1800 generates the needed Metadata that allows the OpenEmbedded
1801 build system to build your code into the image.
1802 Use the following command form:
1803 <literallayout class='monospaced'>
1804 $ devtool add <replaceable>your-project-name</replaceable>&nbsp;<replaceable>path-to-source</replaceable>/<replaceable>your-project-name</replaceable>
1805 </literallayout>
1806 Running <filename>devtool</filename> modifies the
1807 <filename>bblayers.conf</filename> used to build the
1808 image in the Yocto Project.
1809 For more information on the <filename>bblayers.conf</filename>,
1810 see the
1811 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
1812 section in the Yocto Project Board Support Package (BSP) Developer's Guide.
1813 </para>
1814
1815 <para>
1816 Running <filename>devtool</filename> adds a new workspace
1817 layer to the <filename>bblayers.conf</filename> file that
1818 is based on your project's location:
1819 <literallayout class='monospaced'>
1820 <replaceable>path-to-source</replaceable>/<replaceable>build-directory</replaceable>/<replaceable>workspace-layer</replaceable>
1821 </literallayout>
1822 By default, the name of the workspace layer is "workplace".
1823 </para>
1824
1825 <para>
1826 For details on the workspace layer created in the
1827 <replaceable>build-directory</replaceable>,
1828 see the
1829 "<link linkend='devtool-adding-a-new-recipe-to-the-workspace'>Adding a New Recipe to the Workspace Layer</link>"
1830 section.
1831 </para>
1832
1833 <para>
1834 Of course, each layer must have a
1835 <filename>layer.conf</filename> configuration file.
1836 <filename>devtool</filename> also creates this configuration
1837 file:
1838 <literallayout class='monospaced'>
1839 $ cat workspace/conf/layer.conf
1840 # ### workspace layer auto­generated by devtool ###
1841 BBPATH =. "${LAYERDIR}:"
1842 BBFILES += "${LAYERDIR}/recipes/*/*.bb \
1843 ${LAYERDIR}/appends/*.bbappend"
1844 BBFILE_COLLECTIONS += "workspacelayer"
1845 BBFILE_PATTERN_workspacelayer = "^${LAYERDIR}/"
1846 BBFILE_PATTERN_IGNORE_EMPTY_workspacelayer = "1"
1847 BBFILE_PRIORITY_workspacelayer = "99"
1848 </literallayout>
1849 </para>
1850
1851 <para>
1852 Running <filename>devtool</filename> also automatically
1853 generates your recipe:
1854 <literallayout class='monospaced'>
1855 $ cat workspace/recipes/<replaceable>your-project-name</replaceable>/<replaceable>your-project-name</replaceable>.bb
1856 # Recipe created by recipetool
1857 # This is the basis of a recipe and may need further editing in order to be fully functional.
1858 # (Feel free to remove these comments when editing.)
1859 #
1860 # Unable to find any files that looked like license statements. Check the accompanying
1861 # documentation and source headers and set LICENSE and LIC_FILES_CHKSUM accordingly.
1862 LICENSE = "CLOSED"
1863 LIC_FILES_CHKSUM = ""
1864
1865 # No information for SRC_URI yet (only an external source tree was
1866 # specified)
1867 SRC_URI = ""
1868
1869 DEPENDS = "libx11"
1870 # NOTE: if this software is not capable of being built in a separate build directory
1871 # from the source, you should replace autotools with autotools­-brokensep in the
1872 # inherit line
1873 inherit autotools
1874
1875 # Specify any options you want to pass to the configure script using EXTRA_OECONF:
1876 EXTRA_OECONF = ""
1877 </literallayout>
1878 </para>
1879
1880 <para>
1881 Lastly, the <filename>devtool</filename> creates the
1882 <filename>.bbappend</filename> file:
1883 <literallayout class='monospaced'>
1884 $ cat workspace/appends/<replaceable>your-project-name</replaceable>.bbappend
1885 inherit externalsrc
1886 EXTERNALSRC = "/<replaceable>path-to-source</replaceable>/<replaceable>your-project-name</replaceable>"
1887
1888 # initial_rev: <replaceable>commit-ID</replaceable>
1889 </literallayout>
1890 </para>
1891 </section>
1892
1893 <section id='build-your-project'>
1894 <title>Build Your Project</title>
1895
1896 <para>
1897 You can use BitBake or <filename>devtool</filename> to build
1898 your modified project.
1899 </para>
1900
1901 <para>
1902 To use BitBake, use the following:
1903 <literallayout class='monospaced'>
1904 $ bitbake <replaceable>your-project-name</replaceable>
1905 </literallayout>
1906 To use <filename>devtool</filename>, run the tool with the
1907 <filename>build</filename> option:
1908 <literallayout class='monospaced'>
1909 $ devtool build <replaceable>your-project-name</replaceable>
1910 </literallayout>
1911 </para>
1912 </section>
1913
1914 <section id='dev-build-the-image'>
1915 <title>Build the Image</title>
1916
1917 <para>
1918 The final step before testing is to rebuild the base image
1919 with your project changes as part of the image.
1920 Simply run BitBake again on your image.
1921 Here is an example that assumes
1922 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
1923 is set to "qemux86":
1924 <literallayout class='monospaced'>
1925 $ bitbake qemux86 <replaceable>image</replaceable>
1926 </literallayout>
1927 </para>
1928 </section>
1929
1930 <section id='dev-testing-the-image'>
1931 <title>Testing the Image</title>
1932
1933 <para>
1934 Once you have the image, you can test it using QEMU.
1935 Here is an example assuming "qemux86":
1936 <literallayout class='monospaced'>
1937 $ runqemu qemux86 <replaceable>image</replaceable>
1938 </literallayout>
1939 For information on how to test an image using QEMU, see the
1940 "<link linkend='dev-manual-qemu'>Using the Quick EMUlator (QEMU)</link>"
1941 section.
1942 </para>
1943 </section>
1944 </section>
1945
1946 <section id='devtool-quick-reference'>
1947 <title><filename>devtool</filename> Quick Reference</title>
1759 1948
1760 <para> 1949 <para>
1761 Now that you know where to locate the directory that has the temporary source code, 1950 <filename>devtool</filename> has more functionality than simply
1762 you can use a Quilt or Git workflow to make your edits, test the changes, 1951 adding a new recipe and the supporting Metadata to a temporary
1763 and preserve the changes in the form of patches. 1952 workspace layer.
1953 This section provides a short reference on
1954 <filename>devtool</filename> for most of the commands.
1764 </para> 1955 </para>
1956
1957 <section id='devtool-getting-help'>
1958 <title>Getting Help</title>
1959
1960 <para>
1961 The easiest way to get help with the
1962 <filename>devtool</filename> command is using the
1963 <filename>&dash;&dash;help</filename> option:
1964 <literallayout class='monospaced'>
1965 $ devtool &dash;&dash;help
1966 usage: devtool [-h] [&dash;&dash;basepath BASEPATH] [-d] [-q]
1967 [&dash;&dash;color {auto,always,never}]
1968 {create-workspace,deploy-target,undeploy-target,add,modify,extract,update-recipe,status,build,reset}
1969 ...
1970
1971 OpenEmbedded development tool
1972
1973 positional arguments:
1974 {create-workspace,deploy-target,undeploy-target,add,modify,extract,update-recipe,status,build,reset}
1975 create-workspace Set up a workspace
1976 deploy-target Deploy recipe output files to live target machine
1977 undeploy-target Undeploy recipe output files in live target machine
1978 add Add a new recipe
1979 modify Modify the source for an existing recipe
1980 extract Extract the source for an existing recipe
1981 update-recipe Apply changes from external source tree to recipe
1982 status Show status
1983 build Build recipe
1984 reset Remove a recipe from your workspace
1985
1986 optional arguments:
1987 -h, &dash;&dash;help show this help message and exit
1988 &dash;&dash;basepath BASEPATH Base directory of SDK / build directory
1989 -d, &dash;&dash;debug Enable debug output
1990 -q, &dash;&dash;quiet Print only errors
1991 &dash;&dash;color {auto,always,never}
1992 Colorize output
1993
1994 Use devtool &lt;command&gt; &dash;&dash;help to get help on a specific command
1995 </literallayout>
1996 </para>
1997
1998 <para>
1999 As directed in the general help output, you can get more
2000 syntax on a specific command by providing the command
2001 name and using <filename>&dash;&dash;help</filename>:
2002 <literallayout class='monospaced'>
2003 $ devtool add &dash;&dash;help
2004 usage: devtool add [-h] [&dash;&dash;version VERSION] recipename srctree
2005
2006 positional arguments:
2007 recipename Name for new recipe to add
2008 srctree Path to external source tree
2009
2010 optional arguments:
2011 -h, &dash;&dash;help show this help message and exit
2012 &dash;&dash;version VERSION, -V VERSION
2013 </literallayout>
2014 </para>
2015 </section>
2016
2017 <section id='devtool-adding-a-new-recipe-to-the-workspace'>
2018 <title>Adding a New Recipe to the Workspace Layer</title>
2019
2020 <para>
2021 Use the <filename>add</filename> command to add a new recipe
2022 to the workspace layer.
2023 The recipe you add should not exist -
2024 <filename>devtool</filename> creates it for you.
2025 The source files the recipe uses should exist in an external
2026 area.
2027 </para>
2028
2029 <para>
2030 The following example creates and adds a new recipe named
2031 <filename>jackson-2.0</filename> to the workspace layer.
2032 The source code built by the recipes resides in
2033 <filename>/home/scottrif/sources/jackson</filename>:
2034 <literallayout class='monospaced'>
2035 $ devtool add jackson-2.0 /home/scottrif/sources/jackson
2036 </literallayout>
2037 <note>
2038 For complete syntax, use the
2039 <filename>devtool add &dash;&dash;help</filename> command.
2040 </note>
2041 </para>
2042
2043 <para>
2044 If you add a recipe and the workspace layer does not exist,
2045 the command creates the layer and populates it as follows:
2046 </para>
2047
2048 <para>
2049 <imagedata fileref="figures/build-workspace-directory.png"
2050 width="6in" depth="4in" align="center" scale="100" />
2051 </para>
2052
2053 <para>
2054 <literallayout class='monospaced'>
2055 README - Provides information on what is in workspace layer and how to
2056 manage it.
2057
2058 appends - A directory that contains *.bbappend files.
2059
2060 conf - A configuration directory that contains the layer.conf file.
2061
2062 recipes - A directory containing recipes. This directory contains a
2063 folder for each directory added whose name matches that of the
2064 added recipe. devtool places the <replaceable>recipe</replaceable>.bb file
2065 within that sub-directory.
2066 </literallayout>
2067 </para>
2068
2069 <para>
2070 Running <filename>devtool add</filename> when the
2071 workspace layer exists causes the tool to add the recipe
2072 and append files into the existing workspace layer.
2073 </para>
2074 </section>
2075
2076 <section id='devtool-creating-the-workspace'>
2077 <title>Creating the Workspace Layer</title>
2078
2079 <para>
2080 Use the <filename>create-workspace</filename> command to
2081 create a new workspace layer in your
2082 <link linkend='build-directory'>Build Directory</link>.
2083 When you create a new workspace layer, it is populated with the
2084 <filename>README</filename> file and the
2085 <filename>conf</filename> directory only.
2086 </para>
2087
2088 <para>
2089 The following example creates a new workspace layer in your
2090 current working and by default names the workspace layer
2091 "workspace":
2092 <literallayout class='monospaced'>
2093 $ devtool create-workspace
2094 </literallayout>
2095 <note>
2096 For complete syntax, use the
2097 <filename>devtool create-workspace &dash;&dash;help</filename> command.
2098 </note>
2099 </para>
2100
2101 <para>
2102 You can create a workspace layer anywhere by supplying
2103 a pathname with the command.
2104 The following command creates a new workspace layer named
2105 "new-workspace":
2106 <literallayout class='monospaced'>
2107 $ devtool create-workspace /home/scottrif/new-workspace
2108 </literallayout>
2109 </para>
2110 </section>
2111
2112 <section id='devtool-modifying-a-recipe'>
2113 <title>Modifying a Recipe</title>
2114
2115 <para>
2116 Use the <filename>modify</filename> command to configure
2117 an external recipe in the workspace layer.
2118 This command is very similar to the
2119 <link linkend='devtool-adding-a-new-recipe-to-the-workspace'><filename>add</filename></link>
2120 command except that it does not physically create the
2121 recipe in the workspace layer because the recipe already
2122 exists in an external layer.
2123 </para>
2124
2125 <para>
2126 The <filename>modify</filename> command provides options
2127 that allow you to extract the source and provide a
2128 development branch name where you can do your work.
2129 You can use the following command to checkout the source
2130 files:
2131 <literallayout class='monospaced'>
2132 $ devtool modify -x <replaceable>recipe</replaceable>&nbsp;<replaceable>path-to-source</replaceable>
2133 </literallayout>
2134 Using the above command form, the default development branch
2135 would be "devtool".
2136 </para>
2137
2138 <para>
2139 If you want to name a development branch, use the
2140 <filename>-b</filename> option with the
2141 <filename>-x</filename> option:
2142 <literallayout class='monospaced'>
2143 $ devtool modify -x -b <replaceable>branch</replaceable>&nbsp;<replaceable>recipe</replaceable>&nbsp;<replaceable>path-to-source</replaceable>
2144 </literallayout>
2145 <note>
2146 For complete syntax, use the
2147 <filename>devtool modify &dash;&dash;help</filename> command.
2148 </note>
2149 </para>
2150 </section>
2151
2152 <section id='devtool-resetting-a-recipe'>
2153 <title>Resetting a Recipe</title>
2154
2155 <para>
2156 Use the <filename>reset</filename> command to remove a
2157 recipe and its configuration (e.g. the corresponding
2158 <filename>.bbappend</filename> file) from the workspace layer.
2159 Realize that this command deletes the recipe and and the
2160 append file.
2161 The command does not physically move them for you.
2162 Consequently, you must be sure to physically relocate your
2163 updated recipe and the append file outside of the workspace
2164 layer before running the <filename>reset</filename> command.
2165 <note>
2166 For complete syntax, use the
2167 <filename>devtool reset &dash;&dash;help</filename> command.
2168 </note>
2169 </para>
2170 </section>
2171
2172 <section id='devtool-updating-a-recipe'>
2173 <title>Updating a Recipe</title>
2174
2175 <para>
2176 Use the <filename>update-recipe</filename> command to cause
2177 <filename>devtool</filename> to update your recipe with patches
2178 that reflect changes you make to the source files.
2179 For example, if you know you are going to work on some
2180 code, you could first use the
2181 <link linkend='devtool-modifying-a-recipe'><filename>modify</filename></link>
2182 command to extract the code and set up the workspace.
2183 After which, you could modify, compile, and test the code
2184 in its own layer to which it was extracted.
2185 When you are satisfied with the results you can then
2186 run the <filename>update-recipe</filename> to create the
2187 patches and update the recipe in the external layer:
2188 <literallayout class='monospaced'>
2189 $ devtool update-recipe <replaceable>recipe</replaceable>
2190 </literallayout>
2191 <note>
2192 For complete syntax, use the
2193 <filename>devtool update-recipe &dash;&dash;help</filename> command.
2194 </note>
2195 </para>
2196 </section>
2197
2198 <section id='devtool-building-your-software'>
2199 <title>Building Your Software</title>
2200
2201 <para>
2202 Use the <filename>build</filename> command to cause the
2203 OpenEmbedded build system to build your software based
2204 on the recipe file:
2205 <literallayout class='monospaced'>
2206 $ devtool build <replaceable>recipe</replaceable>
2207 </literallayout>
2208 <note>
2209 For complete syntax, use the
2210 <filename>devtool update-recipe &dash;&dash;help</filename> command.
2211 </note>
2212 Building your software using <filename>build</filename> is
2213 identical to using BitBake to build the software.
2214 </para>
2215 </section>
2216
2217 <section id='devtool-deploying-your-software-on-the-target-machine'>
2218 <title>Deploying Your Software on the Target Machine</title>
2219
2220 <para>
2221 Use the <filename>deploy-target</filename> command to deploy
2222 the recipe's build output to the the live target machine:
2223 <literallayout class='monospaced'>
2224 $ devtool deploy-target <replaceable>recipe</replaceable>&nbsp;<replaceable>target</replaceable>
2225 </literallayout>
2226 The <replaceable>target</replaceable> is the actual
2227 target running on an SSH server (i.e.
2228 <filename>user@hostname[:destdir]</filename>.
2229 <note>
2230 For complete syntax, use the
2231 <filename>devtool deploy-target &dash;&dash;help</filename> command.
2232 </note>
2233 </para>
2234 </section>
2235
2236 <section id='devtool-removing-your-software-from-the-target-machine'>
2237 <title>Removing Your Software from the Target Machine</title>
2238
2239 <para>
2240 Use the <filename>undeploy-target</filename> command to remove
2241 deployed build output from the target machine.
2242 For <filename>undeploy-target</filename> command to work,
2243 you must have previously used the
2244 <link linkend='devtool-deploying-your-software-on-the-target-machine'><filename>deploy-target</filename></link>
2245 command.
2246 <literallayout class='monospaced'>
2247 $ devtool undeploy-target <replaceable>recipe</replaceable>&nbsp;<replaceable>target</replaceable>
2248 </literallayout>
2249 The <replaceable>target</replaceable> is the actual
2250 target running on an SSH server (i.e.
2251 <filename>user@hostname</filename>.
2252 <note>
2253 For complete syntax, use the
2254 <filename>devtool undeploy-target &dash;&dash;help</filename> command.
2255 </note>
2256 </para>
2257 </section>
1765 </section> 2258 </section>
1766 2259
1767 <section id="using-a-quilt-workflow"> 2260 <section id="using-a-quilt-workflow">
1768 <title>Using a Quilt Workflow</title> 2261 <title>Using Quilt in Your Workflow</title>
1769 2262
1770 <para> 2263 <para>
1771 <ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink> 2264 <ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink>
@@ -1782,7 +2275,7 @@
1782 The temporary source code used by the OpenEmbedded build system is kept in the 2275 The temporary source code used by the OpenEmbedded build system is kept in the
1783 Build Directory. 2276 Build Directory.
1784 See the 2277 See the
1785 "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>" 2278 "<link linkend='finding-the-temporary-source-code'>Finding Temporary Source Code</link>"
1786 section to learn how to locate the directory that has the temporary source code for a 2279 section to learn how to locate the directory that has the temporary source code for a
1787 particular package.</para></listitem> 2280 particular package.</para></listitem>
1788 <listitem><para><emphasis>Change Your Working Directory:</emphasis> 2281 <listitem><para><emphasis>Change Your Working Directory:</emphasis>
@@ -1815,7 +2308,7 @@
1815 <literallayout class='monospaced'> 2308 <literallayout class='monospaced'>
1816 $ bitbake -c compile -f <replaceable>name_of_package</replaceable> 2309 $ bitbake -c compile -f <replaceable>name_of_package</replaceable>
1817 </literallayout> 2310 </literallayout>
1818 The <filename>-f</filename> or <filename>--force</filename> 2311 The <filename>-f</filename> or <filename>&dash;&dash;force</filename>
1819 option forces the specified task to execute. 2312 option forces the specified task to execute.
1820 If you find problems with your code, you can just keep editing and 2313 If you find problems with your code, you can just keep editing and
1821 re-testing iteratively until things work as expected. 2314 re-testing iteratively until things work as expected.
@@ -1863,133 +2356,99 @@
1863 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink></filename> 2356 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink></filename>
1864 value in the recipe since the resulting packages have changed.</para></listitem> 2357 value in the recipe since the resulting packages have changed.</para></listitem>
1865 </orderedlist> 2358 </orderedlist>
1866 </para> </section> 2359 </para>
2360 </section>
2361
2362 <section id='finding-the-temporary-source-code'>
2363 <title>Finding Temporary Source Code</title>
1867 2364
1868 <section id='using-a-git-workflow'>
1869 <title>Using a Git Workflow</title>
1870 <para> 2365 <para>
1871 Git is an even more powerful tool that allows you to capture source code changes without having 2366 You might
1872 a clean source tree. 2367 find it helpful during development to modify the temporary source code used by recipes
1873 This section outlines the typical workflow you can use to modify temporary source code, 2368 to build packages.
1874 test changes, and then preserve the changes in the form of a patch all using Git. 2369 For example, suppose you are developing a patch and you need to experiment a bit
1875 For general information on Git as it is used in the Yocto Project, see the 2370 to figure out your solution.
1876 "<link linkend='git'>Git</link>" section. 2371 After you have initially built the package, you can iteratively tweak the
2372 source code, which is located in the
2373 <link linkend='build-directory'>Build Directory</link>, and then
2374 you can force a re-compile and quickly test your altered code.
2375 Once you settle on a solution, you can then preserve your changes in the form of
2376 patches.
2377 You can accomplish these steps all within either a
2378 <ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink> or
2379 <link linkend='git'>Git</link> workflow.
1877 </para> 2380 </para>
1878 2381
1879 <note> 2382 <para>
1880 This workflow uses Git only for its ability to manage local changes to the source code 2383 During a build, the unpacked temporary source code used by recipes
1881 and produce patches independent of any version control system used with the Yocto Project. 2384 to build packages is available in the Build Directory as
1882 </note> 2385 defined by the
2386 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename> variable.
2387 Below is the default value for the <filename>S</filename> variable as defined in the
2388 <filename>meta/conf/bitbake.conf</filename> configuration file in the
2389 <link linkend='source-directory'>Source Directory</link>:
2390 <literallayout class='monospaced'>
2391 S = "${WORKDIR}/${BP}"
2392 </literallayout>
2393 You should be aware that many recipes override the <filename>S</filename> variable.
2394 For example, recipes that fetch their source from Git usually set
2395 <filename>S</filename> to <filename>${WORKDIR}/git</filename>.
2396 <note>
2397 The
2398 <ulink url='&YOCTO_DOCS_REF_URL;#var-BP'><filename>BP</filename></ulink>
2399 represents the base recipe name, which consists of the name and version:
2400 <literallayout class='monospaced'>
2401 BP = "${BPN}-${PV}"
2402 </literallayout>
2403 </note>
2404 </para>
1883 2405
1884 <para> 2406 <para>
1885 Follow these general steps: 2407 The path to the work directory for the recipe
1886 <orderedlist> 2408 (<ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>)
1887 <listitem><para><emphasis>Find the Source Code:</emphasis> 2409 is defined as follows:
1888 The temporary source code used by the OpenEmbedded build system is kept in the 2410 <literallayout class='monospaced'>
1889 Build Directory. 2411 ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}
1890 See the 2412 </literallayout>
1891 "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>" 2413 The actual directory depends on several things:
1892 section to learn how to locate the directory that has the temporary source code for a 2414 <itemizedlist>
1893 particular package.</para></listitem> 2415 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>:
1894 <listitem><para><emphasis>Change Your Working Directory:</emphasis> 2416 The top-level build output directory</listitem>
1895 You need to be in the directory that has the temporary source code. 2417 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></ulink>:
1896 That directory is defined by the 2418 The target system identifier</listitem>
1897 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink> 2419 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>:
1898 variable.</para></listitem> 2420 The recipe name</listitem>
1899 <listitem><para><emphasis>If needed, initialize a Git Repository:</emphasis> 2421 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTENDPE'><filename>EXTENDPE</filename></ulink>:
1900 If the recipe you are working with does not use a Git fetcher, 2422 The epoch - (if
1901 you need to set up a Git repository as follows: 2423 <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>
1902 <literallayout class='monospaced'> 2424 is not specified, which is usually the case for most
1903 $ git init 2425 recipes, then <filename>EXTENDPE</filename> is blank)</listitem>
1904 $ git add * 2426 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>:
1905 $ git commit -m "initial revision" 2427 The recipe version</listitem>
1906 </literallayout> 2428 <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>:
1907 The above Git commands initialize a Git repository that is based on the 2429 The recipe revision</listitem>
1908 files in your current working directory, stage all the files, and commit 2430 </itemizedlist>
1909 the files. 2431 </para>
1910 At this point, your Git repository is aware of all the source code files. 2432
1911 Any edits you now make to files can be committed later and will be tracked by 2433 <para>
1912 Git.</para></listitem> 2434 As an example, assume a Source Directory top-level folder
1913 <listitem><para><emphasis>Edit the Files:</emphasis> 2435 name <filename>poky</filename>, a default Build Directory at
1914 Make your changes to the temporary source code.</para></listitem> 2436 <filename>poky/build</filename>, and a
1915 <listitem><para><emphasis>Test Your Changes:</emphasis> 2437 <filename>qemux86-poky-linux</filename> machine target
1916 Once you have modified the source code, the easiest way 2438 system.
1917 to test your changes is by calling the 2439 Furthermore, suppose your recipe is named
1918 <filename>do_compile</filename> task as shown in the 2440 <filename>foo_1.3.0.bb</filename>.
1919 following example: 2441 In this case, the work directory the build system uses to
1920 <literallayout class='monospaced'> 2442 build the package would be as follows:
1921 $ bitbake -c compile -f <replaceable>name_of_package</replaceable> 2443 <literallayout class='monospaced'>
1922 </literallayout> 2444 poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0
1923 The <filename>-f</filename> or <filename>--force</filename> 2445 </literallayout>
1924 option forces the specified task to execute. 2446 </para>
1925 If you find problems with your code, you can just keep editing and 2447
1926 re-testing iteratively until things work as expected. 2448 <para>
1927 <note>All the modifications you make to the temporary source code 2449 Now that you know where to locate the directory that has the temporary source code,
1928 disappear once you <filename>-c clean</filename>, <filename>-c cleansstate</filename>, 2450 you can use a Quilt or Git workflow to make your edits, test the changes,
1929 or <filename>-c cleanall</filename> with BitBake for the package. 2451 and preserve the changes in the form of patches.
1930 Modifications will also disappear if you use the <filename>rm_work</filename>
1931 feature as described in the
1932 "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
1933 section of the Yocto Project Quick Start.
1934 </note></para></listitem>
1935 <listitem><para><emphasis>See the List of Files You Changed:</emphasis>
1936 Use the <filename>git status</filename> command to see what files you have actually edited.
1937 The ability to have Git track the files you have changed is an advantage that this
1938 workflow has over the Quilt workflow.
1939 Here is the Git command to list your changed files:
1940 <literallayout class='monospaced'>
1941 $ git status
1942 </literallayout></para></listitem>
1943 <listitem><para><emphasis>Stage the Modified Files:</emphasis>
1944 Use the <filename>git add</filename> command to stage the changed files so they
1945 can be committed as follows:
1946 <literallayout class='monospaced'>
1947 $ git add file1.c file2.c file3.c
1948 </literallayout></para></listitem>
1949 <listitem><para><emphasis>Commit the Staged Files and View Your Changes:</emphasis>
1950 Use the <filename>git commit</filename> command to commit the changes to the
1951 local repository.
1952 Once you have committed the files, you can use the <filename>git log</filename>
1953 command to see your changes:
1954 <literallayout class='monospaced'>
1955 $ git commit -m "<replaceable>commit-summary-message</replaceable>"
1956 $ git log
1957 </literallayout>
1958 <note>The name of the patch file created in the next step is based on your
1959 <replaceable>commit-summary-message</replaceable>.</note></para></listitem>
1960 <listitem><para><emphasis>Generate the Patch:</emphasis>
1961 Once the changes are committed, use the <filename>git format-patch</filename>
1962 command to generate a patch file:
1963 <literallayout class='monospaced'>
1964 $ git format-patch -1
1965 </literallayout>
1966 Specifying "-1" causes Git to generate the
1967 patch file for the most recent commit.</para>
1968 <para>At this point, the patch file has all your edits made
1969 to the <filename>file1.c</filename>, <filename>file2.c</filename>, and
1970 <filename>file3.c</filename> files.
1971 You can find the resulting patch file in the current directory and it
1972 is named according to the <filename>git commit</filename> summary line.
1973 The patch file ends with <filename>.patch</filename>.</para></listitem>
1974 <listitem><para><emphasis>Copy the Patch File:</emphasis>
1975 For simplicity, copy the patch file into a directory named <filename>files</filename>,
1976 which you can create in the same directory that holds the recipe
1977 (<filename>.bb</filename>) file or the
1978 append (<filename>.bbappend</filename>) file.
1979 Placing the patch here guarantees that the OpenEmbedded build system will find
1980 the patch.
1981 Next, add the patch into the
1982 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>
1983 of the recipe.
1984 Here is an example:
1985 <literallayout class='monospaced'>
1986 SRC_URI += "file://0001-<replaceable>commit-summary-message</replaceable>.patch"
1987 </literallayout></para></listitem>
1988 <listitem><para><emphasis>Increment the Recipe Revision Number:</emphasis>
1989 Finally, don't forget to 'bump' the
1990 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink></filename>
1991 value in the recipe since the resulting packages have changed.</para></listitem>
1992 </orderedlist>
1993 </para> 2452 </para>
1994 </section> 2453 </section>
1995</section> 2454</section>
@@ -2109,6 +2568,3 @@
2109</section> 2568</section>
2110 2569
2111</chapter> 2570</chapter>
2112<!--
2113vim: expandtab tw=80 ts=4
2114-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-17 18:27:10 +0000