From 9cee16bd2ebd58b5ac609cd4542db6c016d59031 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Mon, 15 Feb 2016 21:37:53 -0800 Subject: dev-manual: Applied review comments to the devtool section (From yocto-docs rev: 8bd08b5bbe245e48496b95740d8b205650bd4a35) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/dev-manual/dev-manual-model.xml | 455 ++++++++++---------------- 1 file changed, 168 insertions(+), 287 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 843b1b788d..cef668408a 100644 --- a/documentation/dev-manual/dev-manual-model.xml +++ b/documentation/dev-manual/dev-manual-model.xml @@ -1764,15 +1764,6 @@ The remainder of this section presents these workflows. - - The steps in this section assume 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. -
@@ -1823,49 +1814,33 @@ feed into the devtool add workflow: Left: - The left scenario represents a situation - where the source tree (srctree) exists as a - previously extracted Git structure outside of - the devtool workspace. - - - The following command names the recipe - and identifies where the existing source tree - is located: + The left scenario represents a common situation + where the source code does not exist locally + and needs to be extracted. + In this situation, you just let it get + extracted to the default workspace - you do not + want it in some specific location outside of the + workspace. + Thus, everything you need will be located in the + workspace: - $ devtool add recipe srctree + $ devtool add recipe fetchuri - - If a recipe exists that is associated with - source code, devtool - can leverage off that if it knows about the - layer in which the recipe resides. - Be sure to update your - conf/bblayers.conf file - to include the layers you want - devtool to know about - when looking for an existing recipe. - - The command examines the source code and creates - a recipe for it placing the recipe into the - workspace. - - Because the extracted source code already exists, - devtool does not try to - relocate it into the workspace - just the new - (or a modified copy of) the recipe is placed in - the workspace. - - Aside from a recipe folder, the command - also creates an append folder and places an initial - *.bbappend within. + With this command, devtool + creates a recipe and an append file in the + workspace as well as extracts the upstream + source files into a local Git repository also + within the sources folder. Middle: - The middle scenario represents a situation where + The middle scenario also represents a situation where the source code does not exist locally. - In this case, the code is in an upstream Git - repository and needs to be extracted to some - local area. + In this case, the code is again upstream + and needs to be extracted to some + local area - this time outside of the default + workspace. + As always, if required devtool creates + a Git repository locally during the extraction. Furthermore, the first positional argument srctree in this case identifies where the @@ -1886,101 +1861,33 @@ for the recipe. Right: - The right scenario represents another situation - where the source code does not exist locally - and again needs to be extracted. - However, in this situation, you want to extract the - source into the workspace. - Thus, everything you need will be located in the - workspace: + The right scenario represents a situation + where the source tree (srctree) has been + previously prepared outside of the + devtool workspace. + + + The following command names the recipe + and identifies where the existing source tree + is located: - $ devtool add recipe fetchuri + $ devtool add recipe srctree - With this command, devtool - creates a recipe and an append file in the - workspace as well as extracts the upstream - source files into a local Git repository also - within the sources folder. + The command examines the source code and creates + a recipe for it placing the recipe into the + workspace. + + Because the extracted source code already exists, + devtool does not try to + relocate it into the workspace - just the new + the recipe is placed in the workspace. + + Aside from a recipe folder, the command + also creates an append folder and places an initial + *.bbappend within. - Edit the Recipe: At this point, you can use devtool edit-recipe to open up the editor as defined by the @@ -1999,6 +1906,10 @@ 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 @@ -2015,6 +1926,15 @@ 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 + 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: @@ -2030,8 +1950,10 @@ specific command that allows you to do this. Optionally Update the Recipe With Patch Files: - Once you are satisfied with the recipe you probably want - to generate patch files that go with the recipe. + 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. @@ -2040,11 +1962,11 @@ To convert commits created using Git to patch files, use the devtool update-recipe command. - Any patches added, removed, or otherwise must be - previously committed to the upstream Git repository. + Any changes you want to turn into patches must be + committed to the Git repository in the source tree. - $ devtool update-recipe recipe_name + $ devtool update-recipe recipe Move the Recipe to its Permanent Layer: @@ -2105,10 +2027,9 @@ The recipe exists in some layer external to the devtool workspace. - The source files exist in a Git - structure either upstream in an un-extracted - state or locally in a previously extracted - state. + The source files exist upstream in an + un-extracted state or locally in a previously + extracted state. The typical situation is where another developer has @@ -2118,44 +2039,49 @@ either upstream or locally. Left: - The left scenario represents a situation - where the source tree (srctree) exists as a - previously extracted Git structure outside of - the devtool workspace. - In this example, the recipe also exists - elsewhere in its own layer - (i.e. meta-layername). + The left scenario represents a common situation + where the source code does not exist locally + and needs to be extracted. + In this situation, the source is extracted + into the default workspace location. + The recipe, in this scenario, is in its own + layer outside the workspace + (i.e. + meta-layername). - The following command tells - devtool the recipe - with which to work and uses - srctree to point to the - previously extracted source files: + The following command identifies the recipe + and instructs devtool to + extract the source files using the "-x" option: - $ devtool modify recipe srctree + $ devtool modify -x recipe - Because devtool uses the - conf/bblayers.conf to - identify layers in which to look for recipes, - you do not have to provide anything beyond a - recipe's name with the command. - In other words, you do not have to provide a - full recipe pathname or provide any file naming - extensions for recipe. - - - Once the command finishes, it creates only - an append file for the recipe in the workspace. - The recipe and the source code remain in their - original locations. + Once devtoollocates the recipe, + it uses the + SRC_URI + variable to locate the source code and + any local patch files from other developers are + located. + + You cannot provide an URL for + srctree when using the + devtool modify command. + + With this scenario, however, since no + srctree argument exists, the + devtool modify command extracts the + source files to a Git structure using the default + location within the workspace. + The result is that the command set up both the source + code and an append file within the workspace with the + recipe remaining in its original location. Middle: The middle scenario represents a situation where - the source code does not exist locally. - In this case, the code is in an upstream Git - repository and needs to be extracted to some - local area. + the source code also does not exist locally. + In this case, the code is again upstream + and needs to be extracted to some + local area as a Git repository. The recipe, in this scenario, is again in its own layer outside the workspace. @@ -2167,19 +2093,9 @@ $ devtool modify -x recipe srctree - With the help of the - conf/bblayers.conf file, - devtoollocates the recipe. - Inside the recipe, the - SRC_URI - variable points to where the source code and - any local patch files from other developers are - located. - - You cannot provide an URL for - srctree when using the - devtool modify command. - + As with all extractions, the command uses + the recipe's SRC_URI to locate the + source files. Once the files are located, the command extracts them to the location specified by srctree. @@ -2191,34 +2107,28 @@ provided with srctree. Right: - The right scenario represents another situation - where the source code does not exist locally - and again needs to be extracted. - However, in this situation, you want to extract the - source into the workspace. - The recipe, in this scenario, is again in its own - layer outside the workspace. + The right scenario represents a situation + where the source tree (srctree) exists as a + previously extracted Git structure outside of + the devtool workspace. + In this example, the recipe also exists + elsewhere in its own layer. + - The following command identifies the recipe - and instructs devtool to - extract the source files using the "-x" option: + The following command tells + devtool the recipe + with which to work and uses + srctree to point to the + previously extracted source files: - $ devtool modify -x recipe + $ devtool modify recipe srctree - As with the previous example, the - conf/bblayers.conf file - helps locate the recipe. - And, as with all extractions, the command uses - the recipe's SRC_URI to locate the - source files. - With this scenario, however, since no - srctree argument exists, the - devtool modify command extracts the - source files to a Git structure using the default - location within the workspace. - The result is that the command set up both the source - code and an append file within the workspace with the - recipe remaining in its original location. + + + Once the command finishes, it creates only + an append file for the recipe in the workspace. + The recipe and the source code remain in their + original locations. @@ -2238,49 +2148,33 @@ in TMPDIR. - Test Your Changes: - Once your code is built, you can test it for - correct operation. - If you have actual hardware, you can use the - devtool deploy-target command - to put the build output on the target. - If you do not have target hardware, you can deploy - the output to QEMU where it can emulate the hardware: + 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 - Regardless of where you are deploying the build - output, the target must - be running an SSH server. - For example, to run the dropbear - SSH server in an image you are going to be running on - QEMU, be sure this statement is in your - conf/local.conf file: - - EXTRA_IMAGE_FEATURES += "ssh-server-dropbear" - - Here is a devtool deploy-target - command example that uses the - busybox recipe and QEMU as - the target: - - $ devtool deploy-target busybox root@192.168.7.2 - - - It is worth mentioning that you can load an image - onto your target and - while it is running, deploy your package build - output to the target as the image is running. - You can also rebuild your image using - bitbake and it will pick up - your new package output. - From there, you could re-run the image on QEMU - to see the effects of your - devtool build output. - - You can continue to change, build, and test your - changes until you are satisfied with the code's - behavior. + 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 @@ -2294,50 +2188,29 @@ $ devtool update-recipe recipe - By default, devtool updates - the recipe's SRC_URI statement - to include the location for the patch files it - generates. + 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 + "--append LAYERDIR" option to cause the command to create append files in a specific layer rather than the default recipe layer. - The command also creates a recipe - folder beneath the folder in which the recipe resides - that contains the actual *.patch - files. - - Make Sure the Recipe is in the Final Layer: - Strictly speaking, this step is not necessary if - you begin this workflow with the recipe in its own - proper layer outside of the devtool - workspace. - However, it is included here so that when you do the - final step following this you do not lose the recipe - should it be in the workspace, which is possible - (e.g. starting with devtool add to - create a recipe in the workspace). - - You should be sure that the recipe is located - outside of the workspace before using the - devtool reset command described in - the next step. 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. - Restoring the workspace removes all traces of the - recipe. $ devtool reset recipe - Once the workspace is restored, you can use it again for - working on different code. @@ -2469,6 +2342,13 @@ + attic - A directory created if devtool believes it preserve + anything when you run "devtool reset". For example, if you + run "devtool add", make changes to the recipe, and then + run "devtool reset", devtool takes notice that the file has + been changed and moves it into the attic should you still + want the recipe. + README - Provides information on what is in workspace layer and how to manage it. @@ -2485,9 +2365,10 @@ within that sub-directory. sources - A directory containing a working copy of the source files used - when building the recipe. This directory contains a - folder for each set of source files matched to a corresponding - recipe. + when building the recipe. This is the default directory used + as the location of the source tree when you do not provide a + source tree path. This directory contains a folder for each + set of source files matched to a corresponding recipe.
-- cgit v1.2.3-54-g00ecf