From cf40ca7f5d86514ab3e161f43d795a1facbd5500 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Tue, 6 Mar 2018 13:59:44 -0800 Subject: sdk-manual: Updates to the devtool upgrade flow section. Did some rewriting to add some references to other sections in the manual set. Did some other minor clean up. (From yocto-docs rev: 7e7be31e96a0e73e230b8596b2431716f254e027) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/sdk-manual/sdk-extensible.xml | 174 +++++++++++++++++----------- 1 file changed, 107 insertions(+), 67 deletions(-) (limited to 'documentation/sdk-manual') diff --git a/documentation/sdk-manual/sdk-extensible.xml b/documentation/sdk-manual/sdk-extensible.xml index 6c4e5c2233..02a0b2ffe7 100644 --- a/documentation/sdk-manual/sdk-extensible.xml +++ b/documentation/sdk-manual/sdk-extensible.xml @@ -745,21 +745,39 @@ 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. + The devtool upgrade command upgrades + an existing recipe to that of a more up-to-date version + found upstream. + Throughout the life of software, recipes continually undergo + version upgrades by their upstream publishers. + You can use the devtool upgrade + workflow to make sure your recipes you are using for builds + are up-to-date with their upstream counterparts. + + Several methods exist by which you can upgrade recipes. + devtool upgrade happens to be one. + You can read about all the methods by which you can + upgrade recipes in the + "Upgrading Recipes" + section of the Yocto Project Development Tasks Manual. + - Depending on your particular scenario, the arguments and options - you use with devtool upgrade form different - combinations. + The devtool upgrade 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 + you would use with the devtool upgrade command: @@ -769,110 +787,131 @@ - Initiate the Upgrade: - The top part of the flow shows a typical scenario by which - you could use devtool upgrade. + + 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 + + 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 + + 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). + 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. + 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: + 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. + + In this example, the "-V" option specifies the new + version. + If you don't use "-V", the command upgrades the + recipe to the latest 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. + 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 + + Resolve any Conflicts created by the Upgrade: + At this point, conflicts could exist 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. + Conflicts 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. + + 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: + + Build the Recipe: Once you have your recipe in order, you can build it. - You can either use devtool build or - bitbake. + You can either use devtool build + or bitbake. Either method produces build output that is stored in TMPDIR. - Deploy the Build Output: + + 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 or bitbake to build + 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. + 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: + 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 + 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. + However, devtool does not provide + a specific command that allows you to do this. 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. + 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. If you specify a destination layer that is the same as the original source, then the old version of the recipe and associated files will be removed prior to @@ -884,6 +923,7 @@ Any changes you want to turn into patches must be committed to the Git repository in the source tree. + As a final process of the devtool finish command, the state of the standard layers and the upstream source is -- cgit v1.2.3-54-g00ecf