From 5ec03cd359332d87f2fd4f4542a58dea1600ec96 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Fri, 16 Sep 2016 09:49:24 -0700 Subject: dev-manual: Updated add and modify flows and text. Updated the devtool add and devtool modify flow diagrams and supporting text to exactly match those from the SDK manual. Also, updated the help output generated from the devtool --help and devtool add --help commands. (From yocto-docs rev: 002297a8ed3979f012fe228b7edb77514e7528a2) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/dev-manual/dev-manual-model.xml | 161 ++++++++++----------- .../dev-manual/figures/devtool-add-flow.png | Bin 179361 -> 177945 bytes .../dev-manual/figures/devtool-modify-flow.png | Bin 152662 -> 164192 bytes 3 files changed, 76 insertions(+), 85 deletions(-) (limited to 'documentation/dev-manual') 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 @@
- Use <filename>devtool add</filename> to Integrate New Code + Use <filename>devtool add</filename> to Add an Application The devtool add command generates a new recipe based on existing source code. This command takes advantage of the - workspace + workspace layer that many devtool commands use. The command is flexible enough to allow you to extract source @@ -721,7 +721,8 @@ and needs to be extracted to some local area - this time outside of the default workspace. - As always, if required devtool creates + If required, devtool + always creates a Git repository locally during the extraction. Furthermore, the first positional argument srctree in this case @@ -788,10 +789,6 @@ If you need to take the build output and eventually move it to the target hardware, you would use devtool build: - - You could use bitbake to build - the recipe as well. - $ devtool build recipe @@ -831,49 +828,44 @@ However, devtool does not provide a specific command that allows you to do this. - Optionally Update the Recipe With Patch Files: - Once you are satisfied with the recipe, if you have made - any changes to the source tree that you want to have - applied by the recipe, you need to generate patches - from those changes. - You do this before moving the recipe - to its final layer and cleaning up the workspace area - devtool uses. - This optional step is especially relevant if you are - using or adding third-party software. - To convert commits created using Git to patch files, - use the devtool update-recipe command. + + Finish Your Work With the Recipe: + The devtool finish command creates + any patches corresponding to commits in the local + Git repository, moves the new recipe to a more permanent + layer, and then resets the recipe so that the recipe is + built normally rather than from the workspace. + + $ devtool finish recipe layer + Any changes you want to turn into patches must be committed to the Git repository in the source tree. + + + As mentioned, the devtool finish + command moves the final recipe to its permanent layer. + + + As a final process of the + devtool finish command, the state + of the standard layers and the upstream source is + restored so that you can build the recipe from those + areas rather than the workspace. + + You can use the devtool reset + command to put things back should you decide you + do not want to proceed with your work. + If you do use this command, realize that the source + tree is preserved. - - $ devtool update-recipe recipe - - - Move the Recipe to its Permanent Layer: - Before cleaning up the workspace, you need to move the - final recipe to its permanent layer. - You must do this before using the - devtool reset command if you want to - retain the recipe. - - Reset the Recipe: - As a final step, you can restore the state such that - standard layers and the upstream source is used to build - the recipe rather than data in the workspace. - To reset the recipe, use the devtool reset - command: - - $ devtool reset recipe -
- Use <filename>devtool modify</filename> to Enable Work on Code Associated with an Existing Recipe + Use <filename>devtool modify</filename> to Modify the Source of an Existing Component The devtool modify command prepares the @@ -1028,17 +1020,12 @@ Build the Recipe: Once you have updated the source files, you can build the recipe. - You can either use devtool build or - bitbake. - Either method produces build output that is stored - in - TMPDIR. Deploy the Build Output: When you use the devtool build - command or bitbake to build out your - recipe, you probably want to see if the resulting build - output works as expected on target hardware. + command to build out your recipe, you probably want to see + if the resulting build output works as expected on target + hardware. This step assumes you have a previously built image that is already either running in QEMU or @@ -1062,42 +1049,43 @@ However, devtool does not provide a specific command that allows you to do this. - Optionally Create Patch Files for Your Changes: - After you have debugged your changes, you can - use devtool update-recipe to - generate patch files for all the commits you have - made. - - Patch files are generated only for changes - you have committed. - + + Finish Your Work With the Recipe: + The devtool finish command creates + any patches corresponding to commits in the local + Git repository, updates the recipe to point to them + (or creates a .bbappend file to do + so, depending on the specified destination layer), and + then resets the recipe so that the recipe is built normally + rather than from the workspace. - $ devtool update-recipe recipe + $ devtool finish recipe layer - By default, the - devtool update-recipe command - creates the patch files in a folder named the same - as the recipe beneath the folder in which the recipe - resides, and updates the recipe's - SRC_URI - statement to point to the generated patch files. - You can use the - "--append LAYERDIR" - option to cause the command to create append files - in a specific layer rather than the default - recipe layer. + Any changes you want to turn into patches must be + committed to the Git repository in the source tree. + + + Because there is no need to move the recipe, + devtool finish either updates the + original recipe in the original layer or the command + creates a .bbappend in a different + layer as provided by layer. + + + As a final process of the + devtool finish command, the state + of the standard layers and the upstream source is + restored so that you can build the recipe from those + areas rather than the workspace. + + You can use the devtool reset + command to put things back should you decide you + do not want to proceed with your work. + If you do use this command, realize that the source + tree is preserved. - Restore the Workspace: - The devtool reset restores the - state so that standard layers and upstream sources are - used to build the recipe rather than what is in the - workspace. - - $ devtool reset recipe - -
@@ -1297,7 +1285,7 @@ OpenEmbedded development tool - optional arguments: + options: --basepath BASEPATH Base directory of SDK / build directory --bbpath BBPATH Explicitly specify the BBPATH, rather than getting it from the metadata @@ -1315,11 +1303,12 @@ status Show workspace status search Search available recipes Working on a recipe in the workspace: - build Build a recipe edit-recipe Edit a recipe file in your workspace configure-help Get help on configure script options + build Build a recipe update-recipe Apply changes from external source tree to recipe reset Remove a recipe from your workspace + finish Finish working on a recipe in your workspace Testing changes on target: deploy-target Deploy recipe output files to live target machine undeploy-target Undeploy recipe output files in live target machine @@ -1339,14 +1328,14 @@ $ devtool add --help usage: devtool add [-h] [--same-dir | --no-same-dir] [--fetch URI] - [--version VERSION] [--no-git] [--binary] [--also-native] - [--src-subdir SUBDIR] + [--version VERSION] [--no-git] [--autorev] [--binary] + [--also-native] [--src-subdir SUBDIR] [recipename] [srctree] [fetchuri] Adds a new recipe to the workspace to build a specified source tree. Can optionally fetch a remote URI and unpack it to create the source tree. - positional arguments: + arguments: recipename Name for new recipe to add (just name - no version, path or extension). If not specified, will attempt to auto-detect it. @@ -1357,7 +1346,7 @@ fetchuri Fetch the specified URI and extract it to create the source tree - optional arguments: + options: -h, --help show this help message and exit --same-dir, -s Build in same directory as source --no-same-dir Force build in a separate build directory @@ -1368,6 +1357,8 @@ Version to use within recipe (PV) --no-git, -g If fetching source, do not set up source tree as a git repository + --autorev, -a When fetching from a git repository, set SRCREV in the + recipe to a floating revision instead of fixed --binary, -b Treat the source tree as something that should be installed verbatim (no compilation, same directory structure). Useful with binary packages e.g. RPMs. diff --git a/documentation/dev-manual/figures/devtool-add-flow.png b/documentation/dev-manual/figures/devtool-add-flow.png index c09e60e355..985ac331f1 100644 Binary files a/documentation/dev-manual/figures/devtool-add-flow.png and b/documentation/dev-manual/figures/devtool-add-flow.png differ diff --git a/documentation/dev-manual/figures/devtool-modify-flow.png b/documentation/dev-manual/figures/devtool-modify-flow.png index cd7f4d05b1..fd684ffbe9 100644 Binary files a/documentation/dev-manual/figures/devtool-modify-flow.png and b/documentation/dev-manual/figures/devtool-modify-flow.png differ -- cgit v1.2.3-54-g00ecf