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.xml212
1 files changed, 190 insertions, 22 deletions
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
index d71021da36..ff74063fc3 100644
--- a/documentation/dev-manual/dev-manual-model.xml
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -6,10 +6,6 @@
6 6
7<title>Common Development Models</title> 7<title>Common Development Models</title>
8 8
9<para role='writernotes'>
10 Test paragraph.
11</para>
12
13<para> 9<para>
14 Many development models exist for which you can use the Yocto Project. 10 Many development models exist for which you can use the Yocto Project.
15 This chapter overviews simple methods that use tools provided by the 11 This chapter overviews simple methods that use tools provided by the
@@ -2219,6 +2215,175 @@
2219 </orderedlist> 2215 </orderedlist>
2220 </para> 2216 </para>
2221 </section> 2217 </section>
2218
2219 <section id='devtool-use-devtool-upgrade-to-create-a-version-of-the-recipe-that-supports-a-newer-version-of-the-software'>
2220 <title>Use <filename>devtool upgrade</filename> to Create a Version of the Recipe that Supports a Newer Version of the Software</title>
2221
2222 <para>
2223 The <filename>devtool upgrade</filename> command updates
2224 an existing recipe so that you can build it for an updated
2225 set of source files.
2226 The command is flexible enough to allow you to specify
2227 source code revision and versioning schemes, extract code into
2228 or out of the <filename>devtool</filename> workspace, and
2229 work with any source file forms that the fetchers support.
2230 </para>
2231
2232 <para>
2233 Depending on your particular scenario, the arguments and options
2234 you use with <filename>devtool upgrade</filename> form different
2235 combinations.
2236 The following diagram shows a common development flow
2237 you would use with the <filename>devtool modify</filename>
2238 command:
2239 </para>
2240
2241 <para>
2242 <imagedata fileref="figures/devtool-upgrade-flow.png" align="center" />
2243 </para>
2244
2245 <para>
2246 <orderedlist>
2247 <listitem><para><emphasis>Initiate the Upgrade</emphasis>:
2248 The top part of the flow shows a typical scenario by which
2249 you could use <filename>devtool upgrade</filename>.
2250 The following conditions exist:
2251 <itemizedlist>
2252 <listitem><para>The recipe exists in some layer external
2253 to the <filename>devtool</filename> workspace.
2254 </para></listitem>
2255 <listitem><para>The source files for the new release
2256 exist adjacent to the same location pointed to by
2257 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
2258 in the recipe (e.g. a tarball with the new version
2259 number in the name, or as a different revision in
2260 the upstream Git repository).
2261 </para></listitem>
2262 </itemizedlist>
2263 A common situation is where third-party software has
2264 undergone a revision so that it has been upgraded.
2265 The recipe you have access to is likely in your own layer.
2266 Thus, you need to upgrade the recipe to use the
2267 newer version of the software:
2268 <literallayout class='monospaced'>
2269 $ devtool upgrade -V <replaceable>version recipe</replaceable>
2270 </literallayout>
2271 By default, the <filename>devtool upgrade</filename> command
2272 extracts source code into the <filename>sources</filename>
2273 directory in the workspace.
2274 If you want the code extracted to any other location, you
2275 need to provide the <replaceable>srctree</replaceable>
2276 positional argument with the command as follows:
2277 <literallayout class='monospaced'>
2278 $ devtool upgrade -V <replaceable>version recipe srctree</replaceable>
2279 </literallayout>
2280 Also, in this example, the "-V" option is used to specify
2281 the new version.
2282 If the source files pointed to by the
2283 <filename>SRC_URI</filename> statement in the recipe are
2284 in a Git repository, you must provide the "-S" option and
2285 specify a revision for the software.</para>
2286
2287 <para>Once <filename>devtool</filename> locates the recipe,
2288 it uses the <filename>SRC_URI</filename> variable to locate
2289 the source code and any local patch files from other
2290 developers are located.
2291 The result is that the command sets up the source
2292 code, the new version of the recipe, and an append file
2293 all within the workspace.
2294 </para></listitem>
2295 <listitem><para><emphasis>Resolve any Conflicts created by the Upgrade</emphasis>:
2296 At this point, there could be some conflicts due to the
2297 software being upgraded to a new version.
2298 This would occur if your recipe specifies some patch files in
2299 <filename>SRC_URI</filename> that conflict with changes
2300 made in the new version of the software.
2301 If this is the case, you need to resolve the conflicts
2302 by editing the source and following the normal
2303 <filename>git rebase</filename> conflict resolution
2304 process.</para>
2305
2306 <para>Before moving onto the next step, be sure to resolve any
2307 such conflicts created through use of a newer or different
2308 version of the software.
2309 </para></listitem>
2310 <listitem><para><emphasis>Build the Recipe</emphasis>:
2311 Once you have your recipe in order, you can build it.
2312 You can either use <filename>devtool build</filename> or
2313 <filename>bitbake</filename>.
2314 Either method produces build output that is stored
2315 in
2316 <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>.
2317 </para></listitem>
2318 <listitem><para><emphasis>Deploy the Build Output</emphasis>:
2319 When you use the <filename>devtool build</filename>
2320 command or <filename>bitbake</filename> to build out your
2321 recipe, you probably want to see if the resulting build
2322 output works as expected on target hardware.
2323 <note>
2324 This step assumes you have a previously built
2325 image that is already either running in QEMU or
2326 running on actual hardware.
2327 Also, it is assumed that for deployment of the image
2328 to the target, SSH is installed in the image and if
2329 the image is running on real hardware that you have
2330 network access to and from your development machine.
2331 </note>
2332 You can deploy your build output to that target hardware by
2333 using the <filename>devtool deploy-target</filename> command:
2334 <literallayout class='monospaced'>
2335 $ devtool deploy-target <replaceable>recipe target</replaceable>
2336 </literallayout>
2337 The <replaceable>target</replaceable> is a live target machine
2338 running as an SSH server.</para>
2339
2340 <para>You can, of course, also deploy the image you build
2341 using the <filename>devtool build-image</filename> command
2342 to actual hardware.
2343 However, <filename>devtool</filename> does not provide a
2344 specific command that allows you to do this.
2345 </para></listitem>
2346 <listitem><para><emphasis>Optionally Create Patch Files for Your Changes</emphasis>:
2347 After you have debugged your changes, you can
2348 use <filename>devtool update-recipe</filename> to
2349 generate patch files for all the commits you have
2350 made.
2351 <note>
2352 Patch files are generated only for changes
2353 you have committed.
2354 </note>
2355 <literallayout class='monospaced'>
2356 $ devtool update-recipe <replaceable>recipe</replaceable>
2357 </literallayout>
2358 By default, the
2359 <filename>devtool update-recipe</filename> command
2360 creates the patch files in a folder named the same
2361 as the recipe beneath the folder in which the recipe
2362 resides, and updates the recipe's
2363 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
2364 statement to point to the generated patch files.
2365 </para></listitem>
2366 <listitem><para><emphasis>Move the Recipe to its Permanent Layer</emphasis>:
2367 Before cleaning up the workspace, you need to move the
2368 final recipe to its permanent layer.
2369 You can either overwrite the original recipe or you can
2370 overlay the upgraded recipe into a separate layer.
2371 You must do this before using the
2372 <filename>devtool reset</filename> command if you want to
2373 retain the upgraded recipe.
2374 </para></listitem>
2375 <listitem><para><emphasis>Restore the Workspace</emphasis>:
2376 The <filename>devtool reset</filename> restores the
2377 state so that standard layers and upstream sources are
2378 used to build the recipe rather than what is in the
2379 workspace.
2380 <literallayout class='monospaced'>
2381 $ devtool reset <replaceable>recipe</replaceable>
2382 </literallayout>
2383 </para></listitem>
2384 </orderedlist>
2385 </para>
2386 </section>
2222 </section> 2387 </section>
2223 2388
2224 <section id='devtool-quick-reference'> 2389 <section id='devtool-quick-reference'>
@@ -2256,24 +2421,27 @@
2256 -h, --help show this help message and exit 2421 -h, --help show this help message and exit
2257 2422
2258 subcommands: 2423 subcommands:
2259 &lt;subcommand&gt; 2424 Beginning work on a recipe:
2260 create-workspace Set up workspace in an alternative location 2425 add Add a new recipe
2261 upgrade Upgrade an existing recipe 2426 modify Modify the source for an existing recipe
2262 deploy-target Deploy recipe output files to live target machine 2427 upgrade Upgrade an existing recipe
2263 undeploy-target Undeploy recipe output files in live target machine 2428 Getting information:
2264 search Search available recipes 2429 status Show workspace status
2265 build Build a recipe 2430 search Search available recipes
2266 edit-recipe Edit a recipe file in your workspace 2431 Working on a recipe in the workspace:
2267 configure-help Get help on configure script options 2432 build Build a recipe
2268 add Add a new recipe 2433 edit-recipe Edit a recipe file in your workspace
2269 modify Modify the source for an existing recipe 2434 configure-help Get help on configure script options
2270 extract Extract the source for an existing recipe 2435 update-recipe Apply changes from external source tree to recipe
2271 sync Synchronize the source tree for an existing recipe 2436 reset Remove a recipe from your workspace
2272 update-recipe Apply changes from external source tree to recipe 2437 Testing changes on target:
2273 status Show workspace status 2438 deploy-target Deploy recipe output files to live target machine
2274 reset Remove a recipe from your workspace 2439 undeploy-target Undeploy recipe output files in live target machine
2275 build-image Build image including workspace recipe packages 2440 build-image Build image including workspace recipe packages
2276 2441 Advanced:
2442 create-workspace Set up workspace in an alternative location
2443 extract Extract the source for an existing recipe
2444 sync Synchronize the source tree for an existing recipe
2277 Use devtool &lt;subcommand&gt; --help to get help on a specific command 2445 Use devtool &lt;subcommand&gt; --help to get help on a specific command
2278 </literallayout> 2446 </literallayout>
2279 </para> 2447 </para>