summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual/dev-manual-model.xml
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2016-02-11 17:14:32 -0800
committerRichard Purdie <richard.purdie@linuxfoundation.org>2016-03-03 17:40:12 +0000
commit7699f0ab60b000c38233ba99245df1ff76c44217 (patch)
treeec68e6cd9d2232509c8f6fa5af8e7d216a101d03 /documentation/dev-manual/dev-manual-model.xml
parent1eecaea70d0c801d08cea17e57c8693f8058cdce (diff)
downloadpoky-7699f0ab60b000c38233ba99245df1ff76c44217.tar.gz
dev-manual: Added section for devtool modify flow
New figure and some writer notes for now (From yocto-docs rev: 0a627626f5f353e514b0225b468b0bd0fa3ceef3) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/dev-manual/dev-manual-model.xml')
-rw-r--r--documentation/dev-manual/dev-manual-model.xml275
1 files changed, 275 insertions, 0 deletions
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
index d3fadbd1f7..b07b6c96c9 100644
--- a/documentation/dev-manual/dev-manual-model.xml
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -1952,6 +1952,281 @@
1952 </orderedlist> 1952 </orderedlist>
1953 </para> 1953 </para>
1954 </section> 1954 </section>
1955
1956 <section id='devtool-use-devtool-modify-to-enable-work-on-code-associated-with-an-existing-recipe'>
1957 <title>Use <filename>devtool modify</filename> to Enable Work on Code Associated with an Existing Recipe</title>
1958
1959 <para>
1960 The <filename>devtool modify</filename> command prepares the
1961 way to work on existing code that already has a recipe in
1962 place.
1963 The command is flexible enough to allow you to extract code,
1964 specify the existing recipe, and keep track of and gather any
1965 patch files from other developers that are
1966 associated with the code.
1967 </para>
1968
1969 <para>
1970 Depending on your particular scenario, the arguments and options
1971 you use with <filename>devtool modify</filename> form different
1972 combinations.
1973 The following diagram shows common development flows
1974 you would use with the <filename>devtool modify</filename>
1975 command:
1976 </para>
1977
1978 <para>
1979 <imagedata fileref="figures/devtool-modify-flow.png" align="center" />
1980 </para>
1981
1982 <para>
1983 <orderedlist>
1984 <listitem><para><emphasis>Preparing to Modify the Code</emphasis>:
1985 The top part of the flow shows three scenarios by which
1986 you could use <filename>devtool modify</filename> to
1987 prepare to work on source files.
1988 Each scenario assumes the following:
1989 <itemizedlist>
1990 <listitem><para>The recipe exists in some layer external
1991 to the <filename>devtool</filename> workspace.
1992 </para></listitem>
1993 <listitem><para>The source files exist in a Git
1994 structure either upstream in an un-extracted
1995 state or locally in a previously extracted
1996 state.
1997 </para></listitem>
1998 </itemizedlist>
1999 The typical situation is where another developer has
2000 created some layer for use with the Yocto Project and
2001 their recipe already resides in that layer.
2002 Furthermore, their source code is readily available
2003 either upstream or locally.
2004 <itemizedlist>
2005 <listitem><para><emphasis>Left</emphasis>:
2006 The left scenario represents a situation
2007 where the source tree (srctree) exists as a
2008 previously extracted Git structure outside of
2009 the <filename>devtool</filename> workspace.
2010 In this example, the recipe also exists
2011 elsewhere in its own layer
2012 (i.e. <filename>meta-</filename><replaceable>layername</replaceable>).
2013 </para>
2014
2015 <para>The following command tells
2016 <filename>devtool</filename> the recipe
2017 with which to work and uses
2018 <replaceable>srctree</replaceable> to point to the
2019 previously extracted source files:
2020 <literallayout class='monospaced'>
2021 $ devtool modify <replaceable>recipe srctree</replaceable>
2022 </literallayout>
2023 Because <filename>devtool</filename> uses the
2024 <filename>conf/bblayers.conf</filename> to
2025 identify layers in which to look for recipes,
2026 you do not have to provide anything beyond a
2027 recipe's name with the command.
2028 In other words, you do not have to provide a
2029 full recipe pathname or provide any file naming
2030 extensions for <replaceable>recipe</replaceable>.
2031 </para>
2032
2033 <para>Once the command finishes, it creates only
2034 an append file for the recipe in the workspace.
2035 The recipe and the source code remain in their
2036 original locations.
2037 </para></listitem>
2038 <listitem><para><emphasis>Middle</emphasis>:
2039 The middle scenario represents a situation where
2040 the source code does not exist locally.
2041 In this case, the code is in an upstream Git
2042 repository and needs to be extracted to some
2043 local area.
2044 The recipe, in this scenario, is again in its own
2045 layer outside the workspace.</para>
2046
2047 <para>The following command tells
2048 <filename>devtool</filename> what recipe with
2049 which to work and also uses the "-x" option to
2050 instruct <filename>devtool</filename> to locate and
2051 extract the source code:
2052 <literallayout class='monospaced'>
2053 $ devtool modify -x <replaceable>recipe srctree</replaceable>
2054 </literallayout>
2055 With the help of the
2056 <filename>conf/bblayers.conf</filename> file,
2057 <filename>devtool</filename>locates the recipe.
2058 Inside the recipe, the
2059 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
2060 variable points to where the source code and
2061 any local patch files from other developers are
2062 located.
2063 <note>
2064 You cannot provide an URL for
2065 <replaceable>srctree</replaceable> when using the
2066 <filename>devtool modify</filename> command.
2067 </note>
2068 Once the files are located, the command extracts
2069 them to the location specified by
2070 <replaceable>srctree</replaceable>.</para>
2071
2072 <para>Within workspace, <filename>devtool</filename>
2073 creates an append file for the recipe.
2074 The recipe remains in its original location but
2075 the source files are extracted to the location you
2076 provided with <replaceable>srctree</replaceable>.
2077 </para></listitem>
2078 <listitem><para><emphasis>Right</emphasis>:
2079 The right scenario represents another situation
2080 where the source code does not exist locally
2081 and again needs to be extracted.
2082 However, in this situation, you want to extract the
2083 source into the workspace.
2084 The recipe, in this scenario, is again in its own
2085 layer outside the workspace.</para>
2086
2087 <para>The following command identifies the recipe
2088 and instructs <filename>devtool</filename> to
2089 extract the source files using the "-x" option:
2090 <literallayout class='monospaced'>
2091 $ devtool modify -x <replaceable>recipe</replaceable>
2092 </literallayout>
2093 As with the previous example, the
2094 <filename>conf/bblayers.conf</filename> file
2095 helps locate the recipe.
2096 And, as with all extractions, the command uses
2097 the recipe's <filename>SRC_URI</filename> to locate the
2098 source files.
2099 With this scenario, however, since no
2100 <replaceable>srctree</replaceable> argument exists, the
2101 <filename>devtool modify</filename> command extracts the
2102 source files to a Git structure using the default
2103 location within the workspace.
2104 The result is that the command set up both the source
2105 code and an append file within the workspace with the
2106 recipe remaining in its original location.
2107 </para></listitem>
2108 </itemizedlist>
2109 </para></listitem>
2110 <listitem><para><emphasis>Edit the Source</emphasis>:
2111 Once you have used the <filename>devtool modify</filename>
2112 command, you are free to make changes to the source
2113 files.
2114 You can use any editor you like to make and save
2115 your source code modifications.
2116 </para></listitem>
2117 <listitem><para><emphasis>Build the Recipe</emphasis>:
2118 Once you have updated the source files, you can build
2119 the recipe.
2120 You can either use <filename>devtool build</filename> or
2121 <filename>bitbake</filename>.
2122 Either method produces build output that is stored
2123 in
2124 <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>.
2125 </para></listitem>
2126 <listitem><para><emphasis>Test Your Changes</emphasis>:
2127 Once your code is built, you can test it for
2128 correct operation.
2129 If you have actual hardware, you can use the
2130 <filename>devtool deploy-target</filename> command
2131 to put the build output on the target.
2132 If you do not have target hardware, you can deploy
2133 the output to QEMU where it can emulate the hardware:
2134 <literallayout class='monospaced'>
2135 $ devtool deploy-target <replaceable>recipe target</replaceable>
2136 </literallayout>
2137 Regardless of where you are deploying the build
2138 output, the <replaceable>target</replaceable> must
2139 be running an SSH server.
2140 For example, to run the <filename>dropbear</filename>
2141 SSH server in an image you are going to be running on
2142 QEMU, be sure this statement is in your
2143 <filename>conf/local.conf</filename> file:
2144 <literallayout class='monospaced'>
2145 EXTRA_IMAGE_FEATURES += "ssh-server-dropbear"
2146 </literallayout>
2147 Here is a <filename>devtool deploy-target</filename>
2148 command example that uses the
2149 <filename>busybox</filename> recipe and QEMU as
2150 the target:
2151 <literallayout class='monospaced'>
2152 $ devtool deploy-target busybox root@192.168.7.2
2153 </literallayout>
2154 <note>
2155 It is worth mentioning that you can load an image
2156 onto your <replaceable>target</replaceable> and
2157 while it is running, deploy your package build
2158 output to the target as the image is running.
2159 You can also rebuild your image using
2160 <filename>bitbake</filename> and it will pick up
2161 your new package output.
2162 From there, you could re-run the image on QEMU
2163 to see the effects of your
2164 <filename>devtool build</filename> output.
2165 </note>
2166 You can continue to change, build, and test your
2167 changes until you are satisfied with the code's
2168 behavior.
2169 </para></listitem>
2170 <listitem><para><emphasis>Optionally Create Patch Files for Your Changes</emphasis>:
2171 After you have debugged your changes, you can
2172 use <filename>devtool update-recipe</filename> to
2173 generate patch files for all the commits you have
2174 made.
2175 <note>
2176 Patch files are generated only for changes
2177 you have committed.
2178 </note>
2179 <literallayout class='monospaced'>
2180 $ devtool update-recipe <replaceable>recipe</replaceable>
2181 </literallayout>
2182 By default, <filename>devtool</filename> updates
2183 the recipe's <filename>SRC_URI</filename> statement
2184 to include the location for the patch files it
2185 generates.
2186 <note>
2187 You can use the
2188 "--append <replaceable>LAYERDIR</replaceable>
2189 option to cause the command to create append files
2190 in a specific layer rather than the default
2191 recipe layer.
2192 </note>
2193 The command also creates a <replaceable>recipe</replaceable>
2194 folder beneath the folder in which the recipe resides
2195 that contains the actual <filename>*.patch</filename>
2196 files.
2197 </para></listitem>
2198 <listitem><para><emphasis>Make Sure the Recipe is in the Final Layer</emphasis>:
2199 Strictly speaking, this step is not necessary if
2200 you begin this workflow with the recipe in its own
2201 proper layer outside of the <filename>devtool</filename>
2202 workspace.
2203 However, it is included here so that when you do the
2204 final step following this you do not lose the recipe
2205 should it be in the workspace, which is possible
2206 (e.g. starting with <filename>devtool add</filename> to
2207 create a recipe in the workspace).</para>
2208
2209 <para>You should be sure that the recipe is located
2210 outside of the workspace before using the
2211 <filename>devtool reset</filename> command described in
2212 the next step.
2213 </para></listitem>
2214 <listitem><para><emphasis>Restore the Workspace</emphasis>:
2215 The <filename>devtool reset</filename> restores the
2216 state so that standard layers and upstream sources are
2217 used to build the recipe rather than what is in the
2218 workspace.
2219 Restoring the workspace removes all traces of the
2220 <replaceable>recipe</replaceable>.
2221 <literallayout class='monospaced'>
2222 $ devtool reset <replaceable>recipe</replaceable>
2223 </literallayout>
2224 Once the workspace is restored, you can use it again for
2225 working on different code.
2226 </para></listitem>
2227 </orderedlist>
2228 </para>
2229 </section>
1955 </section> 2230 </section>
1956 2231
1957 <section id='devtool-quick-reference'> 2232 <section id='devtool-quick-reference'>