%poky; ] > Many development models exist for which you can use the Yocto Project. This chapter overviews simple methods that use tools provided by the Yocto Project: System Development: System Development covers Board Support Package (BSP) development and kernel modification or configuration. For an example on how to create a BSP, see the "Creating a New BSP Layer Using the yocto-bsp Script" section in the Yocto Project Board Support Package (BSP) Developer's Guide. For more complete information on how to work with the kernel, see the Yocto Project Linux Kernel Development Manual. User Application Development: User Application Development covers development of applications that you intend to run on target hardware. For information on how to set up your host development system for user-space application development, see the Yocto Project Software Development Kit (SDK) Developer's Guide. For a simple example of user-space application development using the Eclipse IDE, see the "Developing Applications Using Eclipse" section. Temporary Source Code Modification: Direct modification of temporary source code is a convenient development model to quickly iterate and develop towards a solution. Once you implement the solution, you should of course take steps to get the changes upstream and applied in the affected recipes. Image Development using Toaster: You can use Toaster to build custom operating system images within the build environment. Toaster provides an efficient interface to the OpenEmbedded build that allows you to start builds and examine build statistics. Using a Development Shell: You can use a devshell to efficiently debug commands or simply edit packages. Working inside a development shell is a quick way to set up the OpenEmbedded build environment to work on parts of a project.

System development involves modification or creation of an image that you want to run on a specific hardware target. Usually, when you want to create an image that runs on embedded hardware, the image does not require the same number of features that a full-fledged Linux distribution provides. Thus, you can create a much smaller image that is designed to use only the features for your particular hardware. To help you understand how system development works in the Yocto Project, this section covers two types of image development: BSP creation and kernel modification or configuration.

A BSP is a collection of recipes that, when applied during a build, results in an image that you can run on a particular board. Thus, the package when compiled into the new image, supports the operation of the board. For a brief list of terms used when describing the development process in the Yocto Project, see the "Yocto Project Terms" section. The remainder of this section presents the basic steps used to create a BSP using the Yocto Project's BSP Tools. Although not required for BSP creation, the meta-intel repository, which contains many BSPs supported by the Yocto Project, is part of the example. For an example that shows how to create a new layer using the tools, see the "Creating a New BSP Layer Using the yocto-bsp Script" section in the Yocto Project Board Support Package (BSP) Developer's Guide. The following illustration and list summarize the BSP creation general workflow. Set up your host development system to support development using the Yocto Project: See the "The Linux Distribution" and the "The Build Host Packages" sections both in the Yocto Project Quick Start for requirements. Establish a local copy of the project files on your system: You need this Source Directory available on your host system. Having these files on your system gives you access to the build process and to the tools you need. For information on how to set up the Source Directory, see the "Getting Set Up" section. Establish the meta-intel repository on your system: Having local copies of these supported BSP layers on your system gives you access to layers you might be able to build on or modify to create your BSP. For information on how to get these files, see the "Getting Set Up" section. Create your own BSP layer using the yocto-bsp script: Layers are ideal for isolating and storing work for a given piece of hardware. A layer is really just a location or area in which you place the recipes and configurations for your BSP. In fact, a BSP is, in itself, a special type of layer. The simplest way to create a new BSP layer that is compliant with the Yocto Project is to use the yocto-bsp script. For information about that script, see the "Creating a New BSP Layer Using the yocto-bsp Script" section in the Yocto Project Board Support (BSP) Developer's Guide. Another example that illustrates a layer is an application. Suppose you are creating an application that has library or other dependencies in order for it to compile and run. The layer, in this case, would be where all the recipes that define those dependencies are kept. The key point for a layer is that it is an isolated area that contains all the relevant information for the project that the OpenEmbedded build system knows about. For more information on layers, see the "Understanding and Creating Layers" section. For more information on BSP layers, see the "BSP Layers" section in the Yocto Project Board Support Package (BSP) Developer's Guide. Five BSPs exist that are part of the Yocto Project release: beaglebone (ARM), mpc8315e (PowerPC), and edgerouter (MIPS). The recipes and configurations for these five BSPs are located and dispersed within the Source Directory. Three core Intel BSPs exist as part of the Yocto Project release in the meta-intel layer: intel-core2-32, which is a BSP optimized for the Core2 family of CPUs as well as all CPUs prior to the Silvermont core. intel-corei7-64, which is a BSP optimized for Nehalem and later Core and Xeon CPUs as well as Silvermont and later Atom CPUs, such as the Baytrail SoCs. intel-quark, which is a BSP optimized for the Intel Galileo gen1 & gen2 development boards. When you set up a layer for a new BSP, you should follow a standard layout. This layout is described in the "Example Filesystem Layout" section of the Board Support Package (BSP) Development Guide. In the standard layout, you will notice a suggested structure for recipes and configuration information. You can see the standard layout for a BSP by examining any supported BSP found in the meta-intel layer inside the Source Directory. Make configuration changes to your new BSP layer: The standard BSP layer structure organizes the files you need to edit in conf and several recipes-* directories within the BSP layer. Configuration changes identify where your new layer is on the local system and identify which kernel you are going to use. When you run the yocto-bsp script, you are able to interactively configure many things for the BSP (e.g. keyboard, touchscreen, and so forth). Make recipe changes to your new BSP layer: Recipe changes include altering recipes (.bb files), removing recipes you do not use, and adding new recipes or append files (.bbappend) that you need to support your hardware. Prepare for the build: Once you have made all the changes to your BSP layer, there remains a few things you need to do for the OpenEmbedded build system in order for it to create your image. You need to get the build environment ready by sourcing an environment setup script (i.e. oe-init-build-env or oe-init-build-env-memres) and you need to be sure two key configuration files are configured appropriately: the conf/local.conf and the conf/bblayers.conf file. You must make the OpenEmbedded build system aware of your new layer. See the "Enabling Your Layer" section for information on how to let the build system know about your new layer. The entire process for building an image is overviewed in the section "Building Images" section of the Yocto Project Quick Start. You might want to reference this information. Build the image: The OpenEmbedded build system uses the BitBake tool to build images based on the type of image you want to create. You can find more information about BitBake in the BitBake User Manual. The build process supports several types of images to satisfy different needs. See the "Images" chapter in the Yocto Project Reference Manual for information on supported images.

Kernel modification involves changing the Yocto Project kernel, which could involve changing configuration options as well as adding new kernel recipes. Configuration changes can be added in the form of configuration fragments, while recipe modification comes through the kernel's recipes-kernel area in a kernel layer you create. The remainder of this section presents a high-level overview of the Yocto Project kernel architecture and the steps to modify the kernel. You can reference the "Patching the Kernel" section for an example that changes the source code of the kernel. For information on how to configure the kernel, see the "Configuring the Kernel" section. For more information on the kernel and on modifying the kernel, see the Yocto Project Linux Kernel Development Manual.

Traditionally, when one thinks of a patched kernel, they think of a base kernel source tree and a fixed structure that contains kernel patches. The Yocto Project, however, employs mechanisms that, in a sense, result in a kernel source generator. By the end of this section, this analogy will become clearer. You can find a web interface to the Yocto Project kernel source repositories at . If you look at the interface, you will see to the left a grouping of Git repositories titled "Yocto Linux Kernel." Within this group, you will find several kernels supported by the Yocto Project: linux-yocto-3.14 - The stable Yocto Project kernel to use with the Yocto Project Releases 1.6 and 1.7. This kernel is based on the Linux 3.14 released kernel. linux-yocto-3.17 - An additional, unsupported Yocto Project kernel used with the Yocto Project Release 1.7. This kernel is based on the Linux 3.17 released kernel. linux-yocto-3.19 - The stable Yocto Project kernel to use with the Yocto Project Release 1.8. This kernel is based on the Linux 3.19 released kernel. linux-yocto-4.1 - The stable Yocto Project kernel to use with the Yocto Project Release 2.0. This kernel is based on the Linux 4.1 released kernel. linux-yocto-4.4 - The stable Yocto Project kernel to use with the Yocto Project Release 2.1. This kernel is based on the Linux 4.4 released kernel. linux-yocto-dev - A development kernel based on the latest upstream release candidate available. Long Term Support Initiative (LTSI) for Yocto Project kernels is as follows: For Yocto Project releases 1.7, 1.8, and 2.0, the LTSI kernel is linux-yocto-3.14. For Yocto Project release 2.1, the LTSI kernel is linux-yocto-4.1. The kernels are maintained using the Git revision control system that structures them using the familiar "tree", "branch", and "leaf" scheme. Branches represent diversions from general code to more specific code, while leaves represent the end-points for a complete and unique kernel whose source files, when gathered from the root of the tree to the leaf, accumulate to create the files necessary for a specific piece of hardware and its features. The following figure displays this concept: Within the figure, the "Kernel.org Branch Point" represents the point in the tree where a supported base kernel is modified from the Linux kernel. For example, this could be the branch point for the linux-yocto-3.19 kernel. Thus, everything further to the right in the structure is based on the linux-yocto-3.19 kernel. Branch points to the right in the figure represent where the linux-yocto-3.19 kernel is modified for specific hardware or types of kernels, such as real-time kernels. Each leaf thus represents the end-point for a kernel designed to run on a specific targeted device. The overall result is a Git-maintained repository from which all the supported kernel types can be derived for all the supported devices. A big advantage to this scheme is the sharing of common features by keeping them in "larger" branches within the tree. This practice eliminates redundant storage of similar features shared among kernels. Keep in mind the figure does not take into account all the supported Yocto Project kernel types, but rather shows a single generic kernel just for conceptual purposes. Also keep in mind that this structure represents the Yocto Project source repositories that are either pulled from during the build or established on the host development system prior to the build by either cloning a particular kernel's Git repository or by downloading and unpacking a tarball. Upstream storage of all the available kernel source code is one thing, while representing and using the code on your host development system is another. Conceptually, you can think of the kernel source repositories as all the source files necessary for all the supported kernels. As a developer, you are just interested in the source files for the kernel on which you are working. And, furthermore, you need them available on your host system. Kernel source code is available on your host system a couple of different ways. If you are working in the kernel all the time, you probably would want to set up your own local Git repository of the kernel tree. If you just need to make some patches to the kernel, you can access temporary kernel source files that were extracted and used during a build. We will just talk about working with the temporary source code. For more information on how to get kernel source code onto your host system, see the "Yocto Project Kernel" bulleted item earlier in the manual. What happens during the build? When you build the kernel on your development system, all files needed for the build are taken from the source repositories pointed to by the SRC_URI variable and gathered in a temporary work area where they are subsequently used to create the unique kernel. Thus, in a sense, the process constructs a local source tree specific to your kernel to generate the new kernel image - a source generator if you will. The following figure shows the temporary file structure created on your host system when the build occurs. This Build Directory contains all the source files used during the build. Again, for additional information on the Yocto Project kernel's architecture and its branching strategy, see the Yocto Project Linux Kernel Development Manual. You can also reference the "Patching the Kernel" section for a detailed example that modifies the kernel.

This illustration and the following list summarizes the kernel modification general workflow. Set up your host development system to support development using the Yocto Project: See "The Linux Distribution" and "The Build Host Packages" sections both in the Yocto Project Quick Start for requirements. Establish a local copy of project files on your system: Having the Source Directory on your system gives you access to the build process and tools you need. For information on how to get these files, see the bulleted item "Yocto Project Release" earlier in this manual. Establish the temporary kernel source files: Temporary kernel source files are kept in the Build Directory created by the OpenEmbedded build system when you run BitBake. If you have never built the kernel in which you are interested, you need to run an initial build to establish local kernel source files. If you are building an image for the first time, you need to get the build environment ready by sourcing an environment setup script (i.e. oe-init-build-env or oe-init-build-env-memres). You also need to be sure two key configuration files (local.conf and bblayers.conf) are configured appropriately. The entire process for building an image is overviewed in the "Building Images" section of the Yocto Project Quick Start. You might want to reference this information. You can find more information on BitBake in the BitBake User Manual. The build process supports several types of images to satisfy different needs. See the "Images" chapter in the Yocto Project Reference Manual for information on supported images. Make changes to the kernel source code if applicable: Modifying the kernel does not always mean directly changing source files. However, if you have to do this, you make the changes to the files in the Build Directory. Make kernel configuration changes if applicable: If your situation calls for changing the kernel's configuration, you can use menuconfig, which allows you to interactively develop and test the configuration changes you are making to the kernel. Saving changes you make with menuconfig updates the kernel's .config file. Try to resist the temptation to directly edit an existing .config file, which is found in the Build Directory among the source code used for the build (e.g. see the bottom illustration in the "Kernel Overview" section). Doing so, can produce unexpected results when the OpenEmbedded build system regenerates the configuration file. Once you are satisfied with the configuration changes made using menuconfig and you have saved them, you can directly compare the resulting .config file against an existing original and gather those changes into a configuration fragment file to be referenced from within the kernel's .bbappend file. Additionally, if you are working in a BSP layer and need to modify the BSP's kernel's configuration, you can use the yocto-kernel script as well as menuconfig. The yocto-kernel script lets you interactively set up kernel configurations. Rebuild the kernel image with your changes: Rebuilding the kernel image applies your changes.

Standard and extensible Software Development Kits (SDK) make it easy to develop applications inside or outside of the Yocto Project development environment. Tools exist to help the application developer during any phase of development. For information on how to install and use an SDK, see the Yocto Project Software Development Kit (SDK) Developer's Guide.

A common development workflow consists of modifying project source files that are external to the Yocto Project and then integrating that project's build output into an image built using the OpenEmbedded build system. Given this scenario, development engineers typically want to stick to their familiar project development tools and methods, which allows them to just focus on the project. Several workflows exist that allow you to develop, build, and test code that is going to be integrated into an image built using the OpenEmbedded build system. This section describes two: devtool: A set of tools to aid in working on the source code built by the OpenEmbedded build system. Section "Using devtool in Your Workflow" describes this workflow. If you want more information that showcases the workflow, click here for a presentation by Trevor Woerner that, while somewhat dated, provides detailed background information and a complete working tutorial. Quilt: A powerful tool that allows you to capture source code changes without having a clean source tree. While Quilt is not the preferred workflow of the two, this section includes it for users that are committed to using the tool. See the "Using Quilt in Your Workflow" section for more information.

As mentioned earlier, devtool helps you easily develop projects whose build output must be part of an image built using the OpenEmbedded build system. Three entry points exist that allow you to develop using devtool: devtool add devtool modify devtool upgrade The remainder of this section presents these workflows. See the "devtool Quick Reference" in the Yocto Project Reference Manual for a devtool quick reference.

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

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 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. 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 to 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. 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. 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. 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. 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 Any changes you want to turn into patches must be committed to the Git repository in the source tree. 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 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 the workspace. 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.

The devtool upgrade command updates an existing recipe so that you can build it for an updated set of source files. The command is flexible enough to allow you to specify source code revision and versioning schemes, extract code into or out of the devtool workspace, and work with any source file forms that the fetchers support. Depending on your particular scenario, the arguments and options you use with devtool upgrade form different combinations. The following diagram shows a common development flow you would use with the devtool modify command: Initiate the Upgrade: The top part of the flow shows a typical scenario by which you could use devtool upgrade. The following conditions exist: The recipe exists in some layer external to the devtool workspace. The source files for the new release exist adjacent to the same location pointed to by SRC_URI in the recipe (e.g. a tarball with the new version number in the name, or as a different revision in the upstream Git repository). A common situation is where third-party software has undergone a revision so that it has been upgraded. The recipe you have access to is likely in your own layer. Thus, you need to upgrade the recipe to use the newer version of the software: $ devtool upgrade -V version recipe By default, the devtool upgrade command extracts source code into the sources directory in the workspace. If you want the code extracted to any other location, you need to provide the srctree positional argument with the command as follows: $ devtool upgrade -V version recipe srctree Also, in this example, the "-V" option is used to specify the new version. If the source files pointed to by the SRC_URI statement in the recipe are in a Git repository, you must provide the "-S" option and specify a revision for the software. Once devtool locates the recipe, it uses the SRC_URI variable to locate the source code and any local patch files from other developers are located. The result is that the command sets up the source code, the new version of the recipe, and an append file all within the workspace. Resolve any Conflicts created by the Upgrade: At this point, there could be some conflicts due to the software being upgraded to a new version. This would occur if your recipe specifies some patch files in SRC_URI that conflict with changes made in the new version of the software. If this is the case, you need to resolve the conflicts by editing the source and following the normal git rebase conflict resolution process. Before moving onto the next step, be sure to resolve any such conflicts created through use of a newer or different version of the software. Build the Recipe: Once you have your recipe in order, you can build it. You can either use devtool build or bitbake. Either method produces build output that is stored in TMPDIR. 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. 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. 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. If you specify a destination layer that is the same as the original source, then the old version of the recipe and associated files will be removed prior to adding the new version. $ devtool finish recipe layer Any changes you want to turn into patches must be committed to the Git repository in the source tree. 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. 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.

Quilt is a powerful tool that allows you to capture source code changes without having a clean source tree. This section outlines the typical workflow you can use to modify source code, test changes, and then preserve the changes in the form of a patch all using Quilt. With regard to preserving changes to source files if you clean a recipe or have rm_work enabled, the workflow described in the "Using devtool in Your Workflow" section is a safer development flow than than the flow that uses Quilt. Follow these general steps: Find the Source Code: Temporary source code used by the OpenEmbedded build system is kept in the Build Directory. See the "Finding Temporary Source Code" section to learn how to locate the directory that has the temporary source code for a particular package. Change Your Working Directory: You need to be in the directory that has the temporary source code. That directory is defined by the S variable. Create a New Patch: Before modifying source code, you need to create a new patch. To create a new patch file, use quilt new as below: $ quilt new my_changes.patch Notify Quilt and Add Files: After creating the patch, you need to notify Quilt about the files you plan to edit. You notify Quilt by adding the files to the patch you just created: $ quilt add file1.c file2.c file3.c Edit the Files: Make your changes in the source code to the files you added to the patch. Test Your Changes: Once you have modified the source code, the easiest way to your changes is by calling the do_compile task as shown in the following example: $ bitbake -c compile -f package The -f or --force option forces the specified task to execute. If you find problems with your code, you can just keep editing and re-testing iteratively until things work as expected. All the modifications you make to the temporary source code disappear once you run the do_clean or do_cleanall tasks using BitBake (i.e. bitbake -c clean package and bitbake -c cleanall package). Modifications will also disappear if you use the rm_work feature as described in the "Building Images" section of the Yocto Project Quick Start. Generate the Patch: Once your changes work as expected, you need to use Quilt to generate the final patch that contains all your modifications. $ quilt refresh At this point, the my_changes.patch file has all your edits made to the file1.c, file2.c, and file3.c files. You can find the resulting patch file in the patches/ subdirectory of the source (S) directory. Copy the Patch File: For simplicity, copy the patch file into a directory named files, which you can create in the same directory that holds the recipe (.bb) file or the append (.bbappend) file. Placing the patch here guarantees that the OpenEmbedded build system will find the patch. Next, add the patch into the SRC_URI of the recipe. Here is an example: SRC_URI += "file://my_changes.patch"

You might find it helpful during development to modify the temporary source code used by recipes to build packages. For example, suppose you are developing a patch and you need to experiment a bit to figure out your solution. After you have initially built the package, you can iteratively tweak the source code, which is located in the Build Directory, and then you can force a re-compile and quickly test your altered code. Once you settle on a solution, you can then preserve your changes in the form of patches. If you are using Quilt for development, see the "Using Quilt in Your Workflow" section for more information. During a build, the unpacked temporary source code used by recipes to build packages is available in the Build Directory as defined by the S variable. Below is the default value for the S variable as defined in the meta/conf/bitbake.conf configuration file in the Source Directory: S = "${WORKDIR}/${BP}" You should be aware that many recipes override the S variable. For example, recipes that fetch their source from Git usually set S to ${WORKDIR}/git. The BP represents the base recipe name, which consists of the name and version: BP = "${BPN}-${PV}" The path to the work directory for the recipe (WORKDIR) is defined as follows: ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR} The actual directory depends on several things: TMPDIR: The top-level build output directory MULTIMACH_TARGET_SYS: The target system identifier PN: The recipe name EXTENDPE: The epoch - (if PE is not specified, which is usually the case for most recipes, then EXTENDPE is blank) PV: The recipe version PR: The recipe revision As an example, assume a Source Directory top-level folder named poky, a default Build Directory at poky/build, and a qemux86-poky-linux machine target system. Furthermore, suppose your recipe is named foo_1.3.0.bb. In this case, the work directory the build system uses to build the package would be as follows: poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0 Now that you know where to locate the directory that has the temporary source code, you can use a Quilt as described in section "Using Quilt in Your Workflow" to make your edits, test the changes, and preserve the changes in the form of patches.

Toaster is a web interface to the Yocto Project's OpenEmbedded build system. You can initiate builds using Toaster as well as examine the results and statistics of builds. See the Toaster User Manual for information on how to set up and use Toaster to build images.

When debugging certain commands or even when just editing packages, devshell can be a useful tool. When you invoke devshell, all tasks up to and including do_patch are run for the specified target. Then, a new terminal is opened and you are placed in ${S}, the source directory. In the new terminal, all the OpenEmbedded build-related environment variables are still defined so you can use commands such as configure and make. The commands execute just as if the OpenEmbedded build system were executing them. Consequently, working this way can be helpful when debugging a build or preparing software to be used with the OpenEmbedded build system. Following is an example that uses devshell on a target named matchbox-desktop: $ bitbake matchbox-desktop -c devshell This command spawns a terminal with a shell prompt within the OpenEmbedded build environment. The OE_TERMINAL variable controls what type of shell is opened. For spawned terminals, the following occurs: The PATH variable includes the cross-toolchain. The pkgconfig variables find the correct .pc files. The configure command finds the Yocto Project site files as well as any other necessary files. Within this environment, you can run configure or compile commands as if they were being run by the OpenEmbedded build system itself. As noted earlier, the working directory also automatically changes to the Source Directory (S). To manually run a specific task using devshell, run the corresponding run.* script in the ${WORKDIR}/temp directory (e.g., run.do_configure.pid). If a task's script does not exist, which would be the case if the task was skipped by way of the sstate cache, you can create the task by first running it outside of the devshell: $ bitbake -c task Execution of a task's run.* script and BitBake's execution of a task are identical. In other words, running the script re-runs the task just as it would be run using the bitbake -c command. Any run.* file that does not have a .pid extension is a symbolic link (symlink) to the most recent version of that file. Remember, that the devshell is a mechanism that allows you to get into the BitBake task execution environment. And as such, all commands must be called just as BitBake would call them. That means you need to provide the appropriate options for cross-compilation and so forth as applicable. When you are finished using devshell, exit the shell or close the terminal window. It is worth remembering that when using devshell you need to use the full compiler name such as arm-poky-linux-gnueabi-gcc instead of just using gcc. The same applies to other applications such as binutils, libtool and so forth. BitBake sets up environment variables such as CC to assist applications, such as make to find the correct tools. It is also worth noting that devshell still works over X11 forwarding and similar situations.

Similar to working within a development shell as described in the previous section, you can also spawn and work within an interactive Python development shell. When debugging certain commands or even when just editing packages, devpyshell can be a useful tool. When you invoke devpyshell, all tasks up to and including do_patch are run for the specified target. Then a new terminal is opened. Additionally, key Python objects and code are available in the same way they are to BitBake tasks, in particular, the data store 'd'. So, commands such as the following are useful when exploring the data store and running functions: pydevshell> d.getVar("STAGING_DIR", True) '/media/build1/poky/build/tmp/sysroots' pydevshell> d.getVar("STAGING_DIR", False) '${TMPDIR}/sysroots' pydevshell> d.setVar("FOO", "bar") pydevshell> d.getVar("FOO", True) 'bar' pydevshell> d.delVar("FOO") pydevshell> d.getVar("FOO", True) pydevshell> bb.build.exec_func("do_unpack", d) pydevshell> The commands execute just as if the OpenEmbedded build system were executing them. Consequently, working this way can be helpful when debugging a build or preparing software to be used with the OpenEmbedded build system. Following is an example that uses devpyshell on a target named matchbox-desktop: $ bitbake matchbox-desktop -c devpyshell This command spawns a terminal and places you in an interactive Python interpreter within the OpenEmbedded build environment. The OE_TERMINAL variable controls what type of shell is opened. When you are finished using devpyshell, you can exit the shell either by using Ctrl+d or closing the terminal window.