diff options
author | Scott Rifenbark <srifenbark@gmail.com> | 2018-05-03 14:29:25 -0700 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2018-05-24 17:16:30 +0100 |
commit | dd0e423bfd3215bcb027d48fd5bcefc90e20d8d3 (patch) | |
tree | f5b3419022280882c40d5ac6db266cb921ddf36b /documentation/sdk-manual | |
parent | d77de6b09f21f450cb9f13e8fc1c50a1c088800c (diff) | |
download | openembedded-core-contrib-dd0e423bfd3215bcb027d48fd5bcefc90e20d8d3.tar.gz |
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 <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/sdk-manual')
-rw-r--r-- | documentation/sdk-manual/sdk-extensible.xml | 221 |
1 files changed, 125 insertions, 96 deletions
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 @@ <para> The <filename>devtool modify</filename> 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. </para> <para> Depending on your particular scenario, the arguments and options you use with <filename>devtool modify</filename> form different combinations. - The following diagram shows common development flows - you would use with the <filename>devtool modify</filename> - command: + The following diagram shows common development flows for the + <filename>devtool modify</filename> command: </para> <para> @@ -543,140 +542,165 @@ <para> <orderedlist> - <listitem><para><emphasis>Preparing to Modify the Code</emphasis>: + <listitem><para> + <emphasis>Preparing to Modify the Code</emphasis>: The top part of the flow shows three scenarios by which you could use <filename>devtool modify</filename> to prepare to work on source files. Each scenario assumes the following: <itemizedlist> - <listitem><para>The recipe exists in some layer external + <listitem><para> + The recipe exists locally in a layer external to the <filename>devtool</filename> workspace. </para></listitem> - <listitem><para>The source files exist upstream in an + <listitem><para> + The source files exist either upstream in an un-extracted state or locally in a previously extracted state. </para></listitem> </itemizedlist> 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. <itemizedlist> - <listitem><para><emphasis>Left</emphasis>: - The left scenario represents a common situation - where the source code does not exist locally - and needs to be extracted. + <listitem><para> + <emphasis>Left</emphasis>: + 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 <filename>devtool</filename> + workspace location. The recipe, in this scenario, is in its own layer outside the workspace (i.e. <filename>meta-</filename><replaceable>layername</replaceable>). </para> - <para>The following command identifies the recipe - and by default extracts the source files: + <para>The following command identifies the + recipe and, by default, extracts the source + files: <literallayout class='monospaced'> $ devtool modify <replaceable>recipe</replaceable> </literallayout> - Once <filename>devtool</filename>locates the recipe, - it uses the + Once <filename>devtool</filename>locates the + recipe, <filename>devtool</filename> uses the + recipe's <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> - variable to locate the source code and - any local patch files from other developers are - located. - <note> - You cannot provide an URL for - <replaceable>srctree</replaceable> when using the - <filename>devtool modify</filename> command. - </note> - With this scenario, however, since no - <replaceable>srctree</replaceable> argument exists, the - <filename>devtool modify</filename> 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.</para> + + <para>With this scenario, no + <replaceable>srctree</replaceable> argument + exists. + Consequently, the default behavior of the + <filename>devtool modify</filename> command is + to extract the source files pointed to by the + <filename>SRC_URI</filename> statements into a + local Git structure. + Furthermore, the location for the extracted + source is the default area within the + <filename>devtool</filename> 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. </para></listitem> - <listitem><para><emphasis>Middle</emphasis>: - The middle scenario represents a situation where - the source code also does not exist locally. + <listitem><para> + <emphasis>Middle</emphasis>: + 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.</para> + The recipe, in this scenario, is again local + and in its own layer outside the workspace. + </para> <para>The following command tells <filename>devtool</filename> 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 + <filename>devtool</filename> workspace: <literallayout class='monospaced'> $ devtool modify <replaceable>recipe srctree</replaceable> </literallayout> + <note> + You cannot provide a URL for + <replaceable>srctree</replaceable> using + the <filename>devtool</filename> command. + </note> As with all extractions, the command uses - the recipe's <filename>SRC_URI</filename> to locate the - source files. - Once the files are located, the command by default - extracts them. - Providing the <replaceable>srctree</replaceable> - argument instructs <filename>devtool</filename> where - to place the extracted source.</para> - - <para>Within workspace, <filename>devtool</filename> - creates an append file for the recipe. + the recipe's <filename>SRC_URI</filename> + statements to locate the source files and any + associated patch files. + Once the files are located, the command by + default extracts them into + <replaceable>srctree</replaceable>.</para> + + <para>Within workspace, + <filename>devtool</filename> 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 <replaceable>srctree</replaceable>. + the source files are extracted to the location + you provide with + <replaceable>srctree</replaceable>. </para></listitem> - <listitem><para><emphasis>Right</emphasis>: - The right scenario represents a situation - where the source tree - (<replaceable>srctree</replaceable>) exists as a - previously extracted Git structure outside of - the <filename>devtool</filename> workspace. + <listitem><para> + <emphasis>Right</emphasis>: + The right scenario in the figure represents a + situation where the source tree + (<replaceable>srctree</replaceable>) already + exists locally as a previously extracted Git + structure outside of the + <filename>devtool</filename> workspace. In this example, the recipe also exists - elsewhere in its own layer. + elsewhere locally in its own layer. </para> <para>The following command tells <filename>devtool</filename> the recipe - with which to work, uses the "-n" option to indicate - source does not need to be extracted, and uses - <replaceable>srctree</replaceable> 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 <replaceable>srctree</replaceable> to + point to the previously extracted source files: <literallayout class='monospaced'> $ devtool modify -n <replaceable>recipe srctree</replaceable> </literallayout> </para> <para>Once the command finishes, it creates only - an append file for the recipe in the workspace. + an append file for the recipe in the + <filename>devtool</filename> workspace. The recipe and the source code remain in their original locations. </para></listitem> </itemizedlist> </para></listitem> - <listitem><para><emphasis>Edit the Source</emphasis>: - Once you have used the <filename>devtool modify</filename> - command, you are free to make changes to the source - files. + <listitem><para> + <emphasis>Edit the Source</emphasis>: + Once you have used the + <filename>devtool modify</filename> 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. </para></listitem> - <listitem><para><emphasis>Build the Recipe</emphasis>: + <listitem><para> + <emphasis>Build the Recipe</emphasis>: Once you have updated the source files, you can build the recipe. </para></listitem> - <listitem><para><emphasis>Deploy the Build Output</emphasis>: + <listitem><para> + <emphasis>Deploy the Build Output</emphasis>: When you use the <filename>devtool build</filename> - 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. <note> 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. </note> - You can deploy your build output to that target hardware by - using the <filename>devtool deploy-target</filename> command: + You can deploy your build output to that target + hardware by using the + <filename>devtool deploy-target</filename> command: <literallayout class='monospaced'> $ devtool deploy-target <replaceable>recipe target</replaceable> </literallayout> - The <replaceable>target</replaceable> is a live target machine - running as an SSH server.</para> + The <replaceable>target</replaceable> is a live target + machine running as an SSH server.</para> - <para>You can, of course, also deploy the image you build - using the <filename>devtool build-image</filename> command - to actual hardware. - However, <filename>devtool</filename> does not provide a - specific command that allows you to do this. + <para>You can, of course, use other methods to deploy + the image you built using the + <filename>devtool build-image</filename> command to + actual hardware. + <filename>devtool</filename> does not provide + a specific command to deploy the image to actual + hardware. </para></listitem> <listitem><para> <emphasis>Finish Your Work With the Recipe</emphasis>: @@ -707,28 +734,30 @@ Git repository, updates the recipe to point to them (or creates a <filename>.bbappend</filename> 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. <literallayout class='monospaced'> $ devtool finish <replaceable>recipe layer</replaceable> </literallayout> <note> 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 + <filename>devtool finish</filename> command. </note></para> <para>Because there is no need to move the recipe, <filename>devtool finish</filename> either updates the original recipe in the original layer or the command - creates a <filename>.bbappend</filename> in a different - layer as provided by <replaceable>layer</replaceable>. - </para> + creates a <filename>.bbappend</filename> file in a + different layer as provided by + <replaceable>layer</replaceable>.</para> <para>As a final process of the <filename>devtool finish</filename> 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. <note> You can use the <filename>devtool reset</filename> command to put things back should you decide you |