diff options
author | Scott Rifenbark <srifenbark@gmail.com> | 2016-02-11 17:14:32 -0800 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2016-03-03 17:40:12 +0000 |
commit | 7699f0ab60b000c38233ba99245df1ff76c44217 (patch) | |
tree | ec68e6cd9d2232509c8f6fa5af8e7d216a101d03 /documentation/dev-manual/dev-manual-model.xml | |
parent | 1eecaea70d0c801d08cea17e57c8693f8058cdce (diff) | |
download | openembedded-core-contrib-7699f0ab60b000c38233ba99245df1ff76c44217.tar.gz |
dev-manual: Added section for devtool modify flow
New figure and some writer notes for now
(From yocto-docs rev: 0a627626f5f353e514b0225b468b0bd0fa3ceef3)
Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/dev-manual/dev-manual-model.xml')
-rw-r--r-- | documentation/dev-manual/dev-manual-model.xml | 275 |
1 files changed, 275 insertions, 0 deletions
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml index d3fadbd1f7..b07b6c96c9 100644 --- a/documentation/dev-manual/dev-manual-model.xml +++ b/documentation/dev-manual/dev-manual-model.xml @@ -1952,6 +1952,281 @@ </orderedlist> </para> </section> + + <section id='devtool-use-devtool-modify-to-enable-work-on-code-associated-with-an-existing-recipe'> + <title>Use <filename>devtool modify</filename> to Enable Work on Code Associated with an Existing Recipe</title> + + <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. + </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: + </para> + + <para> + <imagedata fileref="figures/devtool-modify-flow.png" align="center" /> + </para> + + <para> + <orderedlist> + <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 + to the <filename>devtool</filename> workspace. + </para></listitem> + <listitem><para>The source files exist in a Git + structure 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 + 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 situation + where the source tree (srctree) exists 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 + (i.e. <filename>meta-</filename><replaceable>layername</replaceable>). + </para> + + <para>The following command tells + <filename>devtool</filename> the recipe + with which to work and uses + <replaceable>srctree</replaceable> to point to the + previously extracted source files: + <literallayout class='monospaced'> + $ devtool modify <replaceable>recipe srctree</replaceable> + </literallayout> + Because <filename>devtool</filename> uses the + <filename>conf/bblayers.conf</filename> 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 <replaceable>recipe</replaceable>. + </para> + + <para>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. + </para></listitem> + <listitem><para><emphasis>Middle</emphasis>: + 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 recipe, in this scenario, is again in its own + layer outside the workspace.</para> + + <para>The following command tells + <filename>devtool</filename> what recipe with + which to work and also uses the "-x" option to + instruct <filename>devtool</filename> to locate and + extract the source code: + <literallayout class='monospaced'> + $ devtool modify -x <replaceable>recipe srctree</replaceable> + </literallayout> + With the help of the + <filename>conf/bblayers.conf</filename> file, + <filename>devtool</filename>locates the recipe. + Inside the recipe, the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + variable points to where 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> + Once the files are located, the command extracts + them to the location specified by + <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>. + </para></listitem> + <listitem><para><emphasis>Right</emphasis>: + 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.</para> + + <para>The following command identifies the recipe + and instructs <filename>devtool</filename> to + extract the source files using the "-x" option: + <literallayout class='monospaced'> + $ devtool modify -x <replaceable>recipe</replaceable> + </literallayout> + As with the previous example, the + <filename>conf/bblayers.conf</filename> file + helps locate the recipe. + And, as with all extractions, the command uses + the recipe's <filename>SRC_URI</filename> to locate the + source files. + With this scenario, however, since no + <replaceable>srctree</replaceable> argument exists, the + <filename>devtool modify</filename> 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. + </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. + You can use any editor you like to make and save + your source code modifications. + </para></listitem> + <listitem><para><emphasis>Build the Recipe</emphasis>: + Once you have updated the source files, you can build + the recipe. + You can either use <filename>devtool build</filename> or + <filename>bitbake</filename>. + Either method produces build output that is stored + in + <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>. + </para></listitem> + <listitem><para><emphasis>Test Your Changes</emphasis>: + Once your code is built, you can test it for + correct operation. + If you have actual hardware, you can use the + <filename>devtool deploy-target</filename> 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: + <literallayout class='monospaced'> + $ devtool deploy-target <replaceable>recipe target</replaceable> + </literallayout> + Regardless of where you are deploying the build + output, the <replaceable>target</replaceable> must + be running an SSH server. + For example, to run the <filename>dropbear</filename> + SSH server in an image you are going to be running on + QEMU, be sure this statement is in your + <filename>conf/local.conf</filename> file: + <literallayout class='monospaced'> + EXTRA_IMAGE_FEATURES += "ssh-server-dropbear" + </literallayout> + Here is a <filename>devtool deploy-target</filename> + command example that uses the + <filename>busybox</filename> recipe and QEMU as + the target: + <literallayout class='monospaced'> + $ devtool deploy-target busybox root@192.168.7.2 + </literallayout> + <note> + It is worth mentioning that you can load an image + onto your <replaceable>target</replaceable> 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 + <filename>bitbake</filename> 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 + <filename>devtool build</filename> output. + </note> + You can continue to change, build, and test your + changes until you are satisfied with the code's + behavior. + </para></listitem> + <listitem><para><emphasis>Optionally Create Patch Files for Your Changes</emphasis>: + After you have debugged your changes, you can + use <filename>devtool update-recipe</filename> to + generate patch files for all the commits you have + made. + <note> + Patch files are generated only for changes + you have committed. + </note> + <literallayout class='monospaced'> + $ devtool update-recipe <replaceable>recipe</replaceable> + </literallayout> + By default, <filename>devtool</filename> updates + the recipe's <filename>SRC_URI</filename> statement + to include the location for the patch files it + generates. + <note> + You can use the + "--append <replaceable>LAYERDIR</replaceable> + option to cause the command to create append files + in a specific layer rather than the default + recipe layer. + </note> + The command also creates a <replaceable>recipe</replaceable> + folder beneath the folder in which the recipe resides + that contains the actual <filename>*.patch</filename> + files. + </para></listitem> + <listitem><para><emphasis>Make Sure the Recipe is in the Final Layer</emphasis>: + Strictly speaking, this step is not necessary if + you begin this workflow with the recipe in its own + proper layer outside of the <filename>devtool</filename> + 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 <filename>devtool add</filename> to + create a recipe in the workspace).</para> + + <para>You should be sure that the recipe is located + outside of the workspace before using the + <filename>devtool reset</filename> command described in + the next step. + </para></listitem> + <listitem><para><emphasis>Restore the Workspace</emphasis>: + The <filename>devtool reset</filename> 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 + <replaceable>recipe</replaceable>. + <literallayout class='monospaced'> + $ devtool reset <replaceable>recipe</replaceable> + </literallayout> + Once the workspace is restored, you can use it again for + working on different code. + </para></listitem> + </orderedlist> + </para> + </section> </section> <section id='devtool-quick-reference'> |