summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual/dev-manual-model.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/dev-manual/dev-manual-model.xml')
-rw-r--r--documentation/dev-manual/dev-manual-model.xml161
1 files changed, 76 insertions, 85 deletions
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
index ff44a3f68b..dcff37e981 100644
--- a/documentation/dev-manual/dev-manual-model.xml
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -649,13 +649,13 @@
649 </para> 649 </para>
650 650
651 <section id='use-devtool-to-integrate-new-code'> 651 <section id='use-devtool-to-integrate-new-code'>
652 <title>Use <filename>devtool add</filename> to Integrate New Code</title> 652 <title>Use <filename>devtool add</filename> to Add an Application</title>
653 653
654 <para> 654 <para>
655 The <filename>devtool add</filename> command generates 655 The <filename>devtool add</filename> command generates
656 a new recipe based on existing source code. 656 a new recipe based on existing source code.
657 This command takes advantage of the 657 This command takes advantage of the
658 <link linkend='devtool-the-workspace-layer-structure'>workspace</link> 658 <ulink url='&YOCTO_DOCS_DEV_URL;#devtool-the-workspace-layer-structure'>workspace</ulink>
659 layer that many <filename>devtool</filename> commands 659 layer that many <filename>devtool</filename> commands
660 use. 660 use.
661 The command is flexible enough to allow you to extract source 661 The command is flexible enough to allow you to extract source
@@ -721,7 +721,8 @@
721 and needs to be extracted to some 721 and needs to be extracted to some
722 local area - this time outside of the default 722 local area - this time outside of the default
723 workspace. 723 workspace.
724 As always, if required <filename>devtool</filename> creates 724 If required, <filename>devtool</filename>
725 always creates
725 a Git repository locally during the extraction. 726 a Git repository locally during the extraction.
726 Furthermore, the first positional argument 727 Furthermore, the first positional argument
727 <replaceable>srctree</replaceable> in this case 728 <replaceable>srctree</replaceable> in this case
@@ -788,10 +789,6 @@
788 <para>If you need to take the build output and eventually 789 <para>If you need to take the build output and eventually
789 move it to the target hardware, you would use 790 move it to the target hardware, you would use
790 <filename>devtool build</filename>: 791 <filename>devtool build</filename>:
791 <note>
792 You could use <filename>bitbake</filename> to build
793 the recipe as well.
794 </note>
795 <literallayout class='monospaced'> 792 <literallayout class='monospaced'>
796 $ devtool build <replaceable>recipe</replaceable> 793 $ devtool build <replaceable>recipe</replaceable>
797 </literallayout></para> 794 </literallayout></para>
@@ -831,49 +828,44 @@
831 However, <filename>devtool</filename> does not provide a 828 However, <filename>devtool</filename> does not provide a
832 specific command that allows you to do this. 829 specific command that allows you to do this.
833 </para></listitem> 830 </para></listitem>
834 <listitem><para><emphasis>Optionally Update the Recipe With Patch Files</emphasis>: 831 <listitem><para>
835 Once you are satisfied with the recipe, if you have made 832 <emphasis>Finish Your Work With the Recipe</emphasis>:
836 any changes to the source tree that you want to have 833 The <filename>devtool finish</filename> command creates
837 applied by the recipe, you need to generate patches 834 any patches corresponding to commits in the local
838 from those changes. 835 Git repository, moves the new recipe to a more permanent
839 You do this before moving the recipe 836 layer, and then resets the recipe so that the recipe is
840 to its final layer and cleaning up the workspace area 837 built normally rather than from the workspace.
841 <filename>devtool</filename> uses. 838 <literallayout class='monospaced'>
842 This optional step is especially relevant if you are 839 $ devtool finish <replaceable>recipe layer</replaceable>
843 using or adding third-party software.</para> 840 </literallayout>
844 <para>To convert commits created using Git to patch files,
845 use the <filename>devtool update-recipe</filename> command.
846 <note> 841 <note>
847 Any changes you want to turn into patches must be 842 Any changes you want to turn into patches must be
848 committed to the Git repository in the source tree. 843 committed to the Git repository in the source tree.
844 </note></para>
845
846 <para>As mentioned, the <filename>devtool finish</filename>
847 command moves the final recipe to its permanent layer.
848 </para>
849
850 <para>As a final process of the
851 <filename>devtool finish</filename> command, the state
852 of the standard layers and the upstream source is
853 restored so that you can build the recipe from those
854 areas rather than the workspace.
855 <note>
856 You can use the <filename>devtool reset</filename>
857 command to put things back should you decide you
858 do not want to proceed with your work.
859 If you do use this command, realize that the source
860 tree is preserved.
849 </note> 861 </note>
850 <literallayout class='monospaced'>
851 $ devtool update-recipe <replaceable>recipe</replaceable>
852 </literallayout>
853 </para></listitem>
854 <listitem><para><emphasis>Move the Recipe to its Permanent Layer</emphasis>:
855 Before cleaning up the workspace, you need to move the
856 final recipe to its permanent layer.
857 You must do this before using the
858 <filename>devtool reset</filename> command if you want to
859 retain the recipe.
860 </para></listitem>
861 <listitem><para><emphasis>Reset the Recipe</emphasis>:
862 As a final step, you can restore the state such that
863 standard layers and the upstream source is used to build
864 the recipe rather than data in the workspace.
865 To reset the recipe, use the <filename>devtool reset</filename>
866 command:
867 <literallayout class='monospaced'>
868 $ devtool reset <replaceable>recipe</replaceable>
869 </literallayout>
870 </para></listitem> 862 </para></listitem>
871 </orderedlist> 863 </orderedlist>
872 </para> 864 </para>
873 </section> 865 </section>
874 866
875 <section id='devtool-use-devtool-modify-to-enable-work-on-code-associated-with-an-existing-recipe'> 867 <section id='devtool-use-devtool-modify-to-enable-work-on-code-associated-with-an-existing-recipe'>
876 <title>Use <filename>devtool modify</filename> to Enable Work on Code Associated with an Existing Recipe</title> 868 <title>Use <filename>devtool modify</filename> to Modify the Source of an Existing Component</title>
877 869
878 <para> 870 <para>
879 The <filename>devtool modify</filename> command prepares the 871 The <filename>devtool modify</filename> command prepares the
@@ -1028,17 +1020,12 @@
1028 <listitem><para><emphasis>Build the Recipe</emphasis>: 1020 <listitem><para><emphasis>Build the Recipe</emphasis>:
1029 Once you have updated the source files, you can build 1021 Once you have updated the source files, you can build
1030 the recipe. 1022 the recipe.
1031 You can either use <filename>devtool build</filename> or
1032 <filename>bitbake</filename>.
1033 Either method produces build output that is stored
1034 in
1035 <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>.
1036 </para></listitem> 1023 </para></listitem>
1037 <listitem><para><emphasis>Deploy the Build Output</emphasis>: 1024 <listitem><para><emphasis>Deploy the Build Output</emphasis>:
1038 When you use the <filename>devtool build</filename> 1025 When you use the <filename>devtool build</filename>
1039 command or <filename>bitbake</filename> to build out your 1026 command to build out your recipe, you probably want to see
1040 recipe, you probably want to see if the resulting build 1027 if the resulting build output works as expected on target
1041 output works as expected on target hardware. 1028 hardware.
1042 <note> 1029 <note>
1043 This step assumes you have a previously built 1030 This step assumes you have a previously built
1044 image that is already either running in QEMU or 1031 image that is already either running in QEMU or
@@ -1062,42 +1049,43 @@
1062 However, <filename>devtool</filename> does not provide a 1049 However, <filename>devtool</filename> does not provide a
1063 specific command that allows you to do this. 1050 specific command that allows you to do this.
1064 </para></listitem> 1051 </para></listitem>
1065 <listitem><para><emphasis>Optionally Create Patch Files for Your Changes</emphasis>: 1052 <listitem><para>
1066 After you have debugged your changes, you can 1053 <emphasis>Finish Your Work With the Recipe</emphasis>:
1067 use <filename>devtool update-recipe</filename> to 1054 The <filename>devtool finish</filename> command creates
1068 generate patch files for all the commits you have 1055 any patches corresponding to commits in the local
1069 made. 1056 Git repository, updates the recipe to point to them
1070 <note> 1057 (or creates a <filename>.bbappend</filename> file to do
1071 Patch files are generated only for changes 1058 so, depending on the specified destination layer), and
1072 you have committed. 1059 then resets the recipe so that the recipe is built normally
1073 </note> 1060 rather than from the workspace.
1074 <literallayout class='monospaced'> 1061 <literallayout class='monospaced'>
1075 $ devtool update-recipe <replaceable>recipe</replaceable> 1062 $ devtool finish <replaceable>recipe layer</replaceable>
1076 </literallayout> 1063 </literallayout>
1077 By default, the
1078 <filename>devtool update-recipe</filename> command
1079 creates the patch files in a folder named the same
1080 as the recipe beneath the folder in which the recipe
1081 resides, and updates the recipe's
1082 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
1083 statement to point to the generated patch files.
1084 <note> 1064 <note>
1085 You can use the 1065 Any changes you want to turn into patches must be
1086 "--append <replaceable>LAYERDIR</replaceable>" 1066 committed to the Git repository in the source tree.
1087 option to cause the command to create append files 1067 </note></para>
1088 in a specific layer rather than the default 1068
1089 recipe layer. 1069 <para>Because there is no need to move the recipe,
1070 <filename>devtool finish</filename> either updates the
1071 original recipe in the original layer or the command
1072 creates a <filename>.bbappend</filename> in a different
1073 layer as provided by <replaceable>layer</replaceable>.
1074 </para>
1075
1076 <para>As a final process of the
1077 <filename>devtool finish</filename> command, the state
1078 of the standard layers and the upstream source is
1079 restored so that you can build the recipe from those
1080 areas rather than the workspace.
1081 <note>
1082 You can use the <filename>devtool reset</filename>
1083 command to put things back should you decide you
1084 do not want to proceed with your work.
1085 If you do use this command, realize that the source
1086 tree is preserved.
1090 </note> 1087 </note>
1091 </para></listitem> 1088 </para></listitem>
1092 <listitem><para><emphasis>Restore the Workspace</emphasis>:
1093 The <filename>devtool reset</filename> restores the
1094 state so that standard layers and upstream sources are
1095 used to build the recipe rather than what is in the
1096 workspace.
1097 <literallayout class='monospaced'>
1098 $ devtool reset <replaceable>recipe</replaceable>
1099 </literallayout>
1100 </para></listitem>
1101 </orderedlist> 1089 </orderedlist>
1102 </para> 1090 </para>
1103 </section> 1091 </section>
@@ -1297,7 +1285,7 @@
1297 1285
1298 OpenEmbedded development tool 1286 OpenEmbedded development tool
1299 1287
1300 optional arguments: 1288 options:
1301 --basepath BASEPATH Base directory of SDK / build directory 1289 --basepath BASEPATH Base directory of SDK / build directory
1302 --bbpath BBPATH Explicitly specify the BBPATH, rather than getting it 1290 --bbpath BBPATH Explicitly specify the BBPATH, rather than getting it
1303 from the metadata 1291 from the metadata
@@ -1315,11 +1303,12 @@
1315 status Show workspace status 1303 status Show workspace status
1316 search Search available recipes 1304 search Search available recipes
1317 Working on a recipe in the workspace: 1305 Working on a recipe in the workspace:
1318 build Build a recipe
1319 edit-recipe Edit a recipe file in your workspace 1306 edit-recipe Edit a recipe file in your workspace
1320 configure-help Get help on configure script options 1307 configure-help Get help on configure script options
1308 build Build a recipe
1321 update-recipe Apply changes from external source tree to recipe 1309 update-recipe Apply changes from external source tree to recipe
1322 reset Remove a recipe from your workspace 1310 reset Remove a recipe from your workspace
1311 finish Finish working on a recipe in your workspace
1323 Testing changes on target: 1312 Testing changes on target:
1324 deploy-target Deploy recipe output files to live target machine 1313 deploy-target Deploy recipe output files to live target machine
1325 undeploy-target Undeploy recipe output files in live target machine 1314 undeploy-target Undeploy recipe output files in live target machine
@@ -1339,14 +1328,14 @@
1339 <literallayout class='monospaced'> 1328 <literallayout class='monospaced'>
1340 $ devtool add --help 1329 $ devtool add --help
1341 usage: devtool add [-h] [--same-dir | --no-same-dir] [--fetch URI] 1330 usage: devtool add [-h] [--same-dir | --no-same-dir] [--fetch URI]
1342 [--version VERSION] [--no-git] [--binary] [--also-native] 1331 [--version VERSION] [--no-git] [--autorev] [--binary]
1343 [--src-subdir SUBDIR] 1332 [--also-native] [--src-subdir SUBDIR]
1344 [recipename] [srctree] [fetchuri] 1333 [recipename] [srctree] [fetchuri]
1345 1334
1346 Adds a new recipe to the workspace to build a specified source tree. Can 1335 Adds a new recipe to the workspace to build a specified source tree. Can
1347 optionally fetch a remote URI and unpack it to create the source tree. 1336 optionally fetch a remote URI and unpack it to create the source tree.
1348 1337
1349 positional arguments: 1338 arguments:
1350 recipename Name for new recipe to add (just name - no version, 1339 recipename Name for new recipe to add (just name - no version,
1351 path or extension). If not specified, will attempt to 1340 path or extension). If not specified, will attempt to
1352 auto-detect it. 1341 auto-detect it.
@@ -1357,7 +1346,7 @@
1357 fetchuri Fetch the specified URI and extract it to create the 1346 fetchuri Fetch the specified URI and extract it to create the
1358 source tree 1347 source tree
1359 1348
1360 optional arguments: 1349 options:
1361 -h, --help show this help message and exit 1350 -h, --help show this help message and exit
1362 --same-dir, -s Build in same directory as source 1351 --same-dir, -s Build in same directory as source
1363 --no-same-dir Force build in a separate build directory 1352 --no-same-dir Force build in a separate build directory
@@ -1368,6 +1357,8 @@
1368 Version to use within recipe (PV) 1357 Version to use within recipe (PV)
1369 --no-git, -g If fetching source, do not set up source tree as a git 1358 --no-git, -g If fetching source, do not set up source tree as a git
1370 repository 1359 repository
1360 --autorev, -a When fetching from a git repository, set SRCREV in the
1361 recipe to a floating revision instead of fixed
1371 --binary, -b Treat the source tree as something that should be 1362 --binary, -b Treat the source tree as something that should be
1372 installed verbatim (no compilation, same directory 1363 installed verbatim (no compilation, same directory
1373 structure). Useful with binary packages e.g. RPMs. 1364 structure). Useful with binary packages e.g. RPMs.