From dd0e423bfd3215bcb027d48fd5bcefc90e20d8d3 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Thu, 3 May 2018 14:29:25 -0700 Subject: sdk-manual: Updated devtool modify workflow section. I found this section a bit loosely worded and could result in confusion to a user ramping up with YP. I have done an extensive rewrite focusing on exact wordings. (From yocto-docs rev: af64c07d259e06fb13572fc224636ed240037b57) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/sdk-manual/sdk-extensible.xml | 221 ++++++++++++++++------------ 1 file changed, 125 insertions(+), 96 deletions(-) (limited to 'documentation/sdk-manual/sdk-extensible.xml') diff --git a/documentation/sdk-manual/sdk-extensible.xml b/documentation/sdk-manual/sdk-extensible.xml index 4303054cba..3a99b3791b 100644 --- a/documentation/sdk-manual/sdk-extensible.xml +++ b/documentation/sdk-manual/sdk-extensible.xml @@ -520,21 +520,20 @@ The devtool modify command prepares the - way to work on existing code that already has a recipe in - place. - The command is flexible enough to allow you to extract code, - specify the existing recipe, and keep track of and gather any - patch files from other developers that are - associated with the code. + way to work on existing code that already has a local recipe in + place that is used to build the software. + The command is flexible enough to allow you to extract code + from an upstream source, specify the existing recipe, and + keep track of and gather any patch files from other developers + that are associated with the code. Depending on your particular scenario, the arguments and options you use with devtool modify form different combinations. - The following diagram shows common development flows - you would use with the devtool modify - command: + The following diagram shows common development flows for the + devtool modify command: @@ -543,140 +542,165 @@ - Preparing to Modify the Code: + + Preparing to Modify the Code: The top part of the flow shows three scenarios by which you could use devtool modify to prepare to work on source files. Each scenario assumes the following: - The recipe exists in some layer external + + The recipe exists locally in a layer external to the devtool workspace. - The source files exist upstream in an + + The source files exist either upstream in an un-extracted state or locally in a previously extracted state. The typical situation is where another developer has - created some layer for use with the Yocto Project and + created a layer for use with the Yocto Project and their recipe already resides in that layer. Furthermore, their source code is readily available either upstream or locally. - Left: - The left scenario represents a common situation - where the source code does not exist locally - and needs to be extracted. + + Left: + The left scenario in the figure represents a + common situation where the source code does + not exist locally and it needs to be extracted + from an upstream source. In this situation, the source is extracted - into the default workspace location. + into the default devtool + workspace location. The recipe, in this scenario, is in its own layer outside the workspace (i.e. meta-layername). - The following command identifies the recipe - and by default extracts the source files: + The following command identifies the + recipe and, by default, extracts the source + files: $ devtool modify recipe - Once devtoollocates the recipe, - it uses the + Once devtoollocates the + recipe, devtool uses the + recipe's 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 by default - extracts the source files to a Git structure. - Furthermore, the location for the extracted source is the - default area within the workspace. - The result is that the command sets up both the source - code and an append file within the workspace with the - recipe remaining in its original location. + statements to locate the source code and any + local patch files from other developers. + + With this scenario, no + srctree argument + exists. + Consequently, the default behavior of the + devtool modify command is + to extract the source files pointed to by the + SRC_URI statements into a + local Git structure. + Furthermore, the location for the extracted + source is the default area within the + devtool workspace. + The result is that the command sets up both + the source code and an append file within the + workspace while the recipe remains in its + original location. - Middle: - The middle scenario represents a situation where - the source code also does not exist locally. + + Middle: + The middle scenario in the figure represents a + situation where 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. + The recipe, in this scenario, is again local + and in its own layer outside the workspace. + The following command tells devtool what recipe with - which to work and, in this case, identifies a local - area for the extracted source files that is outside - of the default workspace: + which to work and, in this case, identifies a + local area for the extracted source files that + is outside of the default + devtool workspace: $ devtool modify recipe srctree + + You cannot provide a URL for + srctree using + the devtool 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 by default - extracts them. - Providing the srctree - argument instructs devtool where - to place the extracted source. - - Within workspace, devtool - creates an append file for the recipe. + the recipe's SRC_URI + statements to locate the source files and any + associated patch files. + Once the files are located, the command by + default extracts them into + srctree. + + Within workspace, + devtool creates an append + file for the recipe. The recipe remains in its original location but - the source files are extracted to the location you - provided with srctree. + the source files are extracted to the location + you provide with + srctree. - Right: - The right scenario represents a situation - where the source tree - (srctree) exists as a - previously extracted Git structure outside of - the devtool workspace. + + Right: + The right scenario in the figure represents a + situation where the source tree + (srctree) already + exists locally as a previously extracted Git + structure outside of the + devtool workspace. In this example, the recipe also exists - elsewhere in its own layer. + elsewhere locally in its own layer. The following command tells devtool the recipe - with which to work, uses the "-n" option to indicate - source does not need to be extracted, and uses - srctree to point to the - previously extracted source files: + with which to work, uses the "-n" option to + indicate source does not need to be extracted, + and uses srctree to + point to the previously extracted source files: $ devtool modify -n recipe srctree Once the command finishes, it creates only - an append file for the recipe in the workspace. + an append file for the recipe in the + devtool workspace. The recipe and the source code remain in their original locations. - Edit the Source: - Once you have used the devtool modify - command, you are free to make changes to the source - files. + + Edit the Source: + Once you have used the + devtool modify command, you are + free to make changes to the source files. You can use any editor you like to make and save your source code modifications. - Build the Recipe: + + Build the Recipe: Once you have updated the source files, you can build the recipe. - 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. + 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 @@ -686,19 +710,22 @@ 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. + 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, use other methods to deploy + the image you built using the + devtool build-image command to + actual hardware. + devtool does not provide + a specific command to deploy the image to actual + hardware. Finish Your Work With the Recipe: @@ -707,28 +734,30 @@ 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. + 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. + staged and committed within the local Git + repository before you use the + devtool finish command. 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. - + creates a .bbappend file 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. + areas rather than from the workspace. You can use the devtool reset command to put things back should you decide you -- cgit v1.2.3-54-g00ecf