From 70c7e36cb422f358f8eb738d2c74e14d83a82208 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Mon, 22 Feb 2016 21:51:35 -0800 Subject: dev-manual: Created devtool upgrade section. Created the new section for the devtool upgrade flow. (From yocto-docs rev: f3a7f78305ce5045604d9892e18b31b7eabcba62) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/dev-manual/dev-manual-model.xml | 212 +++++++++++++++++++++++--- 1 file changed, 190 insertions(+), 22 deletions(-) (limited to 'documentation/dev-manual/dev-manual-model.xml') diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml index d71021da36..ff74063fc3 100644 --- a/documentation/dev-manual/dev-manual-model.xml +++ b/documentation/dev-manual/dev-manual-model.xml @@ -6,10 +6,6 @@ Common Development Models - - Test paragraph. - - Many development models exist for which you can use the Yocto Project. This chapter overviews simple methods that use tools provided by the @@ -2213,6 +2209,175 @@ used to build the recipe rather than what is in the workspace. + $ devtool reset recipe + + + + + + +
+ Use <filename>devtool upgrade</filename> to Create a Version of the Recipe that Supports a Newer Version of the Software + + + The devtool upgrade command updates + an existing recipe so that you can build it for an updated + set of source files. + The command is flexible enough to allow you to specify + source code revision and versioning schemes, extract code into + or out of the devtool workspace, and + work with any source file forms that the fetchers support. + + + + Depending on your particular scenario, the arguments and options + you use with devtool upgrade form different + combinations. + The following diagram shows a common development flow + you would use with the devtool modify + command: + + + + + + + + + Initiate the Upgrade: + The top part of the flow shows a typical scenario by which + you could use devtool upgrade. + The following conditions exist: + + The recipe exists in some layer external + to the devtool workspace. + + The source files for the new release + exist adjacent to the same location pointed to by + SRC_URI + in the recipe (e.g. a tarball with the new version + number in the name, or as a different revision in + the upstream Git repository). + + + A common situation is where third-party software has + undergone a revision so that it has been upgraded. + The recipe you have access to is likely in your own layer. + Thus, you need to upgrade the recipe to use the + newer version of the software: + + $ devtool upgrade -V version recipe + + By default, the devtool upgrade command + extracts source code into the sources + directory in the workspace. + If you want the code extracted to any other location, you + need to provide the srctree + positional argument with the command as follows: + + $ devtool upgrade -V version recipe srctree + + Also, in this example, the "-V" option is used to specify + the new version. + If the source files pointed to by the + SRC_URI statement in the recipe are + in a Git repository, you must provide the "-S" option and + specify a revision for the software. + + Once devtool locates the recipe, + it uses the SRC_URI variable to locate + the source code and any local patch files from other + developers are located. + The result is that the command sets up the source + code, the new version of the recipe, and an append file + all within the workspace. + + Resolve any Conflicts created by the Upgrade: + At this point, there could be some conflicts due to the + software being upgraded to a new version. + This would occur if your recipe specifies some patch files in + SRC_URI that conflict with changes + made in the new version of the software. + If this is the case, you need to resolve the conflicts + by editing the source and following the normal + git rebase conflict resolution + process. + + Before moving onto the next step, be sure to resolve any + such conflicts created through use of a newer or different + version of the software. + + Build the Recipe: + Once you have your recipe in order, you can build it. + 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. + + This step assumes you have a previously built + image that is already either running in QEMU or + running on actual hardware. + Also, it is assumed that for deployment of the image + to the target, SSH is installed in the image and if + the image is running on real hardware that you have + network access to and from your development machine. + + You can deploy your build output to that target hardware by + using the devtool deploy-target command: + + $ devtool deploy-target recipe target + + The target is a live target machine + running as an SSH server. + + You can, of course, also deploy the image you build + using the devtool build-image command + to actual hardware. + 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. + + + $ devtool update-recipe recipe + + 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. + + Move the Recipe to its Permanent Layer: + Before cleaning up the workspace, you need to move the + final recipe to its permanent layer. + You can either overwrite the original recipe or you can + overlay the upgraded recipe into a separate layer. + You must do this before using the + devtool reset command if you want to + retain the upgraded recipe. + + 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 @@ -2256,24 +2421,27 @@ -h, --help show this help message and exit subcommands: - <subcommand> - create-workspace Set up workspace in an alternative location - upgrade Upgrade an existing recipe - deploy-target Deploy recipe output files to live target machine - undeploy-target Undeploy recipe output files in live target machine - search Search available recipes - build Build a recipe - edit-recipe Edit a recipe file in your workspace - configure-help Get help on configure script options - add Add a new recipe - modify Modify the source for an existing recipe - extract Extract the source for an existing recipe - sync Synchronize the source tree for an existing recipe - update-recipe Apply changes from external source tree to recipe - status Show workspace status - reset Remove a recipe from your workspace - build-image Build image including workspace recipe packages - + Beginning work on a recipe: + add Add a new recipe + modify Modify the source for an existing recipe + upgrade Upgrade an existing recipe + Getting information: + 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 + update-recipe Apply changes from external source tree to recipe + reset Remove a recipe from 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 + build-image Build image including workspace recipe packages + Advanced: + create-workspace Set up workspace in an alternative location + extract Extract the source for an existing recipe + sync Synchronize the source tree for an existing recipe Use devtool <subcommand> --help to get help on a specific command -- cgit v1.2.3-54-g00ecf