4.3.1.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. Finish Your Work With the Recipe: The devtool finish command creates any patches corresponding to commits in the local Git repository, moves the new recipe to a more permanent 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 committed to the Git repository in the source tree.

    As mentioned, the devtool finish command moves the final recipe to its permanent 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 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.