From e1769a81df957085f89c89b390feaa2a384d7e46 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Mon, 21 May 2018 10:33:23 -0700 Subject: sdk-manual: Updated devtool add workflow section. Had to update the figure to use "Upstream Source" labels and fix a wrong "devtool edit-recipe" command. That new figure went into both figures folders for the sdk-manual and mega-manual areas. Provideds some cleaner wording. (From yocto-docs rev: 6225d04dd0551a840d929b752225064a222962bc) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../mega-manual/figures/sdk-devtool-add-flow.png | Bin 179361 -> 180562 bytes .../sdk-manual/figures/sdk-devtool-add-flow.png | Bin 177945 -> 180562 bytes documentation/sdk-manual/sdk-extensible.xml | 253 ++++++++++----------- 3 files changed, 121 insertions(+), 132 deletions(-) diff --git a/documentation/mega-manual/figures/sdk-devtool-add-flow.png b/documentation/mega-manual/figures/sdk-devtool-add-flow.png index c09e60e355..745a028729 100644 Binary files a/documentation/mega-manual/figures/sdk-devtool-add-flow.png and b/documentation/mega-manual/figures/sdk-devtool-add-flow.png differ diff --git a/documentation/sdk-manual/figures/sdk-devtool-add-flow.png b/documentation/sdk-manual/figures/sdk-devtool-add-flow.png index 985ac331f1..745a028729 100644 Binary files a/documentation/sdk-manual/figures/sdk-devtool-add-flow.png and b/documentation/sdk-manual/figures/sdk-devtool-add-flow.png differ diff --git a/documentation/sdk-manual/sdk-extensible.xml b/documentation/sdk-manual/sdk-extensible.xml index f23ecc8043..cde599d682 100644 --- a/documentation/sdk-manual/sdk-extensible.xml +++ b/documentation/sdk-manual/sdk-extensible.xml @@ -205,51 +205,13 @@ SDK environment now set up; additionally you may now run devtool to perform development tasks. Run devtool --help for further details. - - Running the setup script defines many environment variables needed in - order to use the SDK (e.g. PATH, - CC, - LD, - and so forth). - If you want to see all the environment variables the script exports, - examine the installation file itself. + Running the setup script defines many environment variables needed + in order to use the SDK (e.g. PATH, + CC, + LD, + and so forth). + If you want to see all the environment variables the script + exports, examine the installation file itself. @@ -268,7 +230,7 @@ the extensible SDK. You can use devtool to help you easily develop any project whose build output must be part of an - image built using the OpenEmbedded build system. + image built using the build system. @@ -288,8 +250,8 @@ - Three devtool subcommands that provide - entry-points into development are: + Three devtool subcommands exist that provide + entry-points into development: devtool add: @@ -306,17 +268,17 @@ an updated set of source files. - As with the OpenEmbedded build system, "recipes" represent software - packages within devtool. + As with the build system, "recipes" represent software packages + within devtool. When you use devtool add, a recipe is automatically created. When you use devtool modify, the specified - existing recipe is used in order to determine where to get the source - code and how to patch it. + existing recipe is used in order to determine where to get the + source code and how to patch it. In both cases, an environment is set up so that when you build the recipe a source tree that is under your control is used in order to allow you to make changes to the source as desired. - By default, both new recipes and the source go into a "workspace" + By default, new recipes and the source go into a "workspace" directory under the SDK. @@ -363,10 +325,10 @@ generate a recipe based on existing source code. In a shared development environment, it is - typical where other developers are responsible for + typical for other developers to be responsible for various areas of source code. As a developer, you are probably interested in using - that source code as part of your development using + that source code as part of your development within the Yocto Project. All you need is access to the code, a recipe, and a controlled area in which to do your work. @@ -374,138 +336,164 @@ Within the diagram, three possible scenarios feed into the devtool add workflow: - Left: - 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: + + Left: + The left scenario in the figure represents a + common situation where the source code does not + exist locally and needs to be extracted. + In this situation, the source code is extracted + to the default workspace - you do not + want the files in some specific location + outside of the workspace. + Thus, everything you need will be located in + the workspace: $ devtool add recipe fetchuri 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. + extracts the upstream source files into a local + Git repository within the + sources folder. + The command then creates a recipe named + recipe and a + corresponding append file in the workspace. + If you do not provide + recipe, the command + attempts to figure out the recipe name. - Middle: - The middle scenario also represents a situation where - the source code does not exist locally. + + Middle: + The middle scenario in the figure also + represents a situation where the source code + does not exist locally. In this case, the code is again upstream and needs to be extracted to some local area - this time outside of the default workspace. - If required, devtool - always creates - a Git repository locally during the extraction. + + If required, devtool + always creates + a Git repository locally during the + extraction. + Furthermore, the first positional argument - srctree in this case - identifies where the + srctree in this + case identifies where the devtool add command will locate the extracted code outside of the - workspace: + workspace. + You need to specify an empty directory: $ devtool add recipe srctree fetchuri In summary, the source code is pulled from - fetchuri and extracted - into the location defined by + fetchuri and + extracted into the location defined by srctree as a local Git repository. - Within workspace, devtool - creates both the recipe and an append file - for the recipe. + Within workspace, + devtool creates a + recipe named recipe + along with an associated append file. - Right: - The right scenario represents a situation - where the source tree (srctree) has been + + Right: + The right scenario in the figure represents a + situation where the + srctree has been previously prepared outside of the - devtool workspace. - + devtool workspace. - The following command names the recipe - and identifies where the existing source tree - is located: + The following command provides a new + recipe name and identifies the existing source + tree location: $ devtool add recipe srctree - The command examines the source code and creates - a recipe for it placing the recipe into the - workspace. + The command examines the source code and + creates a recipe named + recipe for the code + and places 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. + Because the extracted source code already + exists, devtool does not + try to relocate the source code into the + workspace - only 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. + also creates an associated append folder and + places an initial + *.bbappend file within. - Edit the Recipe: - At this point, you can use devtool edit-recipe + + Edit the Recipe: + You can use devtool edit-recipe to open up the editor as defined by the $EDITOR environment variable and modify the file: $ devtool edit-recipe recipe - From within the editor, you can make modifications to the - recipe that take affect when you build it later. + From within the editor, you can make modifications to + the recipe that take affect when you build it later. - Build the Recipe or Rebuild the Image: - At this point in the flow, the next step you - take depends on what you are going to do with - the new code. - If you need to take the build output and eventually - move it to the target hardware, you would use - devtool build: + + Build the Recipe or Rebuild the Image: + The next step you take depends on what you are going + to do with the new code. + + If you need to eventually move the build output + to the target hardware, use the following + devtool command: $ devtool build recipe + On the other hand, if you want an image to - contain the recipe's packages for immediate deployment - onto a device (e.g. for testing purposes), you can use + contain the recipe's packages from the workspace + for immediate deployment onto a device (e.g. for + testing purposes), you can use the devtool build-image command: $ devtool build-image image - Deploy the Build Output: + + Deploy the Build Output: When you use the devtool build command to build out your recipe, you probably want to - see if the resulting build output works as expected on target - hardware. + see if the resulting build output works as expected + on the 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. + is 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, + 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. + 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. + You can, of course, also deploy the image you + build to actual hardware by using the + devtool build-image command. + However, devtool does not provide + a specific command that allows you to deploy the + image to actual hardware. Finish Your Work With the Recipe: @@ -522,8 +510,9 @@ committed to the Git repository in the source tree. - As mentioned, the devtool finish - command moves the final recipe to its permanent layer. + As mentioned, the + devtool finish command moves the + final recipe to its permanent layer. As a final process of the -- cgit v1.2.3-54-g00ecf