4.3.1.2. Use devtool modify 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:

  1. 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 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 common situation where the source code does not exist locally and needs to be extracted. In this situation, the source is extracted into the default 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:

           $ devtool modify recipe
                                      

      Once devtoollocates the recipe, it uses the SRC_URI variable to locate the source code and any local patch files from other developers are located.

      Note

      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.

    • Middle: The middle scenario 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 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:

           $ devtool modify recipe srctree
                                      

      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 place the extracted source.

      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 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.

      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:

           $ devtool modify -n recipe srctree
                                      

      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.

  2. 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.

  3. 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.

  4. Deploy the Build Output: When you use the devtool build command or bitbake 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 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.

    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.

    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.

  5. 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.

    Note

    Patch files are generated only for changes you have committed.

         $ devtool update-recipe recipe
                            

    By default, the devtool update-recipe command creates the patch files in a folder named the same as the recipe beneath the folder in which the recipe resides, and updates the recipe's SRC_URI statement to point to the generated patch files.

    Note

    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.

  6. 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.

         $ devtool reset recipe