From 38278f0a2162fbb0fda6d5b00d73495906acb968 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Mon, 19 Sep 2016 12:30:02 -0700 Subject: sdk-manual: Added the devtool upgrade command flow to the manual. I needed a new figure and a new section. (From yocto-docs rev: d413ca7b9b946450af7c2c15ab0e68e9181517e9) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../figures/sdk-devtool-upgrade-flow.png | Bin 0 -> 139827 bytes documentation/sdk-manual/sdk-extensible.xml | 164 +++++++++++++++++++++ 2 files changed, 164 insertions(+) create mode 100644 documentation/sdk-manual/figures/sdk-devtool-upgrade-flow.png diff --git a/documentation/sdk-manual/figures/sdk-devtool-upgrade-flow.png b/documentation/sdk-manual/figures/sdk-devtool-upgrade-flow.png new file mode 100644 index 0000000000..65474dad02 Binary files /dev/null and b/documentation/sdk-manual/figures/sdk-devtool-upgrade-flow.png differ diff --git a/documentation/sdk-manual/sdk-extensible.xml b/documentation/sdk-manual/sdk-extensible.xml index bb51683a44..67df1b0975 100644 --- a/documentation/sdk-manual/sdk-extensible.xml +++ b/documentation/sdk-manual/sdk-extensible.xml @@ -604,6 +604,170 @@ + +
+ 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. + + + 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 finish 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. + + + + +
-- cgit 1.2.3-korg