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.xml593
-rw-r--r--documentation/dev-manual/figures/build-workspace-directory.pngbin29627 -> 0 bytes
2 files changed, 6 insertions, 587 deletions
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/dev-manual/figures/build-workspace-directory.png b/documentation/dev-manual/figures/build-workspace-directory.png
deleted file mode 100644
index 5387d33f03..0000000000
--- a/documentation/dev-manual/figures/build-workspace-directory.png
+++ /dev/null
Binary files differ
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-12 01:18:54 +0000