summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2016-09-19 13:52:07 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2016-09-28 15:02:32 +0100
commited6a5495a19b7f2bc0f9ae35027b27f2bb973576 (patch)
tree4b09d10b7d3f677ed3961375e6be73d2ac22e226 /documentation
parent38278f0a2162fbb0fda6d5b00d73495906acb968 (diff)
downloadpoky-ed6a5495a19b7f2bc0f9ae35027b27f2bb973576.tar.gz
documentation: devtool upgrade and quick ref changes to mult manuals
Did the following: * Added the devtool upgrade flow to the SDK manual. * Removed the devtool Quick Reference from the dev-manual and added it as a new chapter to the ref-manual. * Made sure all the links and cross-references work now with the moved material. * Updated the Make file so that the manual set builds correctly regarding the new chapter in the ref-manual. * Created cross-referencing notes in both the sdk-manual and the dev-manual to the newly located devtool Quick Reference chapter. (From yocto-docs rev: fda0bf68b3654b1b96407d552c5254657465b5fc) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation')
-rw-r--r--documentation/Makefile9
-rw-r--r--documentation/dev-manual/dev-manual-model.xml593
-rw-r--r--documentation/mega-manual/figures/sdk-devtool-upgrade-flow.pngbin0 -> 139827 bytes
-rw-r--r--documentation/ref-manual/figures/build-workspace-directory.png (renamed from documentation/dev-manual/figures/build-workspace-directory.png)bin29627 -> 29627 bytes
-rw-r--r--documentation/ref-manual/introduction.xml5
-rw-r--r--documentation/ref-manual/ref-devtool-reference.xml585
-rw-r--r--documentation/ref-manual/ref-manual.xml2
-rw-r--r--documentation/sdk-manual/sdk-extensible.xml6
8 files changed, 610 insertions, 590 deletions
diff --git a/documentation/Makefile b/documentation/Makefile
index 418d3ca8c7..9077c81215 100644
--- a/documentation/Makefile
+++ b/documentation/Makefile
@@ -133,7 +133,7 @@ TARFILES = dev-style.css dev-manual.html \
133 figures/index-downloads.png figures/kernel-dev-flow.png \ 133 figures/index-downloads.png figures/kernel-dev-flow.png \
134 figures/kernel-overview-1.png figures/kernel-overview-2-generic.png \ 134 figures/kernel-overview-1.png figures/kernel-overview-2-generic.png \
135 figures/source-repos.png figures/yp-download.png \ 135 figures/source-repos.png figures/yp-download.png \
136 figures/recipe-workflow.png figures/build-workspace-directory.png \ 136 figures/recipe-workflow.png \
137 figures/devtool-add-flow.png figures/devtool-modify-flow.png \ 137 figures/devtool-add-flow.png figures/devtool-modify-flow.png \
138 figures/devtool-upgrade-flow.png \ 138 figures/devtool-upgrade-flow.png \
139 eclipse 139 eclipse
@@ -249,7 +249,8 @@ TARFILES = mega-manual.html mega-style.css figures/yocto-environment.png \
249 figures/compatible-layers.png figures/import-layer.png figures/new-project.png \ 249 figures/compatible-layers.png figures/import-layer.png figures/new-project.png \
250 figures/sdk-environment.png figures/sdk-installed-standard-sdk-directory.png \ 250 figures/sdk-environment.png figures/sdk-installed-standard-sdk-directory.png \
251 figures/sdk-devtool-add-flow.png figures/sdk-installed-extensible-sdk-directory.png \ 251 figures/sdk-devtool-add-flow.png figures/sdk-installed-extensible-sdk-directory.png \
252 figures/sdk-devtool-modify-flow.png figures/sdk-eclipse-dev-flow.png 252 figures/sdk-devtool-modify-flow.png figures/sdk-eclipse-dev-flow.png \
253 figures/sdk-devtool-upgrade-flow.png
253 endif 254 endif
254 255
255MANUALS = $(DOC)/$(DOC).html 256MANUALS = $(DOC)/$(DOC).html
@@ -269,7 +270,8 @@ TARFILES = ref-manual.html ref-style.css figures/poky-title.png \
269 figures/images.png figures/sdk.png figures/source-fetching.png \ 270 figures/images.png figures/sdk.png figures/source-fetching.png \
270 figures/patching.png figures/configuration-compile-autoreconf.png \ 271 figures/patching.png figures/configuration-compile-autoreconf.png \
271 figures/analysis-for-package-splitting.png figures/image-generation.png \ 272 figures/analysis-for-package-splitting.png figures/image-generation.png \
272 figures/sdk-generation.png figures/building-an-image.png 273 figures/sdk-generation.png figures/building-an-image.png \
274 figures/build-workspace-directory.png
273MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse 275MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse
274FIGURES = figures 276FIGURES = figures
275STYLESHEET = $(DOC)/*.css 277STYLESHEET = $(DOC)/*.css
@@ -282,6 +284,7 @@ TARFILES = sdk-manual.html sdk-style.css figures/sdk-title.png \
282 figures/sdk-environment.png figures/sdk-installed-standard-sdk-directory.png \ 284 figures/sdk-environment.png figures/sdk-installed-standard-sdk-directory.png \
283 figures/sdk-installed-extensible-sdk-directory.png figures/sdk-devtool-add-flow.png \ 285 figures/sdk-installed-extensible-sdk-directory.png figures/sdk-devtool-add-flow.png \
284 figures/sdk-devtool-modify-flow.png figures/sdk-eclipse-dev-flow.png \ 286 figures/sdk-devtool-modify-flow.png figures/sdk-eclipse-dev-flow.png \
287 figures/sdk-devtool-upgrade-flow.png \
285 eclipse 288 eclipse
286MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse 289MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse
287FIGURES = figures 290FIGURES = figures
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
index 0385fac44c..1edead3d6b 100644
--- a/documentation/dev-manual/dev-manual-model.xml
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -646,6 +646,12 @@
646 646
647 <para> 647 <para>
648 The remainder of this section presents these workflows. 648 The remainder of this section presents these workflows.
649 <note>
650 See the
651 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-devtool-reference'><filename>devtool</filename>&nbsp;Quick Reference</ulink>"
652 in the Yocto Project Reference Manual for more a
653 <filename>devtool</filename> reference.
654 </note>
649 </para> 655 </para>
650 656
651 <section id='use-devtool-to-integrate-new-code'> 657 <section id='use-devtool-to-integrate-new-code'>
@@ -1259,593 +1265,6 @@
1259 </section> 1265 </section>
1260 </section> 1266 </section>
1261 1267
1262 <section id='devtool-quick-reference'>
1263 <title><filename>devtool</filename> Quick Reference</title>
1264
1265 <para>
1266 <filename>devtool</filename> has more functionality than simply
1267 adding a new recipe and the supporting Metadata to a temporary
1268 workspace layer.
1269 This section provides a short reference on
1270 <filename>devtool</filename> and its commands.
1271 </para>
1272
1273 <section id='devtool-getting-help'>
1274 <title>Getting Help</title>
1275
1276 <para>
1277 The easiest way to get help with the
1278 <filename>devtool</filename> command is using the
1279 <filename>--help</filename> option:
1280 <literallayout class='monospaced'>
1281 usage: devtool [--basepath BASEPATH] [--bbpath BBPATH] [-d] [-q]
1282 [--color COLOR] [-h]
1283 &lt;subcommand&gt; ...
1284
1285 OpenEmbedded development tool
1286
1287 options:
1288 --basepath BASEPATH Base directory of SDK / build directory
1289 --bbpath BBPATH Explicitly specify the BBPATH, rather than getting it
1290 from the metadata
1291 -d, --debug Enable debug output
1292 -q, --quiet Print only errors
1293 --color COLOR Colorize output (where COLOR is auto, always, never)
1294 -h, --help show this help message and exit
1295
1296 subcommands:
1297 Beginning work on a recipe:
1298 add Add a new recipe
1299 modify Modify the source for an existing recipe
1300 upgrade Upgrade an existing recipe
1301 Getting information:
1302 status Show workspace status
1303 search Search available recipes
1304 Working on a recipe in the workspace:
1305 edit-recipe Edit a recipe file in your workspace
1306 configure-help Get help on configure script options
1307 build Build a recipe
1308 update-recipe Apply changes from external source tree to recipe
1309 reset Remove a recipe from your workspace
1310 finish Finish working on a recipe in your workspace
1311 Testing changes on target:
1312 deploy-target Deploy recipe output files to live target machine
1313 undeploy-target Undeploy recipe output files in live target machine
1314 build-image Build image including workspace recipe packages
1315 Advanced:
1316 create-workspace Set up workspace in an alternative location
1317 extract Extract the source for an existing recipe
1318 sync Synchronize the source tree for an existing recipe
1319 Use devtool &lt;subcommand&gt; --help to get help on a specific command
1320 </literallayout>
1321 </para>
1322
1323 <para>
1324 As directed in the general help output, you can get more
1325 syntax on a specific command by providing the command
1326 name and using <filename>--help</filename>:
1327 <literallayout class='monospaced'>
1328 $ devtool add --help
1329 usage: devtool add [-h] [--same-dir | --no-same-dir] [--fetch URI]
1330 [--version VERSION] [--no-git] [--autorev] [--binary]
1331 [--also-native] [--src-subdir SUBDIR]
1332 [recipename] [srctree] [fetchuri]
1333
1334 Adds a new recipe to the workspace to build a specified source tree. Can
1335 optionally fetch a remote URI and unpack it to create the source tree.
1336
1337 arguments:
1338 recipename Name for new recipe to add (just name - no version,
1339 path or extension). If not specified, will attempt to
1340 auto-detect it.
1341 srctree Path to external source tree. If not specified, a
1342 subdirectory of
1343 /home/scottrif/poky/build/workspace/sources will be
1344 used.
1345 fetchuri Fetch the specified URI and extract it to create the
1346 source tree
1347
1348 options:
1349 -h, --help show this help message and exit
1350 --same-dir, -s Build in same directory as source
1351 --no-same-dir Force build in a separate build directory
1352 --fetch URI, -f URI Fetch the specified URI and extract it to create the
1353 source tree (deprecated - pass as positional argument
1354 instead)
1355 --version VERSION, -V VERSION
1356 Version to use within recipe (PV)
1357 --no-git, -g If fetching source, do not set up source tree as a git
1358 repository
1359 --autorev, -a When fetching from a git repository, set SRCREV in the
1360 recipe to a floating revision instead of fixed
1361 --binary, -b Treat the source tree as something that should be
1362 installed verbatim (no compilation, same directory
1363 structure). Useful with binary packages e.g. RPMs.
1364 --also-native Also add native variant (i.e. support building recipe
1365 for the build host as well as the target machine)
1366 --src-subdir SUBDIR Specify subdirectory within source tree to use
1367 </literallayout>
1368 </para>
1369 </section>
1370
1371 <section id='devtool-the-workspace-layer-structure'>
1372 <title>The Workspace Layer Structure</title>
1373
1374 <para>
1375 <filename>devtool</filename> uses a "Workspace" layer
1376 in which to accomplish builds.
1377 This layer is not specific to any single
1378 <filename>devtool</filename> command but is rather a common
1379 working area used across the tool.
1380 </para>
1381
1382 <para>
1383 The following figure shows the workspace structure:
1384 </para>
1385
1386 <para>
1387 <imagedata fileref="figures/build-workspace-directory.png"
1388 width="6in" depth="5in" align="left" scale="70" />
1389 </para>
1390
1391 <para>
1392 <literallayout class='monospaced'>
1393 attic - A directory created if devtool believes it preserve
1394 anything when you run "devtool reset". For example, if you
1395 run "devtool add", make changes to the recipe, and then
1396 run "devtool reset", devtool takes notice that the file has
1397 been changed and moves it into the attic should you still
1398 want the recipe.
1399
1400 README - Provides information on what is in workspace layer and how to
1401 manage it.
1402
1403 .devtool_md5 - A checksum file used by devtool.
1404
1405 appends - A directory that contains *.bbappend files, which point to
1406 external source.
1407
1408 conf - A configuration directory that contains the layer.conf file.
1409
1410 recipes - A directory containing recipes. This directory contains a
1411 folder for each directory added whose name matches that of the
1412 added recipe. devtool places the <replaceable>recipe</replaceable>.bb file
1413 within that sub-directory.
1414
1415 sources - A directory containing a working copy of the source files used
1416 when building the recipe. This is the default directory used
1417 as the location of the source tree when you do not provide a
1418 source tree path. This directory contains a folder for each
1419 set of source files matched to a corresponding recipe.
1420 </literallayout>
1421 </para>
1422 </section>
1423
1424 <section id='devtool-adding-a-new-recipe-to-the-workspace'>
1425 <title>Adding a New Recipe to the Workspace Layer</title>
1426
1427 <para>
1428 Use the <filename>devtool add</filename> command to add a new recipe
1429 to the workspace layer.
1430 The recipe you add should not exist -
1431 <filename>devtool</filename> creates it for you.
1432 The source files the recipe uses should exist in an external
1433 area.
1434 </para>
1435
1436 <para>
1437 The following example creates and adds a new recipe named
1438 <filename>jackson</filename> to a workspace layer the tool creates.
1439 The source code built by the recipes resides in
1440 <filename>/home/scottrif/sources/jackson</filename>:
1441 <literallayout class='monospaced'>
1442 $ devtool add jackson /home/scottrif/sources/jackson
1443 </literallayout>
1444 </para>
1445
1446 <para>
1447 If you add a recipe and the workspace layer does not exist,
1448 the command creates the layer and populates it as
1449 described in
1450 "<link linkend='devtool-the-workspace-layer-structure'>The Workspace Layer Structure</link>"
1451 section.
1452 </para>
1453
1454 <para>
1455 Running <filename>devtool add</filename> when the
1456 workspace layer exists causes the tool to add the recipe,
1457 append files, and source files into the existing workspace layer.
1458 The <filename>.bbappend</filename> file is created to point
1459 to the external source tree.
1460 </para>
1461 </section>
1462
1463 <section id='devtool-extracting-the-source-for-an-existing-recipe'>
1464 <title>Extracting the Source for an Existing Recipe</title>
1465
1466 <para>
1467 Use the <filename>devtool extract</filename> command to
1468 extract the source for an existing recipe.
1469 When you use this command, you must supply the root name
1470 of the recipe (i.e. no version, paths, or extensions), and
1471 you must supply the directory to which you want the source
1472 extracted.
1473 </para>
1474
1475 <para>
1476 Additional command options let you control the name of a
1477 development branch into which you can checkout the source
1478 and whether or not to keep a temporary directory, which is
1479 useful for debugging.
1480 </para>
1481 </section>
1482
1483 <section id='devtool-synchronizing-a-recipes-extracted-source-tree'>
1484 <title>Synchronizing a Recipe's Extracted Source Tree</title>
1485
1486 <para>
1487 Use the <filename>devtool sync</filename> command to
1488 synchronize a previously extracted source tree for an
1489 existing recipe.
1490 When you use this command, you must supply the root name
1491 of the recipe (i.e. no version, paths, or extensions), and
1492 you must supply the directory to which you want the source
1493 extracted.
1494 </para>
1495
1496 <para>
1497 Additional command options let you control the name of a
1498 development branch into which you can checkout the source
1499 and whether or not to keep a temporary directory, which is
1500 useful for debugging.
1501 </para>
1502 </section>
1503
1504 <section id='devtool-modifying-a-recipe'>
1505 <title>Modifying an Existing Recipe</title>
1506
1507 <para>
1508 Use the <filename>devtool modify</filename> command to begin
1509 modifying the source of an existing recipe.
1510 This command is very similar to the
1511 <link linkend='devtool-adding-a-new-recipe-to-the-workspace'><filename>add</filename></link>
1512 command except that it does not physically create the
1513 recipe in the workspace layer because the recipe already
1514 exists in an another layer.
1515 </para>
1516
1517 <para>
1518 The <filename>devtool modify</filename> command extracts the
1519 source for a recipe, sets it up as a Git repository if the
1520 source had not already been fetched from Git, checks out a
1521 branch for development, and applies any patches from the recipe
1522 as commits on top.
1523 You can use the following command to checkout the source
1524 files:
1525 <literallayout class='monospaced'>
1526 $ devtool modify <replaceable>recipe</replaceable>
1527 </literallayout>
1528 Using the above command form, <filename>devtool</filename> uses
1529 the existing recipe's
1530 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
1531 statement to locate the upstream source, extracts the source
1532 into the default sources location in the workspace.
1533 The default development branch used is "devtool".
1534 </para>
1535 </section>
1536
1537 <section id='devtool-edit-an-existing-recipe'>
1538 <title>Edit an Existing Recipe</title>
1539
1540 <para>
1541 Use the <filename>devtool edit-recipe</filename> command
1542 to run the default editor, which is identified using the
1543 <filename>EDITOR</filename> variable, on the specified recipe.
1544 </para>
1545
1546 <para>
1547 When you use the <filename>devtool edit-recipe</filename>
1548 command, you must supply the root name of the recipe
1549 (i.e. no version, paths, or extensions).
1550 Also, the recipe file itself must reside in the workspace
1551 as a result of the <filename>devtool add</filename> or
1552 <filename>devtool upgrade</filename> commands.
1553 However, you can override that requirement by using the
1554 "-a" or "--any-recipe" option.
1555 Using either of these options allows you to edit any recipe
1556 regardless of its location.
1557 </para>
1558 </section>
1559
1560 <section id='devtool-updating-a-recipe'>
1561 <title>Updating a Recipe</title>
1562
1563 <para>
1564 Use the <filename>devtool update-recipe</filename> command to
1565 update your recipe with patches that reflect changes you make
1566 to the source files.
1567 For example, if you know you are going to work on some
1568 code, you could first use the
1569 <link linkend='devtool-modifying-a-recipe'><filename>devtool modify</filename></link>
1570 command to extract the code and set up the workspace.
1571 After which, you could modify, compile, and test the code.
1572 </para>
1573
1574 <para>
1575 When you are satisfied with the results and you have committed
1576 your changes to the Git repository, you can then
1577 run the <filename>devtool update-recipe</filename> to create the
1578 patches and update the recipe:
1579 <literallayout class='monospaced'>
1580 $ devtool update-recipe <replaceable>recipe</replaceable>
1581 </literallayout>
1582 If you run the <filename>devtool update-recipe</filename>
1583 without committing your changes, the command ignores the
1584 changes.
1585 </para>
1586
1587 <para>
1588 Often, you might want to apply customizations made to your
1589 software in your own layer rather than apply them to the
1590 original recipe.
1591 If so, you can use the
1592 <filename>-a</filename> or <filename>--append</filename>
1593 option with the <filename>devtool update-recipe</filename>
1594 command.
1595 These options allow you to specify the layer into which to
1596 write an append file:
1597 <literallayout class='monospaced'>
1598 $ devtool update-recipe <replaceable>recipe</replaceable> -a <replaceable>base-layer-directory</replaceable>
1599 </literallayout>
1600 The <filename>*.bbappend</filename> file is created at the
1601 appropriate path within the specified layer directory, which
1602 may or may not be in your <filename>bblayers.conf</filename>
1603 file.
1604 If an append file already exists, the command updates it
1605 appropriately.
1606 </para>
1607 </section>
1608
1609 <section id='devtool-upgrading-a-recipe'>
1610 <title>Upgrading a Recipe</title>
1611
1612 <para>
1613 Use the <filename>devtool upgrade</filename> command
1614 to upgrade an existing recipe to a new upstream version.
1615 The command puts the upgraded recipe file into the
1616 workspace along with any associated files, and extracts
1617 the source tree to a specified location should patches
1618 need rebased or added to as a result of the upgrade.
1619 </para>
1620
1621 <para>
1622 When you use the <filename>devtool upgrade</filename> command,
1623 you must supply the root name of the recipe (i.e. no version,
1624 paths, or extensions), and you must supply the directory
1625 to which you want the source extracted.
1626 Additional command options let you control things such as
1627 the version number to which you want to upgrade (i.e. the
1628 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>),
1629 the source revision to which you want to upgrade (i.e. the
1630 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>,
1631 whether or not to apply patches, and so forth.
1632 </para>
1633 </section>
1634
1635 <section id='devtool-resetting-a-recipe'>
1636 <title>Resetting a Recipe</title>
1637
1638 <para>
1639 Use the <filename>devtool reset</filename> command to remove a
1640 recipe and its configuration (e.g. the corresponding
1641 <filename>.bbappend</filename> file) from the workspace layer.
1642 Realize that this command deletes the recipe and the
1643 append file.
1644 The command does not physically move them for you.
1645 Consequently, you must be sure to physically relocate your
1646 updated recipe and the append file outside of the workspace
1647 layer before running the <filename>devtool reset</filename>
1648 command.
1649 </para>
1650
1651 <para>
1652 If the <filename>devtool reset</filename> command detects that
1653 the recipe or the append files have been modified, the
1654 command preserves the modified files in a separate "attic"
1655 subdirectory under the workspace layer.
1656 </para>
1657
1658 <para>
1659 Here is an example that resets the workspace directory that
1660 contains the <filename>mtr</filename> recipe:
1661 <literallayout class='monospaced'>
1662 $ devtool reset mtr
1663 NOTE: Cleaning sysroot for recipe mtr...
1664 NOTE: Leaving source tree /home/scottrif/poky/build/workspace/sources/mtr as-is; if you no
1665 longer need it then please delete it manually
1666 $
1667 </literallayout>
1668 </para>
1669 </section>
1670
1671 <section id='devtool-building-your-recipe'>
1672 <title>Building Your Recipe</title>
1673
1674 <para>
1675 Use the <filename>devtool build</filename> command to cause the
1676 OpenEmbedded build system to build your recipe.
1677 The <filename>devtool build</filename> command is equivalent to
1678 <filename>bitbake -c populate_sysroot</filename>.
1679 </para>
1680
1681 <para>
1682 When you use the <filename>devtool build</filename> command,
1683 you must supply the root name of the recipe (i.e. no version,
1684 paths, or extensions).
1685 You can use either the "-s" or the "--disable-parallel-make"
1686 option to disable parallel makes during the build.
1687 Here is an example:
1688 <literallayout class='monospaced'>
1689 $ devtool build <replaceable>recipe</replaceable>
1690 </literallayout>
1691 </para>
1692 </section>
1693
1694 <section id='devtool-building-your-image'>
1695 <title>Building Your Image</title>
1696
1697 <para>
1698 Use the <filename>devtool build-image</filename> command
1699 to build an image, extending it to include packages from
1700 recipes in the workspace.
1701 Using this command is useful when you want an image that
1702 ready for immediate deployment onto a device for testing.
1703 For proper integration into a final image, you need to
1704 edit your custom image recipe appropriately.
1705 </para>
1706
1707 <para>
1708 When you use the <filename>devtool build-image</filename>
1709 command, you must supply the name of the image.
1710 This command has no command line options:
1711 <literallayout class='monospaced'>
1712 $ devtool build-image <replaceable>image</replaceable>
1713 </literallayout>
1714 </para>
1715 </section>
1716
1717 <section id='devtool-deploying-your-software-on-the-target-machine'>
1718 <title>Deploying Your Software on the Target Machine</title>
1719
1720 <para>
1721 Use the <filename>devtool deploy-target</filename> command to
1722 deploy the recipe's build output to the live target machine:
1723 <literallayout class='monospaced'>
1724 $ devtool deploy-target <replaceable>recipe</replaceable>&nbsp;<replaceable>target</replaceable>
1725 </literallayout>
1726 The <replaceable>target</replaceable> is the address of the
1727 target machine, which must be running an SSH server (i.e.
1728 <filename>user@hostname[:destdir]</filename>).
1729 </para>
1730
1731 <para>
1732 This command deploys all files installed during the
1733 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
1734 task.
1735 Furthermore, you do not need to have package management enabled
1736 within the target machine.
1737 If you do, the package manager is bypassed.
1738 <note><title>Notes</title>
1739 <para>
1740 The <filename>deploy-target</filename>
1741 functionality is for development only.
1742 You should never use it to update an image that will be
1743 used in production.
1744 </para>
1745 </note>
1746 </para>
1747 </section>
1748
1749 <section id='devtool-removing-your-software-from-the-target-machine'>
1750 <title>Removing Your Software from the Target Machine</title>
1751
1752 <para>
1753 Use the <filename>devtool undeploy-target</filename> command to
1754 remove deployed build output from the target machine.
1755 For the <filename>devtool undeploy-target</filename> command to
1756 work, you must have previously used the
1757 <link linkend='devtool-deploying-your-software-on-the-target-machine'><filename>devtool deploy-target</filename></link>
1758 command.
1759 <literallayout class='monospaced'>
1760 $ devtool undeploy-target <replaceable>recipe</replaceable>&nbsp;<replaceable>target</replaceable>
1761 </literallayout>
1762 The <replaceable>target</replaceable> is the address of the
1763 target machine, which must be running an SSH server (i.e.
1764 <filename>user@hostname</filename>).
1765 </para>
1766 </section>
1767
1768 <section id='devtool-creating-the-workspace'>
1769 <title>Creating the Workspace Layer in an Alternative Location</title>
1770
1771 <para>
1772 Use the <filename>devtool create-workspace</filename> command to
1773 create a new workspace layer in your
1774 <link linkend='build-directory'>Build Directory</link>.
1775 When you create a new workspace layer, it is populated with the
1776 <filename>README</filename> file and the
1777 <filename>conf</filename> directory only.
1778 </para>
1779
1780 <para>
1781 The following example creates a new workspace layer in your
1782 current working and by default names the workspace layer
1783 "workspace":
1784 <literallayout class='monospaced'>
1785 $ devtool create-workspace
1786 </literallayout>
1787 </para>
1788
1789 <para>
1790 You can create a workspace layer anywhere by supplying
1791 a pathname with the command.
1792 The following command creates a new workspace layer named
1793 "new-workspace":
1794 <literallayout class='monospaced'>
1795 $ devtool create-workspace /home/scottrif/new-workspace
1796 </literallayout>
1797 </para>
1798 </section>
1799
1800 <section id='devtool-get-the-status-of-the-recipes-in-your-workspace'>
1801 <title>Get the Status of the Recipes in Your Workspace</title>
1802
1803 <para>
1804 Use the <filename>devtool status</filename> command to
1805 list the recipes currently in your workspace.
1806 Information includes the paths to their respective
1807 external source trees.
1808 </para>
1809
1810 <para>
1811 The <filename>devtool status</filename> command has no
1812 command-line options:
1813 <literallayout class='monospaced'>
1814 devtool status
1815 </literallayout>
1816 Following is sample output after using
1817 <link linkend='devtool-adding-a-new-recipe-to-the-workspace'><filename>devtool add</filename></link>
1818 to create and add the <filename>mtr_0.86.bb</filename> recipe
1819 to the <filename>workspace</filename> directory:
1820 <literallayout class='monospaced'>
1821 $ devtool status
1822 mtr: /home/scottrif/poky/build/workspace/sources/mtr (/home/scottrif/poky/build/workspace/recipes/mtr/mtr_0.86.bb)
1823 $
1824 </literallayout>
1825 </para>
1826 </section>
1827
1828 <section id='devtool-search-for-available-target-recipes'>
1829 <title>Search for Available Target Recipes</title>
1830
1831 <para>
1832 Use the <filename>devtool search</filename> command to
1833 search for available target recipes.
1834 The command matches the recipe name, package name,
1835 description, and installed files.
1836 The command displays the recipe name as a result of a
1837 match.
1838 </para>
1839
1840 <para>
1841 When you use the <filename>devtool search</filename> command,
1842 you must supply a <replaceable>keyword</replaceable>.
1843 The command uses the <replaceable>keyword</replaceable> when
1844 searching for a match.
1845 </para>
1846 </section>
1847 </section>
1848
1849 <section id="using-a-quilt-workflow"> 1268 <section id="using-a-quilt-workflow">
1850 <title>Using Quilt in Your Workflow</title> 1269 <title>Using Quilt in Your Workflow</title>
1851 1270
diff --git a/documentation/mega-manual/figures/sdk-devtool-upgrade-flow.png b/documentation/mega-manual/figures/sdk-devtool-upgrade-flow.png
new file mode 100644
index 0000000000..65474dad02
--- /dev/null
+++ b/documentation/mega-manual/figures/sdk-devtool-upgrade-flow.png
Binary files differ
diff --git a/documentation/dev-manual/figures/build-workspace-directory.png b/documentation/ref-manual/figures/build-workspace-directory.png
index 5387d33f03..5387d33f03 100644
--- a/documentation/dev-manual/figures/build-workspace-directory.png
+++ b/documentation/ref-manual/figures/build-workspace-directory.png
Binary files differ
diff --git a/documentation/ref-manual/introduction.xml b/documentation/ref-manual/introduction.xml
index d5f0b279fd..0f43f0d199 100644
--- a/documentation/ref-manual/introduction.xml
+++ b/documentation/ref-manual/introduction.xml
@@ -80,6 +80,11 @@
80 Describes the tasks defined by the OpenEmbedded build system. 80 Describes the tasks defined by the OpenEmbedded build system.
81 </para></listitem> 81 </para></listitem>
82 <listitem><para><emphasis> 82 <listitem><para><emphasis>
83 <link linkend='ref-devtool-reference'><filename>devtool</filename> Quick Reference</link>:</emphasis>
84 Provides a quick reference for the <filename>devtool</filename>
85 command.
86 </para></listitem>
87 <listitem><para><emphasis>
83 <link linkend='ref-qa-checks'>QA Error and Warning Messages</link>:</emphasis> 88 <link linkend='ref-qa-checks'>QA Error and Warning Messages</link>:</emphasis>
84 Lists and describes QA warning and error messages. 89 Lists and describes QA warning and error messages.
85 </para></listitem> 90 </para></listitem>
diff --git a/documentation/ref-manual/ref-devtool-reference.xml b/documentation/ref-manual/ref-devtool-reference.xml
new file mode 100644
index 0000000000..7506f441ea
--- /dev/null
+++ b/documentation/ref-manual/ref-devtool-reference.xml
@@ -0,0 +1,585 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<chapter id='ref-devtool-reference'>
6 <title><filename>devtool</filename> Quick Reference</title>
7
8 <section id='devtool-getting-help'>
9 <title>Getting Help</title>
10
11 <para>
12 The easiest way to get help with the
13 <filename>devtool</filename> command is using the
14 <filename>--help</filename> option:
15 <literallayout class='monospaced'>
16 usage: devtool [--basepath BASEPATH] [--bbpath BBPATH] [-d] [-q]
17 [--color COLOR] [-h]
18 &lt;subcommand&gt; ...
19
20 OpenEmbedded development tool
21
22 options:
23 --basepath BASEPATH Base directory of SDK / build directory
24 --bbpath BBPATH Explicitly specify the BBPATH, rather than getting it
25 from the metadata
26 -d, --debug Enable debug output
27 -q, --quiet Print only errors
28 --color COLOR Colorize output (where COLOR is auto, always, never)
29 -h, --help show this help message and exit
30
31 subcommands:
32 Beginning work on a recipe:
33 add Add a new recipe
34 modify Modify the source for an existing recipe
35 upgrade Upgrade an existing recipe
36 Getting information:
37 status Show workspace status
38 search Search available recipes
39 Working on a recipe in the workspace:
40 edit-recipe Edit a recipe file in your workspace
41 configure-help Get help on configure script options
42 build Build a recipe
43 update-recipe Apply changes from external source tree to recipe
44 reset Remove a recipe from your workspace
45 finish Finish working on a recipe in your workspace
46 Testing changes on target:
47 deploy-target Deploy recipe output files to live target machine
48 undeploy-target Undeploy recipe output files in live target machine
49 build-image Build image including workspace recipe packages
50 Advanced:
51 create-workspace Set up workspace in an alternative location
52 extract Extract the source for an existing recipe
53 sync Synchronize the source tree for an existing recipe
54 Use devtool &lt;subcommand&gt; --help to get help on a specific command
55 </literallayout>
56 </para>
57
58 <para>
59 As directed in the general help output, you can get more
60 syntax on a specific command by providing the command
61 name and using <filename>--help</filename>:
62 <literallayout class='monospaced'>
63 $ devtool add --help
64 usage: devtool add [-h] [--same-dir | --no-same-dir] [--fetch URI]
65 [--version VERSION] [--no-git] [--autorev] [--binary]
66 [--also-native] [--src-subdir SUBDIR]
67 [recipename] [srctree] [fetchuri]
68
69 Adds a new recipe to the workspace to build a specified source tree. Can
70 optionally fetch a remote URI and unpack it to create the source tree.
71
72 arguments:
73 recipename Name for new recipe to add (just name - no version,
74 path or extension). If not specified, will attempt to
75 auto-detect it.
76 srctree Path to external source tree. If not specified, a
77 subdirectory of
78 /home/scottrif/poky/build/workspace/sources will be
79 used.
80 fetchuri Fetch the specified URI and extract it to create the
81 source tree
82
83 options:
84 -h, --help show this help message and exit
85 --same-dir, -s Build in same directory as source
86 --no-same-dir Force build in a separate build directory
87 --fetch URI, -f URI Fetch the specified URI and extract it to create the
88 source tree (deprecated - pass as positional argument
89 instead)
90 --version VERSION, -V VERSION
91 Version to use within recipe (PV)
92 --no-git, -g If fetching source, do not set up source tree as a git
93 repository
94 --autorev, -a When fetching from a git repository, set SRCREV in the
95 recipe to a floating revision instead of fixed
96 --binary, -b Treat the source tree as something that should be
97 installed verbatim (no compilation, same directory
98 structure). Useful with binary packages e.g. RPMs.
99 --also-native Also add native variant (i.e. support building recipe
100 for the build host as well as the target machine)
101 --src-subdir SUBDIR Specify subdirectory within source tree to use
102 </literallayout>
103 </para>
104 </section>
105
106 <section id='devtool-the-workspace-layer-structure'>
107 <title>The Workspace Layer Structure</title>
108
109 <para>
110 <filename>devtool</filename> uses a "Workspace" layer
111 in which to accomplish builds.
112 This layer is not specific to any single
113 <filename>devtool</filename> command but is rather a common
114 working area used across the tool.
115 </para>
116
117 <para>
118 The following figure shows the workspace structure:
119 </para>
120
121 <para>
122 <imagedata fileref="figures/build-workspace-directory.png"
123 width="6in" depth="5in" align="left" scale="70" />
124 </para>
125
126 <para>
127 <literallayout class='monospaced'>
128 attic - A directory created if devtool believes it preserve
129 anything when you run "devtool reset". For example, if you
130 run "devtool add", make changes to the recipe, and then
131 run "devtool reset", devtool takes notice that the file has
132 been changed and moves it into the attic should you still
133 want the recipe.
134
135 README - Provides information on what is in workspace layer and how to
136 manage it.
137
138 .devtool_md5 - A checksum file used by devtool.
139
140 appends - A directory that contains *.bbappend files, which point to
141 external source.
142
143 conf - A configuration directory that contains the layer.conf file.
144
145 recipes - A directory containing recipes. This directory contains a
146 folder for each directory added whose name matches that of the
147 added recipe. devtool places the <replaceable>recipe</replaceable>.bb file
148 within that sub-directory.
149
150 sources - A directory containing a working copy of the source files used
151 when building the recipe. This is the default directory used
152 as the location of the source tree when you do not provide a
153 source tree path. This directory contains a folder for each
154 set of source files matched to a corresponding recipe.
155 </literallayout>
156 </para>
157 </section>
158
159 <section id='devtool-adding-a-new-recipe-to-the-workspace'>
160 <title>Adding a New Recipe to the Workspace Layer</title>
161
162 <para>
163 Use the <filename>devtool add</filename> command to add a new recipe
164 to the workspace layer.
165 The recipe you add should not exist -
166 <filename>devtool</filename> creates it for you.
167 The source files the recipe uses should exist in an external
168 area.
169 </para>
170
171 <para>
172 The following example creates and adds a new recipe named
173 <filename>jackson</filename> to a workspace layer the tool creates.
174 The source code built by the recipes resides in
175 <filename>/home/scottrif/sources/jackson</filename>:
176 <literallayout class='monospaced'>
177 $ devtool add jackson /home/scottrif/sources/jackson
178 </literallayout>
179 </para>
180
181 <para>
182 If you add a recipe and the workspace layer does not exist,
183 the command creates the layer and populates it as
184 described in
185 "<link linkend='devtool-the-workspace-layer-structure'>The Workspace Layer Structure</link>"
186 section.
187 </para>
188
189 <para>
190 Running <filename>devtool add</filename> when the
191 workspace layer exists causes the tool to add the recipe,
192 append files, and source files into the existing workspace layer.
193 The <filename>.bbappend</filename> file is created to point
194 to the external source tree.
195 </para>
196 </section>
197
198 <section id='devtool-extracting-the-source-for-an-existing-recipe'>
199 <title>Extracting the Source for an Existing Recipe</title>
200
201 <para>
202 Use the <filename>devtool extract</filename> command to
203 extract the source for an existing recipe.
204 When you use this command, you must supply the root name
205 of the recipe (i.e. no version, paths, or extensions), and
206 you must supply the directory to which you want the source
207 extracted.
208 </para>
209
210 <para>
211 Additional command options let you control the name of a
212 development branch into which you can checkout the source
213 and whether or not to keep a temporary directory, which is
214 useful for debugging.
215 </para>
216 </section>
217
218 <section id='devtool-synchronizing-a-recipes-extracted-source-tree'>
219 <title>Synchronizing a Recipe's Extracted Source Tree</title>
220
221 <para>
222 Use the <filename>devtool sync</filename> command to
223 synchronize a previously extracted source tree for an
224 existing recipe.
225 When you use this command, you must supply the root name
226 of the recipe (i.e. no version, paths, or extensions), and
227 you must supply the directory to which you want the source
228 extracted.
229 </para>
230
231 <para>
232 Additional command options let you control the name of a
233 development branch into which you can checkout the source
234 and whether or not to keep a temporary directory, which is
235 useful for debugging.
236 </para>
237 </section>
238
239 <section id='devtool-modifying-a-recipe'>
240 <title>Modifying an Existing Recipe</title>
241
242 <para>
243 Use the <filename>devtool modify</filename> command to begin
244 modifying the source of an existing recipe.
245 This command is very similar to the
246 <ulink url='&YOCTO_DOCS_DEV_URL;#devtool-adding-a-new-recipe-to-the-workspace'><filename>add</filename></ulink>
247 command except that it does not physically create the
248 recipe in the workspace layer because the recipe already
249 exists in an another layer.
250 </para>
251
252 <para>
253 The <filename>devtool modify</filename> command extracts the
254 source for a recipe, sets it up as a Git repository if the
255 source had not already been fetched from Git, checks out a
256 branch for development, and applies any patches from the recipe
257 as commits on top.
258 You can use the following command to checkout the source
259 files:
260 <literallayout class='monospaced'>
261 $ devtool modify <replaceable>recipe</replaceable>
262 </literallayout>
263 Using the above command form, <filename>devtool</filename> uses
264 the existing recipe's
265 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
266 statement to locate the upstream source, extracts the source
267 into the default sources location in the workspace.
268 The default development branch used is "devtool".
269 </para>
270 </section>
271
272 <section id='devtool-edit-an-existing-recipe'>
273 <title>Edit an Existing Recipe</title>
274
275 <para>
276 Use the <filename>devtool edit-recipe</filename> command
277 to run the default editor, which is identified using the
278 <filename>EDITOR</filename> variable, on the specified recipe.
279 </para>
280
281 <para>
282 When you use the <filename>devtool edit-recipe</filename>
283 command, you must supply the root name of the recipe
284 (i.e. no version, paths, or extensions).
285 Also, the recipe file itself must reside in the workspace
286 as a result of the <filename>devtool add</filename> or
287 <filename>devtool upgrade</filename> commands.
288 However, you can override that requirement by using the
289 "-a" or "--any-recipe" option.
290 Using either of these options allows you to edit any recipe
291 regardless of its location.
292 </para>
293 </section>
294
295 <section id='devtool-updating-a-recipe'>
296 <title>Updating a Recipe</title>
297
298 <para>
299 Use the <filename>devtool update-recipe</filename> command to
300 update your recipe with patches that reflect changes you make
301 to the source files.
302 For example, if you know you are going to work on some
303 code, you could first use the
304 <ulink url='&YOCTO_DOCS_DEV_URL;#devtool-modifying-a-recipe'><filename>devtool modify</filename></ulink>
305 command to extract the code and set up the workspace.
306 After which, you could modify, compile, and test the code.
307 </para>
308
309 <para>
310 When you are satisfied with the results and you have committed
311 your changes to the Git repository, you can then
312 run the <filename>devtool update-recipe</filename> to create the
313 patches and update the recipe:
314 <literallayout class='monospaced'>
315 $ devtool update-recipe <replaceable>recipe</replaceable>
316 </literallayout>
317 If you run the <filename>devtool update-recipe</filename>
318 without committing your changes, the command ignores the
319 changes.
320 </para>
321
322 <para>
323 Often, you might want to apply customizations made to your
324 software in your own layer rather than apply them to the
325 original recipe.
326 If so, you can use the
327 <filename>-a</filename> or <filename>--append</filename>
328 option with the <filename>devtool update-recipe</filename>
329 command.
330 These options allow you to specify the layer into which to
331 write an append file:
332 <literallayout class='monospaced'>
333 $ devtool update-recipe <replaceable>recipe</replaceable> -a <replaceable>base-layer-directory</replaceable>
334 </literallayout>
335 The <filename>*.bbappend</filename> file is created at the
336 appropriate path within the specified layer directory, which
337 may or may not be in your <filename>bblayers.conf</filename>
338 file.
339 If an append file already exists, the command updates it
340 appropriately.
341 </para>
342 </section>
343
344 <section id='devtool-upgrading-a-recipe'>
345 <title>Upgrading a Recipe</title>
346
347 <para>
348 Use the <filename>devtool upgrade</filename> command
349 to upgrade an existing recipe to a new upstream version.
350 The command puts the upgraded recipe file into the
351 workspace along with any associated files, and extracts
352 the source tree to a specified location should patches
353 need rebased or added to as a result of the upgrade.
354 </para>
355
356 <para>
357 When you use the <filename>devtool upgrade</filename> command,
358 you must supply the root name of the recipe (i.e. no version,
359 paths, or extensions), and you must supply the directory
360 to which you want the source extracted.
361 Additional command options let you control things such as
362 the version number to which you want to upgrade (i.e. the
363 <link linkend='var-PV'><filename>PV</filename></link>),
364 the source revision to which you want to upgrade (i.e. the
365 <link linkend='var-SRCREV'><filename>SRCREV</filename></link>,
366 whether or not to apply patches, and so forth.
367 </para>
368 </section>
369
370 <section id='devtool-resetting-a-recipe'>
371 <title>Resetting a Recipe</title>
372
373 <para>
374 Use the <filename>devtool reset</filename> command to remove a
375 recipe and its configuration (e.g. the corresponding
376 <filename>.bbappend</filename> file) from the workspace layer.
377 Realize that this command deletes the recipe and the
378 append file.
379 The command does not physically move them for you.
380 Consequently, you must be sure to physically relocate your
381 updated recipe and the append file outside of the workspace
382 layer before running the <filename>devtool reset</filename>
383 command.
384 </para>
385
386 <para>
387 If the <filename>devtool reset</filename> command detects that
388 the recipe or the append files have been modified, the
389 command preserves the modified files in a separate "attic"
390 subdirectory under the workspace layer.
391 </para>
392
393 <para>
394 Here is an example that resets the workspace directory that
395 contains the <filename>mtr</filename> recipe:
396 <literallayout class='monospaced'>
397 $ devtool reset mtr
398 NOTE: Cleaning sysroot for recipe mtr...
399 NOTE: Leaving source tree /home/scottrif/poky/build/workspace/sources/mtr as-is; if you no
400 longer need it then please delete it manually
401 $
402 </literallayout>
403 </para>
404 </section>
405
406 <section id='devtool-building-your-recipe'>
407 <title>Building Your Recipe</title>
408
409 <para>
410 Use the <filename>devtool build</filename> command to cause the
411 OpenEmbedded build system to build your recipe.
412 The <filename>devtool build</filename> command is equivalent to
413 <filename>bitbake -c populate_sysroot</filename>.
414 </para>
415
416 <para>
417 When you use the <filename>devtool build</filename> command,
418 you must supply the root name of the recipe (i.e. no version,
419 paths, or extensions).
420 You can use either the "-s" or the "--disable-parallel-make"
421 option to disable parallel makes during the build.
422 Here is an example:
423 <literallayout class='monospaced'>
424 $ devtool build <replaceable>recipe</replaceable>
425 </literallayout>
426 </para>
427 </section>
428
429 <section id='devtool-building-your-image'>
430 <title>Building Your Image</title>
431
432 <para>
433 Use the <filename>devtool build-image</filename> command
434 to build an image, extending it to include packages from
435 recipes in the workspace.
436 Using this command is useful when you want an image that
437 ready for immediate deployment onto a device for testing.
438 For proper integration into a final image, you need to
439 edit your custom image recipe appropriately.
440 </para>
441
442 <para>
443 When you use the <filename>devtool build-image</filename>
444 command, you must supply the name of the image.
445 This command has no command line options:
446 <literallayout class='monospaced'>
447 $ devtool build-image <replaceable>image</replaceable>
448 </literallayout>
449 </para>
450 </section>
451
452 <section id='devtool-deploying-your-software-on-the-target-machine'>
453 <title>Deploying Your Software on the Target Machine</title>
454
455 <para>
456 Use the <filename>devtool deploy-target</filename> command to
457 deploy the recipe's build output to the live target machine:
458 <literallayout class='monospaced'>
459 $ devtool deploy-target <replaceable>recipe</replaceable>&nbsp;<replaceable>target</replaceable>
460 </literallayout>
461 The <replaceable>target</replaceable> is the address of the
462 target machine, which must be running an SSH server (i.e.
463 <filename>user@hostname[:destdir]</filename>).
464 </para>
465
466 <para>
467 This command deploys all files installed during the
468 <link linkend='ref-tasks-install'><filename>do_install</filename></link>
469 task.
470 Furthermore, you do not need to have package management enabled
471 within the target machine.
472 If you do, the package manager is bypassed.
473 <note><title>Notes</title>
474 <para>
475 The <filename>deploy-target</filename>
476 functionality is for development only.
477 You should never use it to update an image that will be
478 used in production.
479 </para>
480 </note>
481 </para>
482 </section>
483
484 <section id='devtool-removing-your-software-from-the-target-machine'>
485 <title>Removing Your Software from the Target Machine</title>
486
487 <para>
488 Use the <filename>devtool undeploy-target</filename> command to
489 remove deployed build output from the target machine.
490 For the <filename>devtool undeploy-target</filename> command to
491 work, you must have previously used the
492 <ulink url='&YOCTO_DOCS_DEV_URL;#devtool-deploying-your-software-on-the-target-machine'><filename>devtool deploy-target</filename></ulink>
493 command.
494 <literallayout class='monospaced'>
495 $ devtool undeploy-target <replaceable>recipe</replaceable>&nbsp;<replaceable>target</replaceable>
496 </literallayout>
497 The <replaceable>target</replaceable> is the address of the
498 target machine, which must be running an SSH server (i.e.
499 <filename>user@hostname</filename>).
500 </para>
501 </section>
502
503 <section id='devtool-creating-the-workspace'>
504 <title>Creating the Workspace Layer in an Alternative Location</title>
505
506 <para>
507 Use the <filename>devtool create-workspace</filename> command to
508 create a new workspace layer in your
509 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
510 When you create a new workspace layer, it is populated with the
511 <filename>README</filename> file and the
512 <filename>conf</filename> directory only.
513 </para>
514
515 <para>
516 The following example creates a new workspace layer in your
517 current working and by default names the workspace layer
518 "workspace":
519 <literallayout class='monospaced'>
520 $ devtool create-workspace
521 </literallayout>
522 </para>
523
524 <para>
525 You can create a workspace layer anywhere by supplying
526 a pathname with the command.
527 The following command creates a new workspace layer named
528 "new-workspace":
529 <literallayout class='monospaced'>
530 $ devtool create-workspace /home/scottrif/new-workspace
531 </literallayout>
532 </para>
533 </section>
534
535 <section id='devtool-get-the-status-of-the-recipes-in-your-workspace'>
536 <title>Get the Status of the Recipes in Your Workspace</title>
537
538 <para>
539 Use the <filename>devtool status</filename> command to
540 list the recipes currently in your workspace.
541 Information includes the paths to their respective
542 external source trees.
543 </para>
544
545 <para>
546 The <filename>devtool status</filename> command has no
547 command-line options:
548 <literallayout class='monospaced'>
549 devtool status
550 </literallayout>
551 Following is sample output after using
552 <ulink url='&YOCTO_DOCS_DEV_URL;#devtool-adding-a-new-recipe-to-the-workspace'><filename>devtool add</filename></ulink>
553 to create and add the <filename>mtr_0.86.bb</filename> recipe
554 to the <filename>workspace</filename> directory:
555 <literallayout class='monospaced'>
556 $ devtool status
557 mtr: /home/scottrif/poky/build/workspace/sources/mtr (/home/scottrif/poky/build/workspace/recipes/mtr/mtr_0.86.bb)
558 $
559 </literallayout>
560 </para>
561 </section>
562
563 <section id='devtool-search-for-available-target-recipes'>
564 <title>Search for Available Target Recipes</title>
565
566 <para>
567 Use the <filename>devtool search</filename> command to
568 search for available target recipes.
569 The command matches the recipe name, package name,
570 description, and installed files.
571 The command displays the recipe name as a result of a
572 match.
573 </para>
574
575 <para>
576 When you use the <filename>devtool search</filename> command,
577 you must supply a <replaceable>keyword</replaceable>.
578 The command uses the <replaceable>keyword</replaceable> when
579 searching for a match.
580 </para>
581 </section>
582</chapter>
583<!--
584vim: expandtab tw=80 ts=4
585-->
diff --git a/documentation/ref-manual/ref-manual.xml b/documentation/ref-manual/ref-manual.xml
index d375157b73..1aca3898e5 100644
--- a/documentation/ref-manual/ref-manual.xml
+++ b/documentation/ref-manual/ref-manual.xml
@@ -145,6 +145,8 @@
145 145
146 <xi:include href="ref-tasks.xml"/> 146 <xi:include href="ref-tasks.xml"/>
147 147
148 <xi:include href="ref-devtool-reference.xml"/>
149
148 <xi:include href="ref-qa-checks.xml"/> 150 <xi:include href="ref-qa-checks.xml"/>
149 151
150 <xi:include href="ref-images.xml"/> 152 <xi:include href="ref-images.xml"/>
diff --git a/documentation/sdk-manual/sdk-extensible.xml b/documentation/sdk-manual/sdk-extensible.xml
index 67df1b0975..73b317f5c8 100644
--- a/documentation/sdk-manual/sdk-extensible.xml
+++ b/documentation/sdk-manual/sdk-extensible.xml
@@ -129,6 +129,12 @@
129 number of sub-commands for each function. 129 number of sub-commands for each function.
130 You can run <filename>devtool --help</filename> to see all the 130 You can run <filename>devtool --help</filename> to see all the
131 commands. 131 commands.
132 <note>
133 See the
134 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-devtool-reference'><filename>devtool</filename>&nbsp;Quick Reference</ulink>"
135 in the Yocto Project Reference Manual for more a
136 <filename>devtool</filename> reference.
137 </note>
132 </para> 138 </para>
133 139
134 <para> 140 <para>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-05-10 20:22:41 +0000