summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r--documentation/dev-manual/dev-manual-model.xml455
1 files changed, 168 insertions, 287 deletions
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
index 843b1b788d..cef668408a 100644
--- a/documentation/dev-manual/dev-manual-model.xml
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -1764,15 +1764,6 @@
1764 1764
1765 <para> 1765 <para>
1766 The remainder of this section presents these workflows. 1766 The remainder of this section presents these workflows.
1767 <note>
1768 The steps in this section assume you have a previously built
1769 image that is already either running in QEMU or running on actual
1770 hardware.
1771 Also, it is assumed that for deployment of the image to the
1772 target, SSH is installed in the image and if the image is running
1773 on real hardware that you have network access to and from your
1774 development machine.
1775 </note>
1776 </para> 1767 </para>
1777 1768
1778 <section id='use-devtool-to-integrate-new-code'> 1769 <section id='use-devtool-to-integrate-new-code'>
@@ -1823,49 +1814,33 @@
1823 feed into the <filename>devtool add</filename> workflow: 1814 feed into the <filename>devtool add</filename> workflow:
1824 <itemizedlist> 1815 <itemizedlist>
1825 <listitem><para><emphasis>Left</emphasis>: 1816 <listitem><para><emphasis>Left</emphasis>:
1826 The left scenario represents a situation 1817 The left scenario represents a common situation
1827 where the source tree (srctree) exists as a 1818 where the source code does not exist locally
1828 previously extracted Git structure outside of 1819 and needs to be extracted.
1829 the <filename>devtool</filename> workspace. 1820 In this situation, you just let it get
1830 </para> 1821 extracted to the default workspace - you do not
1831 1822 want it in some specific location outside of the
1832 <para>The following command names the recipe 1823 workspace.
1833 and identifies where the existing source tree 1824 Thus, everything you need will be located in the
1834 is located: 1825 workspace:
1835 <literallayout class='monospaced'> 1826 <literallayout class='monospaced'>
1836 $ devtool add <replaceable>recipe srctree</replaceable> 1827 $ devtool add <replaceable>recipe fetchuri</replaceable>
1837 </literallayout> 1828 </literallayout>
1838 <note> 1829 With this command, <filename>devtool</filename>
1839 If a recipe exists that is associated with 1830 creates a recipe and an append file in the
1840 source code, <filename>devtool</filename> 1831 workspace as well as extracts the upstream
1841 can leverage off that if it knows about the 1832 source files into a local Git repository also
1842 layer in which the recipe resides. 1833 within the <filename>sources</filename> folder.
1843 Be sure to update your
1844 <filename>conf/bblayers.conf</filename> file
1845 to include the layers you want
1846 <filename>devtool</filename> to know about
1847 when looking for an existing recipe.
1848 </note>
1849 The command examines the source code and creates
1850 a recipe for it placing the recipe into the
1851 workspace.</para>
1852
1853 <para>Because the extracted source code already exists,
1854 <filename>devtool</filename> does not try to
1855 relocate it into the workspace - just the new
1856 (or a modified copy of) the recipe is placed in
1857 the workspace.</para>
1858
1859 <para>Aside from a recipe folder, the command
1860 also creates an append folder and places an initial
1861 <filename>*.bbappend</filename> within.
1862 </para></listitem> 1834 </para></listitem>
1863 <listitem><para><emphasis>Middle</emphasis>: 1835 <listitem><para><emphasis>Middle</emphasis>:
1864 The middle scenario represents a situation where 1836 The middle scenario also represents a situation where
1865 the source code does not exist locally. 1837 the source code does not exist locally.
1866 In this case, the code is in an upstream Git 1838 In this case, the code is again upstream
1867 repository and needs to be extracted to some 1839 and needs to be extracted to some
1868 local area. 1840 local area - this time outside of the default
1841 workspace.
1842 As always, if required <filename>devtool</filename> creates
1843 a Git repository locally during the extraction.
1869 Furthermore, the first positional argument 1844 Furthermore, the first positional argument
1870 <replaceable>srctree</replaceable> in this case 1845 <replaceable>srctree</replaceable> in this case
1871 identifies where the 1846 identifies where the
@@ -1886,101 +1861,33 @@
1886 for the recipe. 1861 for the recipe.
1887 </para></listitem> 1862 </para></listitem>
1888 <listitem><para><emphasis>Right</emphasis>: 1863 <listitem><para><emphasis>Right</emphasis>:
1889 The right scenario represents another situation 1864 The right scenario represents a situation
1890 where the source code does not exist locally 1865 where the source tree (srctree) has been
1891 and again needs to be extracted. 1866 previously prepared outside of the
1892 However, in this situation, you want to extract the 1867 <filename>devtool</filename> workspace.
1893 source into the workspace. 1868 </para>
1894 Thus, everything you need will be located in the 1869
1895 workspace: 1870 <para>The following command names the recipe
1871 and identifies where the existing source tree
1872 is located:
1896 <literallayout class='monospaced'> 1873 <literallayout class='monospaced'>
1897 $ devtool add <replaceable>recipe fetchuri</replaceable> 1874 $ devtool add <replaceable>recipe srctree</replaceable>
1898 </literallayout> 1875 </literallayout>
1899 With this command, <filename>devtool</filename> 1876 The command examines the source code and creates
1900 creates a recipe and an append file in the 1877 a recipe for it placing the recipe into the
1901 workspace as well as extracts the upstream 1878 workspace.</para>
1902 source files into a local Git repository also 1879
1903 within the <filename>sources</filename> folder. 1880 <para>Because the extracted source code already exists,
1881 <filename>devtool</filename> does not try to
1882 relocate it into the workspace - just the new
1883 the recipe is placed in the workspace.</para>
1884
1885 <para>Aside from a recipe folder, the command
1886 also creates an append folder and places an initial
1887 <filename>*.bbappend</filename> within.
1904 </para></listitem> 1888 </para></listitem>
1905 </itemizedlist> 1889 </itemizedlist>
1906 </para></listitem> 1890 </para></listitem>
1907<!--
1908 <listitem><para><emphasis>Add a New Recipe</emphasis>:
1909 The <filename>devtool add</filename> command automatically
1910 generates the needed Metadata that allows the OpenEmbedded
1911 build system to build your code.
1912 Following are some forms you can use to enter the command:
1913 <literallayout class='monospaced'>
1914 $ devtool add [<replaceable>recipe_name</replaceable>]&nbsp;<replaceable>source_path</replaceable>
1915 $ devtool add [<replaceable>recipe_name</replaceable>]&nbsp;<replaceable>source_path remote_URL</replaceable>
1916 $ devtool add [<replaceable>recipe_name</replaceable>]&nbsp;<replaceable>remote_URL</replaceable>
1917 </literallayout>
1918 The <filename>devtool</filename> command automatically detects the
1919 <replaceable>recipe_name</replaceable> and, in many cases, the
1920 version if you do not supply a name or version with the command.</para>
1921 <para>Running <filename>devtool</filename> for the first time
1922 creates a workspace layer, which by default is named
1923 "workspace", and adds it to your
1924 <filename>conf/bblayers.conf</filename> file:
1925 <literallayout class='monospaced'>
1926 <replaceable>source_path</replaceable>/<replaceable>build_directory</replaceable>/<replaceable>workspace_layer</replaceable>
1927 </literallayout>
1928 For details on the workspace layer created in the
1929 <replaceable>build-directory</replaceable>,
1930 see the
1931 "<link linkend='devtool-the-workspace-layer-structure'>The Workspace Layer Structure</link>"
1932 section.</para>
1933 <para>You can also specify a <replaceable>remote_URL</replaceable>
1934 from which to download source instead of (or in addition
1935 to) specifying a <replaceable>source_path</replaceable>.
1936 If you specify a URL but not a <replaceable>source_path</replaceable>,
1937 <filename>devtool</filename> uses a subdirectory called "sources"
1938 within <filename>workspace</filename> to house the source files.</para>
1939 <para>Here is an example command that provides the
1940 <replaceable>remote_URL</replaceable> only:
1941 <literallayout class='monospaced'>
1942 $ devtool add ftp://ftp.bitwizard.nl/mtr/mtr-0.86.tar.gz
1943 NOTE: Creating workspace layer in /home/scottrif/poky/build/workspace
1944 NOTE: Enabling workspace layer in bblayers.conf
1945 NOTE: Using default source tree path /home/scottrif/poky/build/workspace/sources/mtr
1946 NOTE: Recipe /home/scottrif/poky/build/workspace/recipes/mtr/mtr_0.86.bb
1947 has been automatically created; further editing may be required to
1948 make it fully functional
1949 $
1950 </literallayout>
1951 In this example, <filename>devtool</filename> detected both
1952 a recipe name and version from the software for use when
1953 creating the <filename>mtr_0.86.bb</filename> recipe file.
1954 Because no <filename>source_path</filename> was provided, the
1955 tool also created the default directory
1956 <filename>sources/mtr/</filename> in the created
1957 <filename>workspace</filename> directory.</para>
1958 <para>If you are using <filename>devtool add</filename>
1959 to fetch source from a remote URL, the command turns
1960 the source directory into a Git repository if one does
1961 not already exist.
1962 You can disable this behavior by using the "&dash;&dash;no-git"
1963 option.
1964 The <filename>devtool add</filename> command does this in
1965 order to support using
1966 <filename>devtool update-recipe</filename>, shown as step
1967 5 in the flow diagram, to later create patches.
1968 <tip>
1969 In case you ever need to locate the directory in which
1970 <filename>devtool</filename> creates the recipe or, you
1971 need to locate the source, you can use <filename>devtool</filename>
1972 to check status:
1973 <literallayout class='monospaced'>
1974 $ devtool status
1975 mtr: /home/scottrif/poky/build/workspace/sources/mtr (/home/scottrif/poky/build/workspace/recipes/mtr/mtr_0.86.bb)
1976 $
1977 </literallayout>
1978 Continuing with the example, the tool returns the location
1979 for the source followed by the location and name of the
1980 recipe.
1981 </tip>
1982 </para></listitem>
1983-->
1984 <listitem><para><emphasis>Edit the Recipe</emphasis>: 1891 <listitem><para><emphasis>Edit the Recipe</emphasis>:
1985 At this point, you can use <filename>devtool edit-recipe</filename> 1892 At this point, you can use <filename>devtool edit-recipe</filename>
1986 to open up the editor as defined by the 1893 to open up the editor as defined by the
@@ -1999,6 +1906,10 @@
1999 <para>If you need to take the build output and eventually 1906 <para>If you need to take the build output and eventually
2000 move it to the target hardware, you would use 1907 move it to the target hardware, you would use
2001 <filename>devtool build</filename>: 1908 <filename>devtool build</filename>:
1909 <note>
1910 You could use <filename>bitbake</filename> to build
1911 the recipe as well.
1912 </note>
2002 <literallayout class='monospaced'> 1913 <literallayout class='monospaced'>
2003 $ devtool build <replaceable>recipe</replaceable> 1914 $ devtool build <replaceable>recipe</replaceable>
2004 </literallayout></para> 1915 </literallayout></para>
@@ -2015,6 +1926,15 @@
2015 command to build out your recipe, you probably want to 1926 command to build out your recipe, you probably want to
2016 see if the resulting build output works as expected on target 1927 see if the resulting build output works as expected on target
2017 hardware. 1928 hardware.
1929 <note>
1930 This step assumes you have a previously built
1931 image that is already either running in QEMU or
1932 running on actual hardware.
1933 Also, it is assumed that for deployment of the image
1934 to the target, SSH is installed in the image and if
1935 the image is running on real hardware that you have
1936 network access to and from your development machine.
1937 </note>
2018 You can deploy your build output to that target hardware by 1938 You can deploy your build output to that target hardware by
2019 using the <filename>devtool deploy-target</filename> command: 1939 using the <filename>devtool deploy-target</filename> command:
2020 <literallayout class='monospaced'> 1940 <literallayout class='monospaced'>
@@ -2030,8 +1950,10 @@
2030 specific command that allows you to do this. 1950 specific command that allows you to do this.
2031 </para></listitem> 1951 </para></listitem>
2032 <listitem><para><emphasis>Optionally Update the Recipe With Patch Files</emphasis>: 1952 <listitem><para><emphasis>Optionally Update the Recipe With Patch Files</emphasis>:
2033 Once you are satisfied with the recipe you probably want 1953 Once you are satisfied with the recipe, if you have made
2034 to generate patch files that go with the recipe. 1954 any changes to the source tree that you want to have
1955 applied by the recipe, you need to generate patches
1956 from those changes.
2035 You do this before moving the recipe 1957 You do this before moving the recipe
2036 to its final layer and cleaning up the workspace area 1958 to its final layer and cleaning up the workspace area
2037 <filename>devtool</filename> uses. 1959 <filename>devtool</filename> uses.
@@ -2040,11 +1962,11 @@
2040 <para>To convert commits created using Git to patch files, 1962 <para>To convert commits created using Git to patch files,
2041 use the <filename>devtool update-recipe</filename> command. 1963 use the <filename>devtool update-recipe</filename> command.
2042 <note> 1964 <note>
2043 Any patches added, removed, or otherwise must be 1965 Any changes you want to turn into patches must be
2044 previously committed to the upstream Git repository. 1966 committed to the Git repository in the source tree.
2045 </note> 1967 </note>
2046 <literallayout class='monospaced'> 1968 <literallayout class='monospaced'>
2047 $ devtool update-recipe <replaceable>recipe_name</replaceable> 1969 $ devtool update-recipe <replaceable>recipe</replaceable>
2048 </literallayout> 1970 </literallayout>
2049 </para></listitem> 1971 </para></listitem>
2050 <listitem><para><emphasis>Move the Recipe to its Permanent Layer</emphasis>: 1972 <listitem><para><emphasis>Move the Recipe to its Permanent Layer</emphasis>:
@@ -2105,10 +2027,9 @@
2105 <listitem><para>The recipe exists in some layer external 2027 <listitem><para>The recipe exists in some layer external
2106 to the <filename>devtool</filename> workspace. 2028 to the <filename>devtool</filename> workspace.
2107 </para></listitem> 2029 </para></listitem>
2108 <listitem><para>The source files exist in a Git 2030 <listitem><para>The source files exist upstream in an
2109 structure either upstream in an un-extracted 2031 un-extracted state or locally in a previously
2110 state or locally in a previously extracted 2032 extracted state.
2111 state.
2112 </para></listitem> 2033 </para></listitem>
2113 </itemizedlist> 2034 </itemizedlist>
2114 The typical situation is where another developer has 2035 The typical situation is where another developer has
@@ -2118,44 +2039,49 @@
2118 either upstream or locally. 2039 either upstream or locally.
2119 <itemizedlist> 2040 <itemizedlist>
2120 <listitem><para><emphasis>Left</emphasis>: 2041 <listitem><para><emphasis>Left</emphasis>:
2121 The left scenario represents a situation 2042 The left scenario represents a common situation
2122 where the source tree (srctree) exists as a 2043 where the source code does not exist locally
2123 previously extracted Git structure outside of 2044 and needs to be extracted.
2124 the <filename>devtool</filename> workspace. 2045 In this situation, the source is extracted
2125 In this example, the recipe also exists 2046 into the default workspace location.
2126 elsewhere in its own layer 2047 The recipe, in this scenario, is in its own
2127 (i.e. <filename>meta-</filename><replaceable>layername</replaceable>). 2048 layer outside the workspace
2049 (i.e.
2050 <filename>meta-</filename><replaceable>layername</replaceable>).
2128 </para> 2051 </para>
2129 2052
2130 <para>The following command tells 2053 <para>The following command identifies the recipe
2131 <filename>devtool</filename> the recipe 2054 and instructs <filename>devtool</filename> to
2132 with which to work and uses 2055 extract the source files using the "-x" option:
2133 <replaceable>srctree</replaceable> to point to the
2134 previously extracted source files:
2135 <literallayout class='monospaced'> 2056 <literallayout class='monospaced'>
2136 $ devtool modify <replaceable>recipe srctree</replaceable> 2057 $ devtool modify -x <replaceable>recipe</replaceable>
2137 </literallayout> 2058 </literallayout>
2138 Because <filename>devtool</filename> uses the 2059 Once <filename>devtool</filename>locates the recipe,
2139 <filename>conf/bblayers.conf</filename> to 2060 it uses the
2140 identify layers in which to look for recipes, 2061 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
2141 you do not have to provide anything beyond a 2062 variable to locate the source code and
2142 recipe's name with the command. 2063 any local patch files from other developers are
2143 In other words, you do not have to provide a 2064 located.
2144 full recipe pathname or provide any file naming 2065 <note>
2145 extensions for <replaceable>recipe</replaceable>. 2066 You cannot provide an URL for
2146 </para> 2067 <replaceable>srctree</replaceable> when using the
2147 2068 <filename>devtool modify</filename> command.
2148 <para>Once the command finishes, it creates only 2069 </note>
2149 an append file for the recipe in the workspace. 2070 With this scenario, however, since no
2150 The recipe and the source code remain in their 2071 <replaceable>srctree</replaceable> argument exists, the
2151 original locations. 2072 <filename>devtool modify</filename> command extracts the
2073 source files to a Git structure using the default
2074 location within the workspace.
2075 The result is that the command set up both the source
2076 code and an append file within the workspace with the
2077 recipe remaining in its original location.
2152 </para></listitem> 2078 </para></listitem>
2153 <listitem><para><emphasis>Middle</emphasis>: 2079 <listitem><para><emphasis>Middle</emphasis>:
2154 The middle scenario represents a situation where 2080 The middle scenario represents a situation where
2155 the source code does not exist locally. 2081 the source code also does not exist locally.
2156 In this case, the code is in an upstream Git 2082 In this case, the code is again upstream
2157 repository and needs to be extracted to some 2083 and needs to be extracted to some
2158 local area. 2084 local area as a Git repository.
2159 The recipe, in this scenario, is again in its own 2085 The recipe, in this scenario, is again in its own
2160 layer outside the workspace.</para> 2086 layer outside the workspace.</para>
2161 2087
@@ -2167,19 +2093,9 @@
2167 <literallayout class='monospaced'> 2093 <literallayout class='monospaced'>
2168 $ devtool modify -x <replaceable>recipe srctree</replaceable> 2094 $ devtool modify -x <replaceable>recipe srctree</replaceable>
2169 </literallayout> 2095 </literallayout>
2170 With the help of the 2096 As with all extractions, the command uses
2171 <filename>conf/bblayers.conf</filename> file, 2097 the recipe's <filename>SRC_URI</filename> to locate the
2172 <filename>devtool</filename>locates the recipe. 2098 source files.
2173 Inside the recipe, the
2174 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
2175 variable points to where the source code and
2176 any local patch files from other developers are
2177 located.
2178 <note>
2179 You cannot provide an URL for
2180 <replaceable>srctree</replaceable> when using the
2181 <filename>devtool modify</filename> command.
2182 </note>
2183 Once the files are located, the command extracts 2099 Once the files are located, the command extracts
2184 them to the location specified by 2100 them to the location specified by
2185 <replaceable>srctree</replaceable>.</para> 2101 <replaceable>srctree</replaceable>.</para>
@@ -2191,34 +2107,28 @@
2191 provided with <replaceable>srctree</replaceable>. 2107 provided with <replaceable>srctree</replaceable>.
2192 </para></listitem> 2108 </para></listitem>
2193 <listitem><para><emphasis>Right</emphasis>: 2109 <listitem><para><emphasis>Right</emphasis>:
2194 The right scenario represents another situation 2110 The right scenario represents a situation
2195 where the source code does not exist locally 2111 where the source tree (srctree) exists as a
2196 and again needs to be extracted. 2112 previously extracted Git structure outside of
2197 However, in this situation, you want to extract the 2113 the <filename>devtool</filename> workspace.
2198 source into the workspace. 2114 In this example, the recipe also exists
2199 The recipe, in this scenario, is again in its own 2115 elsewhere in its own layer.
2200 layer outside the workspace.</para> 2116 </para>
2201 2117
2202 <para>The following command identifies the recipe 2118 <para>The following command tells
2203 and instructs <filename>devtool</filename> to 2119 <filename>devtool</filename> the recipe
2204 extract the source files using the "-x" option: 2120 with which to work and uses
2121 <replaceable>srctree</replaceable> to point to the
2122 previously extracted source files:
2205 <literallayout class='monospaced'> 2123 <literallayout class='monospaced'>
2206 $ devtool modify -x <replaceable>recipe</replaceable> 2124 $ devtool modify <replaceable>recipe srctree</replaceable>
2207 </literallayout> 2125 </literallayout>
2208 As with the previous example, the 2126 </para>
2209 <filename>conf/bblayers.conf</filename> file 2127
2210 helps locate the recipe. 2128 <para>Once the command finishes, it creates only
2211 And, as with all extractions, the command uses 2129 an append file for the recipe in the workspace.
2212 the recipe's <filename>SRC_URI</filename> to locate the 2130 The recipe and the source code remain in their
2213 source files. 2131 original locations.
2214 With this scenario, however, since no
2215 <replaceable>srctree</replaceable> argument exists, the
2216 <filename>devtool modify</filename> command extracts the
2217 source files to a Git structure using the default
2218 location within the workspace.
2219 The result is that the command set up both the source
2220 code and an append file within the workspace with the
2221 recipe remaining in its original location.
2222 </para></listitem> 2132 </para></listitem>
2223 </itemizedlist> 2133 </itemizedlist>
2224 </para></listitem> 2134 </para></listitem>
@@ -2238,49 +2148,33 @@
2238 in 2148 in
2239 <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>. 2149 <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>.
2240 </para></listitem> 2150 </para></listitem>
2241 <listitem><para><emphasis>Test Your Changes</emphasis>: 2151 <listitem><para><emphasis>Deploy the Build Output</emphasis>:
2242 Once your code is built, you can test it for 2152 When you use the <filename>devtool build</filename>
2243 correct operation. 2153 command or <filename>bitbake</filename> to build out your
2244 If you have actual hardware, you can use the 2154 recipe, you probably want to see if the resulting build
2245 <filename>devtool deploy-target</filename> command 2155 output works as expected on target hardware.
2246 to put the build output on the target. 2156 <note>
2247 If you do not have target hardware, you can deploy 2157 This step assumes you have a previously built
2248 the output to QEMU where it can emulate the hardware: 2158 image that is already either running in QEMU or
2159 running on actual hardware.
2160 Also, it is assumed that for deployment of the image
2161 to the target, SSH is installed in the image and if
2162 the image is running on real hardware that you have
2163 network access to and from your development machine.
2164 </note>
2165 You can deploy your build output to that target hardware by
2166 using the <filename>devtool deploy-target</filename> command:
2249 <literallayout class='monospaced'> 2167 <literallayout class='monospaced'>
2250 $ devtool deploy-target <replaceable>recipe target</replaceable> 2168 $ devtool deploy-target <replaceable>recipe target</replaceable>
2251 </literallayout> 2169 </literallayout>
2252 Regardless of where you are deploying the build 2170 The <replaceable>target</replaceable> is a live target machine
2253 output, the <replaceable>target</replaceable> must 2171 running as an SSH server.</para>
2254 be running an SSH server. 2172
2255 For example, to run the <filename>dropbear</filename> 2173 <para>You can, of course, also deploy the image you build
2256 SSH server in an image you are going to be running on 2174 using the <filename>devtool build-image</filename> command
2257 QEMU, be sure this statement is in your 2175 to actual hardware.
2258 <filename>conf/local.conf</filename> file: 2176 However, <filename>devtool</filename> does not provide a
2259 <literallayout class='monospaced'> 2177 specific command that allows you to do this.
2260 EXTRA_IMAGE_FEATURES += "ssh-server-dropbear"
2261 </literallayout>
2262 Here is a <filename>devtool deploy-target</filename>
2263 command example that uses the
2264 <filename>busybox</filename> recipe and QEMU as
2265 the target:
2266 <literallayout class='monospaced'>
2267 $ devtool deploy-target busybox root@192.168.7.2
2268 </literallayout>
2269 <note>
2270 It is worth mentioning that you can load an image
2271 onto your <replaceable>target</replaceable> and
2272 while it is running, deploy your package build
2273 output to the target as the image is running.
2274 You can also rebuild your image using
2275 <filename>bitbake</filename> and it will pick up
2276 your new package output.
2277 From there, you could re-run the image on QEMU
2278 to see the effects of your
2279 <filename>devtool build</filename> output.
2280 </note>
2281 You can continue to change, build, and test your
2282 changes until you are satisfied with the code's
2283 behavior.
2284 </para></listitem> 2178 </para></listitem>
2285 <listitem><para><emphasis>Optionally Create Patch Files for Your Changes</emphasis>: 2179 <listitem><para><emphasis>Optionally Create Patch Files for Your Changes</emphasis>:
2286 After you have debugged your changes, you can 2180 After you have debugged your changes, you can
@@ -2294,50 +2188,29 @@
2294 <literallayout class='monospaced'> 2188 <literallayout class='monospaced'>
2295 $ devtool update-recipe <replaceable>recipe</replaceable> 2189 $ devtool update-recipe <replaceable>recipe</replaceable>
2296 </literallayout> 2190 </literallayout>
2297 By default, <filename>devtool</filename> updates 2191 By default, the
2298 the recipe's <filename>SRC_URI</filename> statement 2192 <filename>devtool update-recipe</filename> command
2299 to include the location for the patch files it 2193 creates the patch files in a folder named the same
2300 generates. 2194 as the recipe beneath the folder in which the recipe
2195 resides, and updates the recipe's
2196 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
2197 statement to point to the generated patch files.
2301 <note> 2198 <note>
2302 You can use the 2199 You can use the
2303 "--append <replaceable>LAYERDIR</replaceable> 2200 "--append <replaceable>LAYERDIR</replaceable>"
2304 option to cause the command to create append files 2201 option to cause the command to create append files
2305 in a specific layer rather than the default 2202 in a specific layer rather than the default
2306 recipe layer. 2203 recipe layer.
2307 </note> 2204 </note>
2308 The command also creates a <replaceable>recipe</replaceable>
2309 folder beneath the folder in which the recipe resides
2310 that contains the actual <filename>*.patch</filename>
2311 files.
2312 </para></listitem>
2313 <listitem><para><emphasis>Make Sure the Recipe is in the Final Layer</emphasis>:
2314 Strictly speaking, this step is not necessary if
2315 you begin this workflow with the recipe in its own
2316 proper layer outside of the <filename>devtool</filename>
2317 workspace.
2318 However, it is included here so that when you do the
2319 final step following this you do not lose the recipe
2320 should it be in the workspace, which is possible
2321 (e.g. starting with <filename>devtool add</filename> to
2322 create a recipe in the workspace).</para>
2323
2324 <para>You should be sure that the recipe is located
2325 outside of the workspace before using the
2326 <filename>devtool reset</filename> command described in
2327 the next step.
2328 </para></listitem> 2205 </para></listitem>
2329 <listitem><para><emphasis>Restore the Workspace</emphasis>: 2206 <listitem><para><emphasis>Restore the Workspace</emphasis>:
2330 The <filename>devtool reset</filename> restores the 2207 The <filename>devtool reset</filename> restores the
2331 state so that standard layers and upstream sources are 2208 state so that standard layers and upstream sources are
2332 used to build the recipe rather than what is in the 2209 used to build the recipe rather than what is in the
2333 workspace. 2210 workspace.
2334 Restoring the workspace removes all traces of the
2335 <replaceable>recipe</replaceable>.
2336 <literallayout class='monospaced'> 2211 <literallayout class='monospaced'>
2337 $ devtool reset <replaceable>recipe</replaceable> 2212 $ devtool reset <replaceable>recipe</replaceable>
2338 </literallayout> 2213 </literallayout>
2339 Once the workspace is restored, you can use it again for
2340 working on different code.
2341 </para></listitem> 2214 </para></listitem>
2342 </orderedlist> 2215 </orderedlist>
2343 </para> 2216 </para>
@@ -2469,6 +2342,13 @@
2469 2342
2470 <para> 2343 <para>
2471 <literallayout class='monospaced'> 2344 <literallayout class='monospaced'>
2345 attic - A directory created if devtool believes it preserve
2346 anything when you run "devtool reset". For example, if you
2347 run "devtool add", make changes to the recipe, and then
2348 run "devtool reset", devtool takes notice that the file has
2349 been changed and moves it into the attic should you still
2350 want the recipe.
2351
2472 README - Provides information on what is in workspace layer and how to 2352 README - Provides information on what is in workspace layer and how to
2473 manage it. 2353 manage it.
2474 2354
@@ -2485,9 +2365,10 @@
2485 within that sub-directory. 2365 within that sub-directory.
2486 2366
2487 sources - A directory containing a working copy of the source files used 2367 sources - A directory containing a working copy of the source files used
2488 when building the recipe. This directory contains a 2368 when building the recipe. This is the default directory used
2489 folder for each set of source files matched to a corresponding 2369 as the location of the source tree when you do not provide a
2490 recipe. 2370 source tree path. This directory contains a folder for each
2371 set of source files matched to a corresponding recipe.
2491 </literallayout> 2372 </literallayout>
2492 </para> 2373 </para>
2493 </section> 2374 </section>