3.2.1. Use devtool add to Add an Application

The devtool add command generates a new recipe based on existing source code. This command takes advantage of the workspace layer that many devtool commands use. The command is flexible enough to allow you to extract source code into both the workspace or a separate local Git repository and to use existing code that does not need to be extracted.

Depending on your particular scenario, the arguments and options you use with devtool add form different combinations. The following diagram shows common development flows you would use with the devtool add command:

  1. Generating the New Recipe: The top part of the flow shows three scenarios by which you could use devtool add to generate a recipe based on existing source code.

    In a shared development environment, it is typical where other developers are responsible for various areas of source code. As a developer, you are probably interested in using that source code as part of your development using the Yocto Project. All you need is access to the code, a recipe, and a controlled area in which to do your work.

    Within the diagram, three possible scenarios feed into the devtool add workflow:

    • Left: The left scenario represents a common situation where the source code does not exist locally and needs to be extracted. In this situation, you just let it get extracted to the default workspace - you do not want it in some specific location outside of the workspace. Thus, everything you need will be located in the workspace:

           $ devtool add recipe fetchuri
                                  

      With this command, devtool creates a recipe and an append file in the workspace as well as extracts the upstream source files into a local Git repository also within the sources folder.

    • Middle: The middle scenario also represents a situation where the source code does not exist locally. In this case, the code is again upstream and needs to be extracted to some local area - this time outside of the default workspace. If required, devtool always creates a Git repository locally during the extraction. Furthermore, the first positional argument srctree in this case identifies where the devtool add command will locate the extracted code outside of the workspace:

           $ devtool add recipe srctree fetchuri
                                  

      In summary, the source code is pulled from fetchuri and extracted into the location defined by srctree as a local Git repository.

      Within workspace, devtool creates both the recipe and an append file for the recipe.

    • Right: The right scenario represents a situation where the source tree (srctree) has been previously prepared outside of the devtool workspace.

      The following command names the recipe and identifies where the existing source tree is located:

           $ devtool add recipe srctree
                                  

      The command examines the source code and creates a recipe for it placing the recipe into the workspace.

      Because the extracted source code already exists, devtool does not try to relocate it into the workspace - just the new the recipe is placed in the workspace.

      Aside from a recipe folder, the command also creates an append folder and places an initial *.bbappend within.

  2. Edit the Recipe: At this point, you can use devtool edit-recipe to open up the editor as defined by the $EDITOR environment variable and modify the file:

         $ devtool edit-recipe recipe
                        

    From within the editor, you can make modifications to the recipe that take affect when you build it later.

  3. Build the Recipe or Rebuild the Image: At this point in the flow, the next step you take depends on what you are going to do with the new code.

    If you need to take the build output and eventually move it to the target hardware, you would use devtool build:

         $ devtool build recipe
                        

    On the other hand, if you want an image to contain the recipe's packages 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, 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 Update the Recipe With Patch Files: Once you are satisfied with the recipe, if you have made any changes to the source tree that you want to have applied by the recipe, you need to generate patches from those changes. You do this before moving the recipe to its final layer and cleaning up the workspace area devtool uses. This optional step is especially relevant if you are using or adding third-party software.

    To convert commits created using Git to patch files, use the devtool update-recipe command.

    Note

    Any changes you want to turn into patches must be committed to the Git repository in the source tree.

         $ devtool update-recipe recipe
                        

  6. Move the Recipe to its Permanent Layer: Before cleaning up the workspace, you need to move the final recipe to its permanent layer. You must do this before using the devtool reset command if you want to retain the recipe.

  7. Reset the Recipe: As a final step, you can restore the state such that standard layers and the upstream source is used to build the recipe rather than data in the workspace. To reset the recipe, use the devtool reset command:

         $ devtool reset recipe