2.4.2. Use devtool modify to Modify the Source of an Existing Component

The devtool modify command prepares the 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 for 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 locally in a layer external to the devtool workspace.

    • 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 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 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 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:

           $ devtool modify recipe
                                      

      Once devtoollocates the recipe, devtool uses the recipe's SRC_URI 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 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 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 devtool workspace:

           $ devtool modify recipe srctree
                                      

      Note

      You cannot provide a URL for srctree using the devtool command.

      As with all extractions, the command uses 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 provide with srctree.

    • 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 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:

           $ devtool modify -n recipe srctree
                                      

      Once the command finishes, it creates only an append file for the recipe in the devtool 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 or Rebuild the Image: The next step you take depends on what you are going to do with the new code.

    If you need to eventually move the build output to the target hardware, use the following devtool command:

         $ devtool build recipe
                            

    On the other hand, if you want an image to contain the recipe's packages from the workspace for immediate deployment onto a device (e.g. for testing purposes), you can use the devtool build-image command:

         $ devtool build-image image
                            

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

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

  5. Finish Your Work With the Recipe: The devtool finish command creates any patches corresponding to commits in the local 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.

         $ devtool finish recipe layer
                            

    Note

    Any changes you want to turn into patches must be 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 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 from the workspace.

    Note

    You can use the devtool reset command to put things back should you decide you do not want to proceed with your work. If you do use this command, realize that the source tree is preserved.