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 @@ + +
+ Use <filename>devtool modify</filename> to Enable Work on Code Associated with an Existing Recipe + + + 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. + + + + 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: + + + + + + + + + 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 + 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 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. + + 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 following command tells + devtool the recipe + with which to work and uses + srctree to point to the + previously extracted source files: + + $ devtool modify recipe srctree + + 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. + + 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 recipe, in this scenario, is again in its own + layer outside the workspace. + + The following command tells + devtool what recipe with + which to work and also uses the "-x" option to + instruct devtool to locate and + extract the source code: + + $ 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. + + Once the files are located, the command extracts + them to the location specified by + 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. + + 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 following command identifies the recipe + and instructs devtool to + extract the source files using the "-x" option: + + $ devtool modify -x recipe + + 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. + + + + 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: + Once you have updated the source files, you can build + the recipe. + You can either use devtool build or + bitbake. + Either method produces build output that is stored + 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: + + $ 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. + + Optionally Create Patch Files for Your Changes: + After you have debugged your changes, you can + use devtool update-recipe to + generate patch files for all the commits you have + made. + + Patch files are generated only for changes + you have committed. + + + $ devtool update-recipe recipe + + By default, devtool updates + the recipe's SRC_URI statement + to include the location for the patch files it + generates. + + You can use the + "--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. + + + +