diff options
Diffstat (limited to 'import-layers/yocto-poky/documentation/dev-manual/dev-manual-model.xml')
| -rw-r--r-- | import-layers/yocto-poky/documentation/dev-manual/dev-manual-model.xml | 2195 |
1 files changed, 2195 insertions, 0 deletions
diff --git a/import-layers/yocto-poky/documentation/dev-manual/dev-manual-model.xml b/import-layers/yocto-poky/documentation/dev-manual/dev-manual-model.xml new file mode 100644 index 000000000..ff44a3f68 --- /dev/null +++ b/import-layers/yocto-poky/documentation/dev-manual/dev-manual-model.xml @@ -0,0 +1,2195 @@ +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" +[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > + +<chapter id='dev-manual-model'> + +<title>Common Development Models</title> + +<para> + 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: + <itemizedlist> + <listitem><para><emphasis>System Development:</emphasis> + System Development covers Board Support Package (BSP) development + and kernel modification or configuration. + For an example on how to create a BSP, see the + "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>" + 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 + <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>. + </para></listitem> + <listitem><para><emphasis>User Application Development:</emphasis> + 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 + <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>. + For a simple example of user-space application development using + the <trademark class='trade'>Eclipse</trademark> IDE, see the + "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-developing-applications-using-eclipse'>Developing Applications Using <trademark class='trade'>Eclipse</trademark></ulink>" section. + </para></listitem> + <listitem><para><emphasis>Temporary Source Code Modification:</emphasis> + 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. + </para></listitem> + <listitem><para><emphasis>Image Development using Toaster:</emphasis> + You can use <ulink url='&YOCTO_HOME_URL;/Tools-resources/projects/toaster'>Toaster</ulink> + 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. + </para></listitem> + <listitem><para><emphasis>Using a Development Shell:</emphasis> + You can use a + <link linkend='platdev-appdev-devshell'><filename>devshell</filename></link> + 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. + </para></listitem> + </itemizedlist> +</para> + +<section id='system-development-model'> + <title>System Development Workflow</title> + + <para> + 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. + </para> + + <para> + 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. + </para> + + <section id='developing-a-board-support-package-bsp'> + <title>Developing a Board Support Package (BSP)</title> + + <para> + 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. + </para> + + <note> + For a brief list of terms used when describing the development process in the Yocto Project, + see the "<link linkend='yocto-project-terms'>Yocto Project Terms</link>" section. + </note> + + <para> + The remainder of this section presents the basic + steps used to create a BSP using the Yocto Project's + <ulink url='&YOCTO_DOCS_BSP_URL;#using-the-yocto-projects-bsp-tools'>BSP Tools</ulink>. + Although not required for BSP creation, the + <filename>meta-intel</filename> repository, which contains + many BSPs supported by the Yocto Project, is part of the example. + </para> + + <para> + For an example that shows how to create a new layer using the tools, see the + "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>" + section in the Yocto Project Board Support Package (BSP) Developer's Guide. + </para> + + <para> + The following illustration and list summarize the BSP creation general workflow. + </para> + + <para> + <imagedata fileref="figures/bsp-dev-flow.png" width="6in" depth="7in" align="center" scalefit="1" /> + </para> + + <para> + <orderedlist> + <listitem><para><emphasis>Set up your host development system to support + development using the Yocto Project</emphasis>: See the + "<ulink url='&YOCTO_DOCS_QS_URL;#the-linux-distro'>The Linux Distribution</ulink>" + and the + "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Build Host Packages</ulink>" sections both + in the Yocto Project Quick Start for requirements.</para></listitem> + <listitem><para><emphasis>Establish a local copy of the project files on your + system</emphasis>: You need this <link linkend='source-directory'>Source + Directory</link> 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 + "<link linkend='getting-setup'>Getting Set Up</link>" section.</para></listitem> + <listitem><para><emphasis>Establish the <filename>meta-intel</filename> + repository on your system</emphasis>: 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 + "<link linkend='getting-setup'>Getting Set Up</link>" section.</para></listitem> + <listitem><para><emphasis>Create your own BSP layer using the + <ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'><filename>yocto-bsp</filename></ulink> script</emphasis>: + 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 <filename>yocto-bsp</filename> script. + For information about that script, see the + "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>" + section in the Yocto Project Board Support (BSP) Developer's Guide. + </para> + + <para> + 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 + "<link linkend='understanding-and-creating-layers'>Understanding and Creating Layers</link>" + section. + For more information on BSP layers, see the + "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>" + section in the Yocto Project Board Support Package (BSP) + Developer's Guide. + <note> + <para> + Five BSPs exist that are part of the Yocto Project release: + <filename>beaglebone</filename> (ARM), + <filename>mpc8315e</filename> (PowerPC), + and <filename>edgerouter</filename> (MIPS). + The recipes and configurations for these five BSPs + are located and dispersed within the + <link linkend='source-directory'>Source Directory</link>. + </para> + + <para> + Three core Intel BSPs exist as part of the Yocto + Project release in the + <filename>meta-intel</filename> layer: + <itemizedlist> + <listitem><para><filename>intel-core2-32</filename>, + which is a BSP optimized for the Core2 family of CPUs + as well as all CPUs prior to the Silvermont core. + </para></listitem> + <listitem><para><filename>intel-corei7-64</filename>, + 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. + </para></listitem> + <listitem><para><filename>intel-quark</filename>, + which is a BSP optimized for the Intel Galileo + gen1 & gen2 development boards. + </para></listitem> + </itemizedlist> + </para> + </note> + </para> + + <para>When you set up a layer for a new BSP, you should follow a standard layout. + This layout is described in the + "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout'>Example Filesystem Layout</ulink>" + 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 <filename>meta-intel</filename> layer inside + the Source Directory.</para></listitem> + <listitem><para><emphasis>Make configuration changes to your new BSP + layer</emphasis>: The standard BSP layer structure organizes the files you need + to edit in <filename>conf</filename> and several <filename>recipes-*</filename> + 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 <filename>yocto-bsp</filename> script, you are able to interactively + configure many things for the BSP (e.g. keyboard, touchscreen, and so forth). + </para></listitem> + <listitem><para><emphasis>Make recipe changes to your new BSP layer</emphasis>: Recipe + changes include altering recipes (<filename>.bb</filename> files), removing + recipes you do not use, and adding new recipes or append files + (<filename>.bbappend</filename>) that you need to support your hardware. + </para></listitem> + <listitem><para><emphasis>Prepare for the build</emphasis>: 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. <filename>oe-init-build-env</filename> or + <filename>oe-init-build-env-memres</filename>) + and you need to be sure two key configuration files are configured appropriately: + the <filename>conf/local.conf</filename> and the + <filename>conf/bblayers.conf</filename> file. + You must make the OpenEmbedded build system aware of your new layer. + See the + "<link linkend='enabling-your-layer'>Enabling Your Layer</link>" section + for information on how to let the build system know about your new layer.</para> + <para>The entire process for building an image is overviewed in the section + "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>" section + of the Yocto Project Quick Start. + You might want to reference this information.</para></listitem> + <listitem><para><emphasis>Build the image</emphasis>: 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 + <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>. + </para> + <para>The build process supports several types of images to satisfy different needs. + See the + "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter + in the Yocto Project Reference Manual for information on + supported images.</para></listitem> + </orderedlist> + </para> + + <para> + You can view a video presentation on "Building Custom Embedded Images with Yocto" + at <ulink url='http://free-electrons.com/blog/elc-2011-videos'>Free Electrons</ulink>. + After going to the page, just search for "Embedded". + You can also find supplemental information in the + <ulink url='&YOCTO_DOCS_BSP_URL;'> + Yocto Project Board Support Package (BSP) Developer's Guide</ulink>. + Finally, there is helpful material and links on this + <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'>wiki page</ulink>. + Although a bit dated, you might find the information on the wiki + helpful. + </para> + </section> + + <section id='modifying-the-kernel'> + <title><anchor id='kernel-spot' />Modifying the Kernel</title> + + <para> + 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 <filename>recipes-kernel</filename> area + in a kernel layer you create. + </para> + + <para> + 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 + "<link linkend='patching-the-kernel'>Patching the Kernel</link>" section + for an example that changes the source code of the kernel. + For information on how to configure the kernel, see the + "<link linkend='configuring-the-kernel'>Configuring the Kernel</link>" section. + For more information on the kernel and on modifying the kernel, see the + <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>. + </para> + + <section id='kernel-overview'> + <title>Kernel Overview</title> + + <para> + 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. + </para> + + <para> + You can find a web interface to the Yocto Project kernel source repositories at + <ulink url='&YOCTO_GIT_URL;'></ulink>. + 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: + <itemizedlist> + <listitem><para><emphasis> + <filename>linux-yocto-3.14</filename></emphasis> - 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. + </para></listitem> + <listitem><para><emphasis> + <filename>linux-yocto-3.17</filename></emphasis> - 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. + </para></listitem> + <listitem><para><emphasis> + <filename>linux-yocto-3.19</filename></emphasis> - 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. + </para></listitem> + <listitem><para><emphasis> + <filename>linux-yocto-4.1</filename></emphasis> - 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. + </para></listitem> + <listitem><para><emphasis> + <filename>linux-yocto-4.4</filename></emphasis> - 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. + </para></listitem> + <listitem><para><emphasis> + <filename>linux-yocto-dev</filename></emphasis> - A + development kernel based on the latest upstream release + candidate available. + </para></listitem> + </itemizedlist> + <note> + Long Term Support Initiative (LTSI) for Yocto Project kernels + is as follows: + <itemizedlist> + <listitem><para>For Yocto Project releases 1.7, 1.8, and 2.0, + the LTSI kernel is <filename>linux-yocto-3.14</filename>. + </para></listitem> + <listitem><para>For Yocto Project release 2.1, the + LTSI kernel is <filename>linux-yocto-4.1</filename>. + </para></listitem> + </itemizedlist> + </note> + </para> + + <para> + 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: + <para> + <imagedata fileref="figures/kernel-overview-1.png" + width="6in" depth="6in" align="center" scale="100" /> + </para> + + <para> + 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 <filename>linux-yocto-3.19</filename> + kernel. + Thus, everything further to the right in the structure is based on the + <filename>linux-yocto-3.19</filename> kernel. + Branch points to the right in the figure represent where the + <filename>linux-yocto-3.19</filename> 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. + </para> + + <para> + 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. + </para> + + <note> + 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. + </note> + + <para> + 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. + </para> + + <para> + 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 + "<link linkend='local-kernel-files'>Yocto Project Kernel</link>" + bulleted item earlier in the manual. + </para> + + <para> + 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 + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> 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. + </para> + The following figure shows the temporary file structure + created on your host system when the build occurs. + This + <link linkend='build-directory'>Build Directory</link> contains all the + source files used during the build. + </para> + + <para> + <imagedata fileref="figures/kernel-overview-2-generic.png" + width="6in" depth="5in" align="center" scale="100" /> + </para> + + <para> + Again, for additional information on the Yocto Project kernel's + architecture and its branching strategy, see the + <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>. + You can also reference the + "<link linkend='patching-the-kernel'>Patching the Kernel</link>" + section for a detailed example that modifies the kernel. + </para> + </section> + + <section id='kernel-modification-workflow'> + <title>Kernel Modification Workflow</title> + + <para> + This illustration and the following list summarizes the kernel modification general workflow. + </para> + + <para> + <imagedata fileref="figures/kernel-dev-flow.png" + width="6in" depth="5in" align="center" scalefit="1" /> + </para> + + <para> + <orderedlist> + <listitem><para><emphasis>Set up your host development system to support + development using the Yocto Project</emphasis>: See + "<ulink url='&YOCTO_DOCS_QS_URL;#the-linux-distro'>The Linux Distribution</ulink>" and + "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Build Host Packages</ulink>" sections both + in the Yocto Project Quick Start for requirements.</para></listitem> + <listitem><para><emphasis>Establish a local copy of project files on your + system</emphasis>: Having the <link linkend='source-directory'>Source + Directory</link> 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 + "<link linkend='local-yp-release'>Yocto Project Release</link>" earlier in this manual. + </para></listitem> + <listitem><para><emphasis>Establish the temporary kernel source files</emphasis>: + Temporary kernel source files are kept in the + <link linkend='build-directory'>Build Directory</link> + 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.</para> + <para>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. <filename>oe-init-build-env</filename> or + <filename>oe-init-build-env-memres</filename>). + You also need to be sure two key configuration files + (<filename>local.conf</filename> and <filename>bblayers.conf</filename>) + are configured appropriately.</para> + <para>The entire process for building an image is overviewed in the + "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>" + section of the Yocto Project Quick Start. + You might want to reference this information. + You can find more information on BitBake in the + <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>. + </para> + <para>The build process supports several types of images to satisfy different needs. + See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter in + the Yocto Project Reference Manual for information on supported images. + </para></listitem> + <listitem><para><emphasis>Make changes to the kernel source code if + applicable</emphasis>: 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.</para></listitem> + <listitem><para><emphasis>Make kernel configuration changes if applicable</emphasis>: + If your situation calls for changing the kernel's + configuration, you can use + <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#generating-configuration-files'><filename>menuconfig</filename></ulink>, + which allows you to interactively develop and test the + configuration changes you are making to the kernel. + Saving changes you make with + <filename>menuconfig</filename> updates + the kernel's <filename>.config</filename> file. + <note><title>Warning</title> + Try to resist the temptation to directly edit an + existing <filename>.config</filename> file, which is + found in the Build Directory at + <filename>tmp/sysroots/<replaceable>machine-name</replaceable>/kernel</filename>. + Doing so, can produce unexpected results when the + OpenEmbedded build system regenerates the configuration + file. + </note> + Once you are satisfied with the configuration + changes made using <filename>menuconfig</filename> + and you have saved them, you can directly compare the + resulting <filename>.config</filename> file against an + existing original and gather those changes into a + <link linkend='creating-config-fragments'>configuration fragment file</link> + to be referenced from within the kernel's + <filename>.bbappend</filename> file.</para> + + <para>Additionally, if you are working in a BSP layer + and need to modify the BSP's kernel's configuration, + you can use the + <ulink url='&YOCTO_DOCS_BSP_URL;#managing-kernel-patches-and-config-items-with-yocto-kernel'><filename>yocto-kernel</filename></ulink> + script as well as <filename>menuconfig</filename>. + The <filename>yocto-kernel</filename> script lets + you interactively set up kernel configurations. + </para></listitem> + <listitem><para><emphasis>Rebuild the kernel image with your changes</emphasis>: + Rebuilding the kernel image applies your changes. + </para></listitem> + </orderedlist> + </para> + </section> + </section> +</section> + +<section id='application-development-workflow-using-an-sdk'> + <title>Application Development Workflow Using an SDK</title> + + <para> + 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 + <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-intro'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>. + </para> +</section> + +<section id="dev-modifying-source-code"> + <title>Modifying Source Code</title> + + <para> + 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. + </para> + + <para> + 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: + <itemizedlist> + <listitem><para><emphasis><filename>devtool</filename>:</emphasis> + A set of tools to aid in working on the source code built by + the OpenEmbedded build system. + Section + "<link linkend='using-devtool-in-your-workflow'>Using <filename>devtool</filename> in Your Workflow</link>" + describes this workflow. + If you want more information that showcases the workflow, click + <ulink url='https://drive.google.com/a/linaro.org/file/d/0B3KGzY5fW7laTDVxUXo3UDRvd2s/view'>here</ulink> + for a presentation by Trevor Woerner that, while somewhat dated, + provides detailed background information and a complete + working tutorial. + </para></listitem> + <listitem><para><emphasis><ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink>:</emphasis> + 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 + "<link linkend='using-a-quilt-workflow'>Using Quilt in Your Workflow</link>" + section for more information. + </para></listitem> + </itemizedlist> + </para> + + <section id='using-devtool-in-your-workflow'> + <title>Using <filename>devtool</filename> in Your Workflow</title> + + <para> + As mentioned earlier, <filename>devtool</filename> helps + you easily develop projects whose build output must be part of + an image built using the OpenEmbedded build system. + </para> + + <para> + Three entry points exist that allow you to develop using + <filename>devtool</filename>: + <itemizedlist> + <listitem><para><emphasis><filename>devtool add</filename></emphasis> + </para></listitem> + <listitem><para><emphasis><filename>devtool modify</filename></emphasis> + </para></listitem> + <listitem><para><emphasis><filename>devtool upgrade</filename></emphasis> + </para></listitem> + </itemizedlist> + </para> + + <para> + The remainder of this section presents these workflows. + </para> + + <section id='use-devtool-to-integrate-new-code'> + <title>Use <filename>devtool add</filename> to Integrate New Code</title> + + <para> + The <filename>devtool add</filename> command generates + a new recipe based on existing source code. + This command takes advantage of the + <link linkend='devtool-the-workspace-layer-structure'>workspace</link> + layer that many <filename>devtool</filename> 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. + </para> + + <para> + Depending on your particular scenario, the arguments and options + you use with <filename>devtool add</filename> form different + combinations. + The following diagram shows common development flows + you would use with the <filename>devtool add</filename> + command: + </para> + + <para> + <imagedata fileref="figures/devtool-add-flow.png" align="center" /> + </para> + + <para> + <orderedlist> + <listitem><para><emphasis>Generating the New Recipe</emphasis>: + The top part of the flow shows three scenarios by which + you could use <filename>devtool add</filename> to + generate a recipe based on existing source code.</para> + + <para>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.</para> + + <para>Within the diagram, three possible scenarios + feed into the <filename>devtool add</filename> workflow: + <itemizedlist> + <listitem><para><emphasis>Left</emphasis>: + 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: + <literallayout class='monospaced'> + $ devtool add <replaceable>recipe fetchuri</replaceable> + </literallayout> + With this command, <filename>devtool</filename> + 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 <filename>sources</filename> folder. + </para></listitem> + <listitem><para><emphasis>Middle</emphasis>: + 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. + As always, if required <filename>devtool</filename> creates + a Git repository locally during the extraction. + Furthermore, the first positional argument + <replaceable>srctree</replaceable> in this case + identifies where the + <filename>devtool add</filename> command + will locate the extracted code outside of the + workspace: + <literallayout class='monospaced'> + $ devtool add <replaceable>recipe srctree fetchuri</replaceable> + </literallayout> + In summary, the source code is pulled from + <replaceable>fetchuri</replaceable> and extracted + into the location defined by + <replaceable>srctree</replaceable> as a local + Git repository.</para> + + <para>Within workspace, <filename>devtool</filename> + creates both the recipe and an append file + for the recipe. + </para></listitem> + <listitem><para><emphasis>Right</emphasis>: + The right scenario represents a situation + where the source tree (srctree) has been + previously prepared outside of the + <filename>devtool</filename> workspace. + </para> + + <para>The following command names the recipe + and identifies where the existing source tree + is located: + <literallayout class='monospaced'> + $ devtool add <replaceable>recipe srctree</replaceable> + </literallayout> + The command examines the source code and creates + a recipe for it placing the recipe into the + workspace.</para> + + <para>Because the extracted source code already exists, + <filename>devtool</filename> does not try to + relocate it into the workspace - just the new + the recipe is placed in the workspace.</para> + + <para>Aside from a recipe folder, the command + also creates an append folder and places an initial + <filename>*.bbappend</filename> within. + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para><emphasis>Edit the Recipe</emphasis>: + At this point, you can use <filename>devtool edit-recipe</filename> + to open up the editor as defined by the + <filename>$EDITOR</filename> environment variable + and modify the file: + <literallayout class='monospaced'> + $ devtool edit-recipe <replaceable>recipe</replaceable> + </literallayout> + From within the editor, you can make modifications to the + recipe that take affect when you build it later. + </para></listitem> + <listitem><para><emphasis>Build the Recipe or Rebuild the Image</emphasis>: + At this point in the flow, the next step you + take depends on what you are going to do with + the new code.</para> + <para>If you need to take the build output and eventually + move it to the target hardware, you would use + <filename>devtool build</filename>: + <note> + You could use <filename>bitbake</filename> to build + the recipe as well. + </note> + <literallayout class='monospaced'> + $ devtool build <replaceable>recipe</replaceable> + </literallayout></para> + <para>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 <filename>devtool build-image</filename> command: + <literallayout class='monospaced'> + $ devtool build-image <replaceable>image</replaceable> + </literallayout> + </para></listitem> + <listitem><para><emphasis>Deploy the Build Output</emphasis>: + When you use the <filename>devtool build</filename> + 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. + </note> + You can deploy your build output to that target hardware by + using the <filename>devtool deploy-target</filename> command: + <literallayout class='monospaced'> + $ devtool deploy-target <replaceable>recipe target</replaceable> + </literallayout> + The <replaceable>target</replaceable> is a live target machine + running as an SSH server.</para> + + <para>You can, of course, also deploy the image you build + using the <filename>devtool build-image</filename> command + to actual hardware. + However, <filename>devtool</filename> does not provide a + specific command that allows you to do this. + </para></listitem> + <listitem><para><emphasis>Optionally Update the Recipe With Patch Files</emphasis>: + 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 + <filename>devtool</filename> uses. + This optional step is especially relevant if you are + using or adding third-party software.</para> + <para>To convert commits created using Git to patch files, + use the <filename>devtool update-recipe</filename> command. + <note> + Any changes you want to turn into patches must be + committed to the Git repository in the source tree. + </note> + <literallayout class='monospaced'> + $ devtool update-recipe <replaceable>recipe</replaceable> + </literallayout> + </para></listitem> + <listitem><para><emphasis>Move the Recipe to its Permanent Layer</emphasis>: + Before cleaning up the workspace, you need to move the + final recipe to its permanent layer. + You must do this before using the + <filename>devtool reset</filename> command if you want to + retain the recipe. + </para></listitem> + <listitem><para><emphasis>Reset the Recipe</emphasis>: + 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 <filename>devtool reset</filename> + command: + <literallayout class='monospaced'> + $ devtool reset <replaceable>recipe</replaceable> + </literallayout> + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='devtool-use-devtool-modify-to-enable-work-on-code-associated-with-an-existing-recipe'> + <title>Use <filename>devtool modify</filename> to Enable Work on Code Associated with an Existing Recipe</title> + + <para> + The <filename>devtool modify</filename> 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. + </para> + + <para> + Depending on your particular scenario, the arguments and options + you use with <filename>devtool modify</filename> form different + combinations. + The following diagram shows common development flows + you would use with the <filename>devtool modify</filename> + command: + </para> + + <para> + <imagedata fileref="figures/devtool-modify-flow.png" align="center" /> + </para> + + <para> + <orderedlist> + <listitem><para><emphasis>Preparing to Modify the Code</emphasis>: + The top part of the flow shows three scenarios by which + you could use <filename>devtool modify</filename> to + prepare to work on source files. + Each scenario assumes the following: + <itemizedlist> + <listitem><para>The recipe exists in some layer external + to the <filename>devtool</filename> workspace. + </para></listitem> + <listitem><para>The source files exist upstream in an + un-extracted state or locally in a previously + extracted state. + </para></listitem> + </itemizedlist> + 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. + <itemizedlist> + <listitem><para><emphasis>Left</emphasis>: + 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. + <filename>meta-</filename><replaceable>layername</replaceable>). + </para> + + <para>The following command identifies the recipe + and by default extracts the source files: + <literallayout class='monospaced'> + $ devtool modify <replaceable>recipe</replaceable> + </literallayout> + Once <filename>devtool</filename>locates the recipe, + it uses the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + variable to locate the source code and + any local patch files from other developers are + located. + <note> + You cannot provide an URL for + <replaceable>srctree</replaceable> when using the + <filename>devtool modify</filename> command. + </note> + With this scenario, however, since no + <replaceable>srctree</replaceable> argument exists, the + <filename>devtool modify</filename> 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. + </para></listitem> + <listitem><para><emphasis>Middle</emphasis>: + 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.</para> + + <para>The following command tells + <filename>devtool</filename> 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: + <literallayout class='monospaced'> + $ devtool modify <replaceable>recipe srctree</replaceable> + </literallayout> + As with all extractions, the command uses + the recipe's <filename>SRC_URI</filename> to locate the + source files. + Once the files are located, the command by default + extracts them. + Providing the <replaceable>srctree</replaceable> + argument instructs <filename>devtool</filename> where + place the extracted source.</para> + + <para>Within workspace, <filename>devtool</filename> + 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 <replaceable>srctree</replaceable>. + </para></listitem> + <listitem><para><emphasis>Right</emphasis>: + The right scenario represents a situation + where the source tree + (<replaceable>srctree</replaceable>) exists as a + previously extracted Git structure outside of + the <filename>devtool</filename> workspace. + In this example, the recipe also exists + elsewhere in its own layer. + </para> + + <para>The following command tells + <filename>devtool</filename> the recipe + with which to work, uses the "-n" option to indicate + source does not need to be extracted, and uses + <replaceable>srctree</replaceable> to point to the + previously extracted source files: + <literallayout class='monospaced'> + $ devtool modify -n <replaceable>recipe srctree</replaceable> + </literallayout> + </para> + + <para>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. + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para><emphasis>Edit the Source</emphasis>: + Once you have used the <filename>devtool modify</filename> + 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. + </para></listitem> + <listitem><para><emphasis>Build the Recipe</emphasis>: + Once you have updated the source files, you can build + the recipe. + You can either use <filename>devtool build</filename> or + <filename>bitbake</filename>. + Either method produces build output that is stored + in + <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>. + </para></listitem> + <listitem><para><emphasis>Deploy the Build Output</emphasis>: + When you use the <filename>devtool build</filename> + command or <filename>bitbake</filename> 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. + </note> + You can deploy your build output to that target hardware by + using the <filename>devtool deploy-target</filename> command: + <literallayout class='monospaced'> + $ devtool deploy-target <replaceable>recipe target</replaceable> + </literallayout> + The <replaceable>target</replaceable> is a live target machine + running as an SSH server.</para> + + <para>You can, of course, also deploy the image you build + using the <filename>devtool build-image</filename> command + to actual hardware. + However, <filename>devtool</filename> does not provide a + specific command that allows you to do this. + </para></listitem> + <listitem><para><emphasis>Optionally Create Patch Files for Your Changes</emphasis>: + After you have debugged your changes, you can + use <filename>devtool update-recipe</filename> to + generate patch files for all the commits you have + made. + <note> + Patch files are generated only for changes + you have committed. + </note> + <literallayout class='monospaced'> + $ devtool update-recipe <replaceable>recipe</replaceable> + </literallayout> + By default, the + <filename>devtool update-recipe</filename> 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 + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + statement to point to the generated patch files. + <note> + You can use the + "--append <replaceable>LAYERDIR</replaceable>" + option to cause the command to create append files + in a specific layer rather than the default + recipe layer. + </note> + </para></listitem> + <listitem><para><emphasis>Restore the Workspace</emphasis>: + The <filename>devtool reset</filename> restores the + state so that standard layers and upstream sources are + used to build the recipe rather than what is in the + workspace. + <literallayout class='monospaced'> + $ devtool reset <replaceable>recipe</replaceable> + </literallayout> + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='devtool-use-devtool-upgrade-to-create-a-version-of-the-recipe-that-supports-a-newer-version-of-the-software'> + <title>Use <filename>devtool upgrade</filename> to Create a Version of the Recipe that Supports a Newer Version of the Software</title> + + <para> + The <filename>devtool upgrade</filename> 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 <filename>devtool</filename> workspace, and + work with any source file forms that the fetchers support. + </para> + + <para> + Depending on your particular scenario, the arguments and options + you use with <filename>devtool upgrade</filename> form different + combinations. + The following diagram shows a common development flow + you would use with the <filename>devtool modify</filename> + command: + </para> + + <para> + <imagedata fileref="figures/devtool-upgrade-flow.png" align="center" /> + </para> + + <para> + <orderedlist> + <listitem><para><emphasis>Initiate the Upgrade</emphasis>: + The top part of the flow shows a typical scenario by which + you could use <filename>devtool upgrade</filename>. + The following conditions exist: + <itemizedlist> + <listitem><para>The recipe exists in some layer external + to the <filename>devtool</filename> workspace. + </para></listitem> + <listitem><para>The source files for the new release + exist adjacent to the same location pointed to by + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + 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). + </para></listitem> + </itemizedlist> + 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: + <literallayout class='monospaced'> + $ devtool upgrade -V <replaceable>version recipe</replaceable> + </literallayout> + By default, the <filename>devtool upgrade</filename> command + extracts source code into the <filename>sources</filename> + directory in the workspace. + If you want the code extracted to any other location, you + need to provide the <replaceable>srctree</replaceable> + positional argument with the command as follows: + <literallayout class='monospaced'> + $ devtool upgrade -V <replaceable>version recipe srctree</replaceable> + </literallayout> + Also, in this example, the "-V" option is used to specify + the new version. + If the source files pointed to by the + <filename>SRC_URI</filename> statement in the recipe are + in a Git repository, you must provide the "-S" option and + specify a revision for the software.</para> + + <para>Once <filename>devtool</filename> locates the recipe, + it uses the <filename>SRC_URI</filename> 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. + </para></listitem> + <listitem><para><emphasis>Resolve any Conflicts created by the Upgrade</emphasis>: + 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 + <filename>SRC_URI</filename> 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 + <filename>git rebase</filename> conflict resolution + process.</para> + + <para>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. + </para></listitem> + <listitem><para><emphasis>Build the Recipe</emphasis>: + Once you have your recipe in order, you can build it. + You can either use <filename>devtool build</filename> or + <filename>bitbake</filename>. + Either method produces build output that is stored + in + <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>. + </para></listitem> + <listitem><para><emphasis>Deploy the Build Output</emphasis>: + When you use the <filename>devtool build</filename> + command or <filename>bitbake</filename> 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. + </note> + You can deploy your build output to that target hardware by + using the <filename>devtool deploy-target</filename> command: + <literallayout class='monospaced'> + $ devtool deploy-target <replaceable>recipe target</replaceable> + </literallayout> + The <replaceable>target</replaceable> is a live target machine + running as an SSH server.</para> + + <para>You can, of course, also deploy the image you build + using the <filename>devtool build-image</filename> command + to actual hardware. + However, <filename>devtool</filename> does not provide a + specific command that allows you to do this. + </para></listitem> + <listitem><para><emphasis>Optionally Create Patch Files for Your Changes</emphasis>: + After you have debugged your changes, you can + use <filename>devtool update-recipe</filename> to + generate patch files for all the commits you have + made. + <note> + Patch files are generated only for changes + you have committed. + </note> + <literallayout class='monospaced'> + $ devtool update-recipe <replaceable>recipe</replaceable> + </literallayout> + By default, the + <filename>devtool update-recipe</filename> 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 + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + statement to point to the generated patch files. + </para></listitem> + <listitem><para><emphasis>Move the Recipe to its Permanent Layer</emphasis>: + Before cleaning up the workspace, you need to move the + final recipe to its permanent layer. + You can either overwrite the original recipe or you can + overlay the upgraded recipe into a separate layer. + You must do this before using the + <filename>devtool reset</filename> command if you want to + retain the upgraded recipe. + </para></listitem> + <listitem><para><emphasis>Restore the Workspace</emphasis>: + The <filename>devtool reset</filename> restores the + state so that standard layers and upstream sources are + used to build the recipe rather than what is in the + workspace. + <literallayout class='monospaced'> + $ devtool reset <replaceable>recipe</replaceable> + </literallayout> + </para></listitem> + </orderedlist> + </para> + </section> + </section> + + <section id='devtool-quick-reference'> + <title><filename>devtool</filename> Quick Reference</title> + + <para> + <filename>devtool</filename> has more functionality than simply + adding a new recipe and the supporting Metadata to a temporary + workspace layer. + This section provides a short reference on + <filename>devtool</filename> and its commands. + </para> + + <section id='devtool-getting-help'> + <title>Getting Help</title> + + <para> + The easiest way to get help with the + <filename>devtool</filename> command is using the + <filename>--help</filename> option: + <literallayout class='monospaced'> + usage: devtool [--basepath BASEPATH] [--bbpath BBPATH] [-d] [-q] + [--color COLOR] [-h] + <subcommand> ... + + OpenEmbedded development tool + + optional arguments: + --basepath BASEPATH Base directory of SDK / build directory + --bbpath BBPATH Explicitly specify the BBPATH, rather than getting it + from the metadata + -d, --debug Enable debug output + -q, --quiet Print only errors + --color COLOR Colorize output (where COLOR is auto, always, never) + -h, --help show this help message and exit + + subcommands: + Beginning work on a recipe: + add Add a new recipe + modify Modify the source for an existing recipe + upgrade Upgrade an existing recipe + Getting information: + status Show workspace status + search Search available recipes + Working on a recipe in the workspace: + build Build a recipe + edit-recipe Edit a recipe file in your workspace + configure-help Get help on configure script options + update-recipe Apply changes from external source tree to recipe + reset Remove a recipe from your workspace + Testing changes on target: + deploy-target Deploy recipe output files to live target machine + undeploy-target Undeploy recipe output files in live target machine + build-image Build image including workspace recipe packages + Advanced: + create-workspace Set up workspace in an alternative location + extract Extract the source for an existing recipe + sync Synchronize the source tree for an existing recipe + Use devtool <subcommand> --help to get help on a specific command + </literallayout> + </para> + + <para> + As directed in the general help output, you can get more + syntax on a specific command by providing the command + name and using <filename>--help</filename>: + <literallayout class='monospaced'> + $ devtool add --help + usage: devtool add [-h] [--same-dir | --no-same-dir] [--fetch URI] + [--version VERSION] [--no-git] [--binary] [--also-native] + [--src-subdir SUBDIR] + [recipename] [srctree] [fetchuri] + + Adds a new recipe to the workspace to build a specified source tree. Can + optionally fetch a remote URI and unpack it to create the source tree. + + positional arguments: + recipename Name for new recipe to add (just name - no version, + path or extension). If not specified, will attempt to + auto-detect it. + srctree Path to external source tree. If not specified, a + subdirectory of + /home/scottrif/poky/build/workspace/sources will be + used. + fetchuri Fetch the specified URI and extract it to create the + source tree + + optional arguments: + -h, --help show this help message and exit + --same-dir, -s Build in same directory as source + --no-same-dir Force build in a separate build directory + --fetch URI, -f URI Fetch the specified URI and extract it to create the + source tree (deprecated - pass as positional argument + instead) + --version VERSION, -V VERSION + Version to use within recipe (PV) + --no-git, -g If fetching source, do not set up source tree as a git + repository + --binary, -b Treat the source tree as something that should be + installed verbatim (no compilation, same directory + structure). Useful with binary packages e.g. RPMs. + --also-native Also add native variant (i.e. support building recipe + for the build host as well as the target machine) + --src-subdir SUBDIR Specify subdirectory within source tree to use + </literallayout> + </para> + </section> + + <section id='devtool-the-workspace-layer-structure'> + <title>The Workspace Layer Structure</title> + + <para> + <filename>devtool</filename> uses a "Workspace" layer + in which to accomplish builds. + This layer is not specific to any single + <filename>devtool</filename> command but is rather a common + working area used across the tool. + </para> + + <para> + The following figure shows the workspace structure: + </para> + + <para> + <imagedata fileref="figures/build-workspace-directory.png" + width="6in" depth="5in" align="left" scale="70" /> + </para> + + <para> + <literallayout class='monospaced'> + attic - A directory created if devtool believes it preserve + anything when you run "devtool reset". For example, if you + run "devtool add", make changes to the recipe, and then + run "devtool reset", devtool takes notice that the file has + been changed and moves it into the attic should you still + want the recipe. + + README - Provides information on what is in workspace layer and how to + manage it. + + .devtool_md5 - A checksum file used by devtool. + + appends - A directory that contains *.bbappend files, which point to + external source. + + conf - A configuration directory that contains the layer.conf file. + + recipes - A directory containing recipes. This directory contains a + folder for each directory added whose name matches that of the + added recipe. devtool places the <replaceable>recipe</replaceable>.bb file + within that sub-directory. + + sources - A directory containing a working copy of the source files used + when building the recipe. This is the default directory used + as the location of the source tree when you do not provide a + source tree path. This directory contains a folder for each + set of source files matched to a corresponding recipe. + </literallayout> + </para> + </section> + + <section id='devtool-adding-a-new-recipe-to-the-workspace'> + <title>Adding a New Recipe to the Workspace Layer</title> + + <para> + Use the <filename>devtool add</filename> command to add a new recipe + to the workspace layer. + The recipe you add should not exist - + <filename>devtool</filename> creates it for you. + The source files the recipe uses should exist in an external + area. + </para> + + <para> + The following example creates and adds a new recipe named + <filename>jackson</filename> to a workspace layer the tool creates. + The source code built by the recipes resides in + <filename>/home/scottrif/sources/jackson</filename>: + <literallayout class='monospaced'> + $ devtool add jackson /home/scottrif/sources/jackson + </literallayout> + </para> + + <para> + If you add a recipe and the workspace layer does not exist, + the command creates the layer and populates it as + described in + "<link linkend='devtool-the-workspace-layer-structure'>The Workspace Layer Structure</link>" + section. + </para> + + <para> + Running <filename>devtool add</filename> when the + workspace layer exists causes the tool to add the recipe, + append files, and source files into the existing workspace layer. + The <filename>.bbappend</filename> file is created to point + to the external source tree. + </para> + </section> + + <section id='devtool-extracting-the-source-for-an-existing-recipe'> + <title>Extracting the Source for an Existing Recipe</title> + + <para> + Use the <filename>devtool extract</filename> command to + extract the source for an existing recipe. + When you use this command, you must supply the root name + of the recipe (i.e. no version, paths, or extensions), and + you must supply the directory to which you want the source + extracted. + </para> + + <para> + Additional command options let you control the name of a + development branch into which you can checkout the source + and whether or not to keep a temporary directory, which is + useful for debugging. + </para> + </section> + + <section id='devtool-synchronizing-a-recipes-extracted-source-tree'> + <title>Synchronizing a Recipe's Extracted Source Tree</title> + + <para> + Use the <filename>devtool sync</filename> command to + synchronize a previously extracted source tree for an + existing recipe. + When you use this command, you must supply the root name + of the recipe (i.e. no version, paths, or extensions), and + you must supply the directory to which you want the source + extracted. + </para> + + <para> + Additional command options let you control the name of a + development branch into which you can checkout the source + and whether or not to keep a temporary directory, which is + useful for debugging. + </para> + </section> + + <section id='devtool-modifying-a-recipe'> + <title>Modifying an Existing Recipe</title> + + <para> + Use the <filename>devtool modify</filename> command to begin + modifying the source of an existing recipe. + This command is very similar to the + <link linkend='devtool-adding-a-new-recipe-to-the-workspace'><filename>add</filename></link> + command except that it does not physically create the + recipe in the workspace layer because the recipe already + exists in an another layer. + </para> + + <para> + The <filename>devtool modify</filename> command extracts the + source for a recipe, sets it up as a Git repository if the + source had not already been fetched from Git, checks out a + branch for development, and applies any patches from the recipe + as commits on top. + You can use the following command to checkout the source + files: + <literallayout class='monospaced'> + $ devtool modify <replaceable>recipe</replaceable> + </literallayout> + Using the above command form, <filename>devtool</filename> uses + the existing recipe's + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + statement to locate the upstream source, extracts the source + into the default sources location in the workspace. + The default development branch used is "devtool". + </para> + </section> + + <section id='devtool-edit-an-existing-recipe'> + <title>Edit an Existing Recipe</title> + + <para> + Use the <filename>devtool edit-recipe</filename> command + to run the default editor, which is identified using the + <filename>EDITOR</filename> variable, on the specified recipe. + </para> + + <para> + When you use the <filename>devtool edit-recipe</filename> + command, you must supply the root name of the recipe + (i.e. no version, paths, or extensions). + Also, the recipe file itself must reside in the workspace + as a result of the <filename>devtool add</filename> or + <filename>devtool upgrade</filename> commands. + However, you can override that requirement by using the + "-a" or "--any-recipe" option. + Using either of these options allows you to edit any recipe + regardless of its location. + </para> + </section> + + <section id='devtool-updating-a-recipe'> + <title>Updating a Recipe</title> + + <para> + Use the <filename>devtool update-recipe</filename> command to + update your recipe with patches that reflect changes you make + to the source files. + For example, if you know you are going to work on some + code, you could first use the + <link linkend='devtool-modifying-a-recipe'><filename>devtool modify</filename></link> + command to extract the code and set up the workspace. + After which, you could modify, compile, and test the code. + </para> + + <para> + When you are satisfied with the results and you have committed + your changes to the Git repository, you can then + run the <filename>devtool update-recipe</filename> to create the + patches and update the recipe: + <literallayout class='monospaced'> + $ devtool update-recipe <replaceable>recipe</replaceable> + </literallayout> + If you run the <filename>devtool update-recipe</filename> + without committing your changes, the command ignores the + changes. + </para> + + <para> + Often, you might want to apply customizations made to your + software in your own layer rather than apply them to the + original recipe. + If so, you can use the + <filename>-a</filename> or <filename>--append</filename> + option with the <filename>devtool update-recipe</filename> + command. + These options allow you to specify the layer into which to + write an append file: + <literallayout class='monospaced'> + $ devtool update-recipe <replaceable>recipe</replaceable> -a <replaceable>base-layer-directory</replaceable> + </literallayout> + The <filename>*.bbappend</filename> file is created at the + appropriate path within the specified layer directory, which + may or may not be in your <filename>bblayers.conf</filename> + file. + If an append file already exists, the command updates it + appropriately. + </para> + </section> + + <section id='devtool-upgrading-a-recipe'> + <title>Upgrading a Recipe</title> + + <para> + Use the <filename>devtool upgrade</filename> command + to upgrade an existing recipe to a new upstream version. + The command puts the upgraded recipe file into the + workspace along with any associated files, and extracts + the source tree to a specified location should patches + need rebased or added to as a result of the upgrade. + </para> + + <para> + When you use the <filename>devtool upgrade</filename> command, + you must supply the root name of the recipe (i.e. no version, + paths, or extensions), and you must supply the directory + to which you want the source extracted. + Additional command options let you control things such as + the version number to which you want to upgrade (i.e. the + <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>), + the source revision to which you want to upgrade (i.e. the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>, + whether or not to apply patches, and so forth. + </para> + </section> + + <section id='devtool-resetting-a-recipe'> + <title>Resetting a Recipe</title> + + <para> + Use the <filename>devtool reset</filename> command to remove a + recipe and its configuration (e.g. the corresponding + <filename>.bbappend</filename> file) from the workspace layer. + Realize that this command deletes the recipe and the + append file. + The command does not physically move them for you. + Consequently, you must be sure to physically relocate your + updated recipe and the append file outside of the workspace + layer before running the <filename>devtool reset</filename> + command. + </para> + + <para> + If the <filename>devtool reset</filename> command detects that + the recipe or the append files have been modified, the + command preserves the modified files in a separate "attic" + subdirectory under the workspace layer. + </para> + + <para> + Here is an example that resets the workspace directory that + contains the <filename>mtr</filename> recipe: + <literallayout class='monospaced'> + $ devtool reset mtr + NOTE: Cleaning sysroot for recipe mtr... + NOTE: Leaving source tree /home/scottrif/poky/build/workspace/sources/mtr as-is; if you no + longer need it then please delete it manually + $ + </literallayout> + </para> + </section> + + <section id='devtool-building-your-recipe'> + <title>Building Your Recipe</title> + + <para> + Use the <filename>devtool build</filename> command to cause the + OpenEmbedded build system to build your recipe. + The <filename>devtool build</filename> command is equivalent to + <filename>bitbake -c populate_sysroot</filename>. + </para> + + <para> + When you use the <filename>devtool build</filename> command, + you must supply the root name of the recipe (i.e. no version, + paths, or extensions). + You can use either the "-s" or the "--disable-parallel-make" + option to disable parallel makes during the build. + Here is an example: + <literallayout class='monospaced'> + $ devtool build <replaceable>recipe</replaceable> + </literallayout> + </para> + </section> + + <section id='devtool-building-your-image'> + <title>Building Your Image</title> + + <para> + Use the <filename>devtool build-image</filename> command + to build an image, extending it to include packages from + recipes in the workspace. + Using this command is useful when you want an image that + ready for immediate deployment onto a device for testing. + For proper integration into a final image, you need to + edit your custom image recipe appropriately. + </para> + + <para> + When you use the <filename>devtool build-image</filename> + command, you must supply the name of the image. + This command has no command line options: + <literallayout class='monospaced'> + $ devtool build-image <replaceable>image</replaceable> + </literallayout> + </para> + </section> + + <section id='devtool-deploying-your-software-on-the-target-machine'> + <title>Deploying Your Software on the Target Machine</title> + + <para> + Use the <filename>devtool deploy-target</filename> command to + deploy the recipe's build output to the live target machine: + <literallayout class='monospaced'> + $ devtool deploy-target <replaceable>recipe</replaceable> <replaceable>target</replaceable> + </literallayout> + The <replaceable>target</replaceable> is the address of the + target machine, which must be running an SSH server (i.e. + <filename>user@hostname[:destdir]</filename>). + </para> + + <para> + This command deploys all files installed during the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink> + task. + Furthermore, you do not need to have package management enabled + within the target machine. + If you do, the package manager is bypassed. + <note><title>Notes</title> + <para> + The <filename>deploy-target</filename> + functionality is for development only. + You should never use it to update an image that will be + used in production. + </para> + </note> + </para> + </section> + + <section id='devtool-removing-your-software-from-the-target-machine'> + <title>Removing Your Software from the Target Machine</title> + + <para> + Use the <filename>devtool undeploy-target</filename> command to + remove deployed build output from the target machine. + For the <filename>devtool undeploy-target</filename> command to + work, you must have previously used the + <link linkend='devtool-deploying-your-software-on-the-target-machine'><filename>devtool deploy-target</filename></link> + command. + <literallayout class='monospaced'> + $ devtool undeploy-target <replaceable>recipe</replaceable> <replaceable>target</replaceable> + </literallayout> + The <replaceable>target</replaceable> is the address of the + target machine, which must be running an SSH server (i.e. + <filename>user@hostname</filename>). + </para> + </section> + + <section id='devtool-creating-the-workspace'> + <title>Creating the Workspace Layer in an Alternative Location</title> + + <para> + Use the <filename>devtool create-workspace</filename> command to + create a new workspace layer in your + <link linkend='build-directory'>Build Directory</link>. + When you create a new workspace layer, it is populated with the + <filename>README</filename> file and the + <filename>conf</filename> directory only. + </para> + + <para> + The following example creates a new workspace layer in your + current working and by default names the workspace layer + "workspace": + <literallayout class='monospaced'> + $ devtool create-workspace + </literallayout> + </para> + + <para> + You can create a workspace layer anywhere by supplying + a pathname with the command. + The following command creates a new workspace layer named + "new-workspace": + <literallayout class='monospaced'> + $ devtool create-workspace /home/scottrif/new-workspace + </literallayout> + </para> + </section> + + <section id='devtool-get-the-status-of-the-recipes-in-your-workspace'> + <title>Get the Status of the Recipes in Your Workspace</title> + + <para> + Use the <filename>devtool status</filename> command to + list the recipes currently in your workspace. + Information includes the paths to their respective + external source trees. + </para> + + <para> + The <filename>devtool status</filename> command has no + command-line options: + <literallayout class='monospaced'> + devtool status + </literallayout> + Following is sample output after using + <link linkend='devtool-adding-a-new-recipe-to-the-workspace'><filename>devtool add</filename></link> + to create and add the <filename>mtr_0.86.bb</filename> recipe + to the <filename>workspace</filename> directory: + <literallayout class='monospaced'> + $ devtool status + mtr: /home/scottrif/poky/build/workspace/sources/mtr (/home/scottrif/poky/build/workspace/recipes/mtr/mtr_0.86.bb) + $ + </literallayout> + </para> + </section> + + <section id='devtool-search-for-available-target-recipes'> + <title>Search for Available Target Recipes</title> + + <para> + Use the <filename>devtool search</filename> command to + search for available target recipes. + The command matches the recipe name, package name, + description, and installed files. + The command displays the recipe name as a result of a + match. + </para> + + <para> + When you use the <filename>devtool search</filename> command, + you must supply a <replaceable>keyword</replaceable>. + The command uses the <replaceable>keyword</replaceable> when + searching for a match. + </para> + </section> + </section> + + <section id="using-a-quilt-workflow"> + <title>Using Quilt in Your Workflow</title> + + <para> + <ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink> + 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. + <note><title>Tip</title> + With regard to preserving changes to source files if you + clean a recipe or have <filename>rm_work</filename> enabled, + the workflow described in the + "<link linkend='using-devtool-in-your-workflow'>Using <filename>devtool</filename> in Your Workflow</link>" + section is a safer development flow than than the flow that + uses Quilt. + </note> + </para> + + <para> + Follow these general steps: + <orderedlist> + <listitem><para><emphasis>Find the Source Code:</emphasis> + Temporary source code used by the OpenEmbedded build system + is kept in the + <link linkend='build-directory'>Build Directory</link>. + See the + "<link linkend='finding-the-temporary-source-code'>Finding Temporary Source Code</link>" + section to learn how to locate the directory that has the + temporary source code for a particular package. + </para></listitem> + <listitem><para><emphasis>Change Your Working Directory:</emphasis> + You need to be in the directory that has the temporary source code. + That directory is defined by the + <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink> + variable.</para></listitem> + <listitem><para><emphasis>Create a New Patch:</emphasis> + Before modifying source code, you need to create a new patch. + To create a new patch file, use <filename>quilt new</filename> as below: + <literallayout class='monospaced'> + $ quilt new my_changes.patch + </literallayout></para></listitem> + <listitem><para><emphasis>Notify Quilt and Add Files:</emphasis> + 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: + <literallayout class='monospaced'> + $ quilt add file1.c file2.c file3.c + </literallayout> + </para></listitem> + <listitem><para><emphasis>Edit the Files:</emphasis> + Make your changes in the source code to the files you added + to the patch. + </para></listitem> + <listitem><para><emphasis>Test Your Changes:</emphasis> + Once you have modified the source code, the easiest way to + your changes is by calling the + <filename>do_compile</filename> task as shown in the + following example: + <literallayout class='monospaced'> + $ bitbake -c compile -f <replaceable>package</replaceable> + </literallayout> + The <filename>-f</filename> or <filename>--force</filename> + 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. + <note>All the modifications you make to the temporary source code + disappear once you run the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-clean'><filename>do_clean</filename></ulink> + or + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleanall'><filename>do_cleanall</filename></ulink> + tasks using BitBake (i.e. + <filename>bitbake -c clean <replaceable>package</replaceable></filename> + and + <filename>bitbake -c cleanall <replaceable>package</replaceable></filename>). + Modifications will also disappear if you use the <filename>rm_work</filename> + feature as described in the + "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>" + section of the Yocto Project Quick Start. + </note></para></listitem> + <listitem><para><emphasis>Generate the Patch:</emphasis> + Once your changes work as expected, you need to use Quilt to generate the final patch that + contains all your modifications. + <literallayout class='monospaced'> + $ quilt refresh + </literallayout> + At this point, the <filename>my_changes.patch</filename> file has all your edits made + to the <filename>file1.c</filename>, <filename>file2.c</filename>, and + <filename>file3.c</filename> files.</para> + <para>You can find the resulting patch file in the <filename>patches/</filename> + subdirectory of the source (<filename>S</filename>) directory.</para></listitem> + <listitem><para><emphasis>Copy the Patch File:</emphasis> + For simplicity, copy the patch file into a directory named <filename>files</filename>, + which you can create in the same directory that holds the recipe + (<filename>.bb</filename>) file or the + append (<filename>.bbappend</filename>) file. + Placing the patch here guarantees that the OpenEmbedded build system will find + the patch. + Next, add the patch into the + <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename> + of the recipe. + Here is an example: + <literallayout class='monospaced'> + SRC_URI += "file://my_changes.patch" + </literallayout></para></listitem> + </orderedlist> + </para> + </section> + + <section id='finding-the-temporary-source-code'> + <title>Finding Temporary Source Code</title> + + <para> + 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 + <link linkend='build-directory'>Build Directory</link>, 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 + "<link linkend='using-a-quilt-workflow'>Using Quilt in Your Workflow</link>" + section for more information. + </para> + + <para> + During a build, the unpacked temporary source code used by recipes + to build packages is available in the Build Directory as + defined by the + <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename> variable. + Below is the default value for the <filename>S</filename> variable as defined in the + <filename>meta/conf/bitbake.conf</filename> configuration file in the + <link linkend='source-directory'>Source Directory</link>: + <literallayout class='monospaced'> + S = "${WORKDIR}/${BP}" + </literallayout> + You should be aware that many recipes override the <filename>S</filename> variable. + For example, recipes that fetch their source from Git usually set + <filename>S</filename> to <filename>${WORKDIR}/git</filename>. + <note> + The + <ulink url='&YOCTO_DOCS_REF_URL;#var-BP'><filename>BP</filename></ulink> + represents the base recipe name, which consists of the name and version: + <literallayout class='monospaced'> + BP = "${BPN}-${PV}" + </literallayout> + </note> + </para> + + <para> + The path to the work directory for the recipe + (<ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>) + is defined as follows: + <literallayout class='monospaced'> + ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR} + </literallayout> + The actual directory depends on several things: + <itemizedlist> + <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>: + The top-level build output directory</listitem> + <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></ulink>: + The target system identifier</listitem> + <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>: + The recipe name</listitem> + <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTENDPE'><filename>EXTENDPE</filename></ulink>: + The epoch - (if + <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink> + is not specified, which is usually the case for most + recipes, then <filename>EXTENDPE</filename> is blank)</listitem> + <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>: + The recipe version</listitem> + <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>: + The recipe revision</listitem> + </itemizedlist> + </para> + + <para> + As an example, assume a Source Directory top-level folder + named <filename>poky</filename>, a default Build Directory at + <filename>poky/build</filename>, and a + <filename>qemux86-poky-linux</filename> machine target + system. + Furthermore, suppose your recipe is named + <filename>foo_1.3.0.bb</filename>. + In this case, the work directory the build system uses to + build the package would be as follows: + <literallayout class='monospaced'> + poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0 + </literallayout> + </para> + + <para> + Now that you know where to locate the directory that has the + temporary source code, you can use a Quilt as described in section + "<link linkend='using-a-quilt-workflow'>Using Quilt in Your Workflow</link>" + to make your edits, test the changes, and preserve the changes in + the form of patches. + </para> + </section> +</section> + +<section id='image-development-using-toaster'> + <title>Image Development Using Toaster</title> + + <para> + 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 + <ulink url='&YOCTO_DOCS_TOAST_URL;#toaster-manual-intro'>Toaster User Manual</ulink> + for information on how to set up and use Toaster to build images. + </para> +</section> + +<section id="platdev-appdev-devshell"> + <title>Using a Development Shell</title> + + <para> + When debugging certain commands or even when just editing packages, + <filename>devshell</filename> can be a useful tool. + When you invoke <filename>devshell</filename>, all tasks up to and + including + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-patch'><filename>do_patch</filename></ulink> + are run for the specified target. + Then, a new terminal is opened and you are placed in + <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink><filename>}</filename>, + the source directory. + In the new terminal, all the OpenEmbedded build-related environment variables are + still defined so you can use commands such as <filename>configure</filename> and + <filename>make</filename>. + 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. + </para> + + <para> + Following is an example that uses <filename>devshell</filename> on a target named + <filename>matchbox-desktop</filename>: + <literallayout class='monospaced'> + $ bitbake matchbox-desktop -c devshell + </literallayout> + </para> + + <para> + This command spawns a terminal with a shell prompt within the OpenEmbedded build environment. + The <ulink url='&YOCTO_DOCS_REF_URL;#var-OE_TERMINAL'><filename>OE_TERMINAL</filename></ulink> + variable controls what type of shell is opened. + </para> + + <para> + For spawned terminals, the following occurs: + <itemizedlist> + <listitem><para>The <filename>PATH</filename> variable includes the + cross-toolchain.</para></listitem> + <listitem><para>The <filename>pkgconfig</filename> variables find the correct + <filename>.pc</filename> files.</para></listitem> + <listitem><para>The <filename>configure</filename> command finds the + Yocto Project site files as well as any other necessary files.</para></listitem> + </itemizedlist> + </para> + + <para> + 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 (<ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>). + </para> + + <para> + To manually run a specific task using <filename>devshell</filename>, + run the corresponding <filename>run.*</filename> script in + the + <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/temp</filename> + directory (e.g., + <filename>run.do_configure.</filename><replaceable>pid</replaceable>). + 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 <filename>devshell</filename>: + <literallayout class='monospaced'> + $ bitbake -c <replaceable>task</replaceable> + </literallayout> + <note><title>Notes</title> + <itemizedlist> + <listitem><para>Execution of a task's <filename>run.*</filename> + 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 + <filename>bitbake -c</filename> command. + </para></listitem> + <listitem><para>Any <filename>run.*</filename> file that does not + have a <filename>.pid</filename> extension is a + symbolic link (symlink) to the most recent version of that + file. + </para></listitem> + </itemizedlist> + </note> + </para> + + <para> + Remember, that the <filename>devshell</filename> 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. + </para> + + <para> + When you are finished using <filename>devshell</filename>, exit the shell + or close the terminal window. + </para> + + <note><title>Notes</title> + <itemizedlist> + <listitem><para> + It is worth remembering that when using <filename>devshell</filename> + you need to use the full compiler name such as <filename>arm-poky-linux-gnueabi-gcc</filename> + instead of just using <filename>gcc</filename>. + The same applies to other applications such as <filename>binutils</filename>, + <filename>libtool</filename> and so forth. + BitBake sets up environment variables such as <filename>CC</filename> + to assist applications, such as <filename>make</filename> to find the correct tools. + </para></listitem> + <listitem><para> + It is also worth noting that <filename>devshell</filename> still works over + X11 forwarding and similar situations. + </para></listitem> + </itemizedlist> + </note> +</section> + +</chapter> |
