summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2015-06-29 10:18:09 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2015-07-28 18:02:32 +0100
commit49bcb74203195b5a67e8cb7c5aa26fa29fe3f537 (patch)
tree3a61eedf6c805a0ac69414eb7329b7c200267fb6 /documentation/dev-manual
parentce97654d8242afc192203cbd71dcd92dae10beab (diff)
downloadpoky-49bcb74203195b5a67e8cb7c5aa26fa29fe3f537.tar.gz
dev-manual: Applied review edits to devtool section.
(From yocto-docs rev: 2b04710ccb1c63c4dafc2abbb79f5a7feddf43e9) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r--documentation/dev-manual/dev-manual-model.xml225
1 files changed, 108 insertions, 117 deletions
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
index 9c549d7464..6e0ded2f17 100644
--- a/documentation/dev-manual/dev-manual-model.xml
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -1721,44 +1721,17 @@
1721 section. 1721 section.
1722 </para> 1722 </para>
1723 </footnote> 1723 </footnote>
1724 <note>
1725 The workflow considers the entire build process for the
1726 image and not just modification of the external source
1727 code.
1728 </note>
1729 </para> 1724 </para>
1730 1725
1731 <section id='establish-the-reference-image'> 1726 <para>
1732 <title>Establish the Reference Image</title> 1727 The steps in this section assume you have a previously built
1733 1728 image that is already either running in QEMU or running on actual
1734 <para> 1729 hardware.
1735 The steps to clone the <filename>poky</filename> Git 1730 Also, it is assumed that for deployment of the image to the
1736 repository, build out an image, and test it using QEMU 1731 target, SSH is installed in the image and if the image is running
1737 are well documented as follows: 1732 on real hardware that you have network access to and from your
1738 <itemizedlist> 1733 development machine.
1739 <listitem><para> 1734 </para>
1740 For information on how to set up a local copy of the
1741 <filename>poky</filename> repository and on how to
1742 build a Yocto Project image, see the
1743 "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
1744 section in the Yocto Project Quick Start.
1745 </para></listitem>
1746 <listitem><para>
1747 For information on how to test an image using QEMU, see
1748 the
1749 "<link linkend='dev-manual-qemu'>Using the Quick EMUlator (QEMU)</link>"
1750 section.
1751 </para></listitem>
1752 </itemizedlist>
1753 </para>
1754
1755 <para>
1756 Before you start making modifications to your project's
1757 source code, you should be sure you have the appropriate
1758 local repositories and have a base image built using
1759 BitBake that you can run on QEMU.
1760 </para>
1761 </section>
1762 1735
1763 <section id='update-your-external-source'> 1736 <section id='update-your-external-source'>
1764 <title>Update Your External Source</title> 1737 <title>Update Your External Source</title>
@@ -1806,18 +1779,12 @@
1806 <literallayout class='monospaced'> 1779 <literallayout class='monospaced'>
1807 $ devtool add <replaceable>your-project-name</replaceable>&nbsp;<replaceable>path-to-source</replaceable> 1780 $ devtool add <replaceable>your-project-name</replaceable>&nbsp;<replaceable>path-to-source</replaceable>
1808 </literallayout> 1781 </literallayout>
1809 Running <filename>devtool add</filename> modifies the
1810 <filename>bblayers.conf</filename> that the
1811 OpenEmbedded build system uses to build an image.
1812 For more information on the <filename>bblayers.conf</filename>,
1813 see the
1814 "<ulink url='&YOCTO_DOCS_REF_URL;#structure-build-conf-bblayers.conf'><filename>build/conf/bblayers.conf</filename></ulink>"
1815 section in the Yocto Project Reference Manual.
1816 </para> 1782 </para>
1817 1783
1818 <para> 1784 <para>
1819 Running <filename>devtool add</filename> adds a new workspace 1785 Running <filename>devtool</filename> for the first time
1820 layer to the <filename>bblayers.conf</filename> file that 1786 creates a workspace layer through the
1787 <filename>bblayers.conf</filename> file that
1821 is based on your project's location: 1788 is based on your project's location:
1822 <literallayout class='monospaced'> 1789 <literallayout class='monospaced'>
1823 <replaceable>path-to-source</replaceable>/<replaceable>build-directory</replaceable>/<replaceable>workspace-layer</replaceable> 1790 <replaceable>path-to-source</replaceable>/<replaceable>build-directory</replaceable>/<replaceable>workspace-layer</replaceable>
@@ -1918,6 +1885,7 @@
1918 </para> 1885 </para>
1919 </section> 1886 </section>
1920 1887
1888<!--
1921 <section id='dev-build-the-image'> 1889 <section id='dev-build-the-image'>
1922 <title>Build the Image</title> 1890 <title>Build the Image</title>
1923 1891
@@ -1946,6 +1914,7 @@
1946 section. 1914 section.
1947 </para> 1915 </para>
1948 </section> 1916 </section>
1917-->
1949 </section> 1918 </section>
1950 1919
1951 <section id='devtool-quick-reference'> 1920 <section id='devtool-quick-reference'>
@@ -2003,7 +1972,8 @@
2003 name and using <filename>--help</filename>: 1972 name and using <filename>--help</filename>:
2004 <literallayout class='monospaced'> 1973 <literallayout class='monospaced'>
2005 $ devtool add --help 1974 $ devtool add --help
2006 usage: devtool add [-h] [--same-dir] [--version VERSION] recipename srctree 1975 usage: devtool add [-h] [--same-dir] [--fetch URI] [--version VERSION]
1976 recipename srctree
2007 1977
2008 Adds a new recipe 1978 Adds a new recipe
2009 1979
@@ -2013,9 +1983,11 @@
2013 1983
2014 optional arguments: 1984 optional arguments:
2015 -h, --help show this help message and exit 1985 -h, --help show this help message and exit
2016 --same-dir, -s Build in same directory as source (default: False) 1986 --same-dir, -s Build in same directory as source
1987 --fetch URI, -f URI Fetch the specified URI and extract it to create the
1988 source tree
2017 --version VERSION, -V VERSION 1989 --version VERSION, -V VERSION
2018 Version to use within recipe (PV) (default: None) 1990 Version to use within recipe (PV)
2019 </literallayout> 1991 </literallayout>
2020 </para> 1992 </para>
2021 </section> 1993 </section>
@@ -2034,11 +2006,11 @@
2034 2006
2035 <para> 2007 <para>
2036 The following example creates and adds a new recipe named 2008 The following example creates and adds a new recipe named
2037 <filename>jackson-2.0</filename> to the workspace layer. 2009 <filename>jackson</filename> to the workspace layer.
2038 The source code built by the recipes resides in 2010 The source code built by the recipes resides in
2039 <filename>/home/scottrif/sources/jackson</filename>: 2011 <filename>/home/scottrif/sources/jackson</filename>:
2040 <literallayout class='monospaced'> 2012 <literallayout class='monospaced'>
2041 $ devtool add jackson-2.0 /home/scottrif/sources/jackson 2013 $ devtool add jackson /home/scottrif/sources/jackson
2042 </literallayout> 2014 </literallayout>
2043 <note> 2015 <note>
2044 For complete syntax, use the 2016 For complete syntax, use the
@@ -2082,44 +2054,8 @@
2082 </para> 2054 </para>
2083 </section> 2055 </section>
2084 2056
2085 <section id='devtool-creating-the-workspace'>
2086 <title>Creating the Workspace Layer</title>
2087
2088 <para>
2089 Use the <filename>devtool create-workspace</filename> command to
2090 create a new workspace layer in your
2091 <link linkend='build-directory'>Build Directory</link>.
2092 When you create a new workspace layer, it is populated with the
2093 <filename>README</filename> file and the
2094 <filename>conf</filename> directory only.
2095 </para>
2096
2097 <para>
2098 The following example creates a new workspace layer in your
2099 current working and by default names the workspace layer
2100 "workspace":
2101 <literallayout class='monospaced'>
2102 $ devtool create-workspace
2103 </literallayout>
2104 <note>
2105 For complete syntax, use the
2106 <filename>devtool create-workspace --help</filename> command.
2107 </note>
2108 </para>
2109
2110 <para>
2111 You can create a workspace layer anywhere by supplying
2112 a pathname with the command.
2113 The following command creates a new workspace layer named
2114 "new-workspace":
2115 <literallayout class='monospaced'>
2116 $ devtool create-workspace /home/scottrif/new-workspace
2117 </literallayout>
2118 </para>
2119 </section>
2120
2121 <section id='devtool-modifying-a-recipe'> 2057 <section id='devtool-modifying-a-recipe'>
2122 <title>Modifying a Recipe</title> 2058 <title>Modifying an Existing Recipe</title>
2123 2059
2124 <para> 2060 <para>
2125 Use the <filename>devtool modify</filename> command to begin 2061 Use the <filename>devtool modify</filename> command to begin
@@ -2144,18 +2080,62 @@
2144 </literallayout> 2080 </literallayout>
2145 Using the above command form, the default development branch 2081 Using the above command form, the default development branch
2146 would be "devtool". 2082 would be "devtool".
2083 <note>
2084 For complete syntax, use the
2085 <filename>devtool modify --help</filename> command.
2086 </note>
2147 </para> 2087 </para>
2088 </section>
2089
2090 <section id='devtool-updating-a-recipe'>
2091 <title>Updating a Recipe</title>
2148 2092
2149 <para> 2093 <para>
2150 If you want to name a development branch, use the 2094 Use the <filename>devtool update-recipe</filename> command to
2151 <filename>-b</filename> option with the 2095 update your recipe with patches that reflect changes you make
2152 <filename>-x</filename> option: 2096 to the source files.
2097 For example, if you know you are going to work on some
2098 code, you could first use the
2099 <link linkend='devtool-modifying-a-recipe'><filename>devtool modify</filename></link>
2100 command to extract the code and set up the workspace.
2101 After which, you could modify, compile, and test the code.
2102 </para>
2103
2104 <para>
2105 When you are satisfied with the results and you have committed
2106 your changes to the Git repository, you can then
2107 run the <filename>devtool update-recipe</filename> to create the
2108 patches and update the recipe:
2153 <literallayout class='monospaced'> 2109 <literallayout class='monospaced'>
2154 $ devtool modify -x -b <replaceable>branch</replaceable>&nbsp;<replaceable>recipe</replaceable>&nbsp;<replaceable>path-to-source</replaceable> 2110 $ devtool update-recipe <replaceable>recipe</replaceable>
2155 </literallayout> 2111 </literallayout>
2112 If you run the <filename>devtool update-recipe</filename>
2113 without committing your changes, the command ignores the
2114 changes.
2115 </para>
2116
2117 <para>
2118 Often, you might want to apply customizations made to your
2119 software in your own layer rather than apply them to the
2120 original recipe.
2121 If so, you can use the
2122 <filename>-a</filename> or <filename>--append</filename>
2123 option with the <filename>devtool update-recipe</filename>
2124 command.
2125 These options allow you to specify the layer into which to
2126 write an append file:
2127 <literallayout class='monospaced'>
2128 $ devtool update-recipe <replaceable>recipe</replaceable> -a <replaceable>base-layer-directory</replaceable>
2129 </literallayout>
2130 The <filename>*.bbappend</filename> file is created at the
2131 appropriate path within the specified layer directory, which
2132 may or may not be in your <filename>bblayers.conf</filename>
2133 file.
2134 If an append file already exists, the command updates it
2135 appropriately.
2156 <note> 2136 <note>
2157 For complete syntax, use the 2137 For complete syntax, use the
2158 <filename>devtool modify --help</filename> command. 2138 <filename>devtool update-recipe --help</filename> command.
2159 </note> 2139 </note>
2160 </para> 2140 </para>
2161 </section> 2141 </section>
@@ -2188,31 +2168,6 @@
2188 </para> 2168 </para>
2189 </section> 2169 </section>
2190 2170
2191 <section id='devtool-updating-a-recipe'>
2192 <title>Updating a Recipe</title>
2193
2194 <para>
2195 Use the <filename>devtool update-recipe</filename> command to
2196 update your recipe with patches that reflect changes you make
2197 to the source files.
2198 For example, if you know you are going to work on some
2199 code, you could first use the
2200 <link linkend='devtool-modifying-a-recipe'><filename>devtool modify</filename></link>
2201 command to extract the code and set up the workspace.
2202 After which, you could modify, compile, and test the code.
2203 When you are satisfied with the results you can then
2204 run the <filename>devtool update-recipe</filename> to create the
2205 patches and update the recipe:
2206 <literallayout class='monospaced'>
2207 $ devtool update-recipe <replaceable>recipe</replaceable>
2208 </literallayout>
2209 <note>
2210 For complete syntax, use the
2211 <filename>devtool update-recipe --help</filename> command.
2212 </note>
2213 </para>
2214 </section>
2215
2216 <section id='devtool-building-your-software'> 2171 <section id='devtool-building-your-software'>
2217 <title>Building Your Software</title> 2172 <title>Building Your Software</title>
2218 2173
@@ -2295,6 +2250,42 @@
2295 </note> 2250 </note>
2296 </para> 2251 </para>
2297 </section> 2252 </section>
2253
2254 <section id='devtool-creating-the-workspace'>
2255 <title>Creating the Workspace Layer in an Alternative Location</title>
2256
2257 <para>
2258 Use the <filename>devtool create-workspace</filename> command to
2259 create a new workspace layer in your
2260 <link linkend='build-directory'>Build Directory</link>.
2261 When you create a new workspace layer, it is populated with the
2262 <filename>README</filename> file and the
2263 <filename>conf</filename> directory only.
2264 </para>
2265
2266 <para>
2267 The following example creates a new workspace layer in your
2268 current working and by default names the workspace layer
2269 "workspace":
2270 <literallayout class='monospaced'>
2271 $ devtool create-workspace
2272 </literallayout>
2273 <note>
2274 For complete syntax, use the
2275 <filename>devtool create-workspace --help</filename> command.
2276 </note>
2277 </para>
2278
2279 <para>
2280 You can create a workspace layer anywhere by supplying
2281 a pathname with the command.
2282 The following command creates a new workspace layer named
2283 "new-workspace":
2284 <literallayout class='monospaced'>
2285 $ devtool create-workspace /home/scottrif/new-workspace
2286 </literallayout>
2287 </para>
2288 </section>
2298 </section> 2289 </section>
2299 2290
2300 <section id="using-a-quilt-workflow"> 2291 <section id="using-a-quilt-workflow">