diff options
Diffstat (limited to 'yocto-poky/documentation/dev-manual/dev-manual-model.xml')
| -rw-r--r-- | yocto-poky/documentation/dev-manual/dev-manual-model.xml | 2195 |
1 files changed, 0 insertions, 2195 deletions
diff --git a/yocto-poky/documentation/dev-manual/dev-manual-model.xml b/yocto-poky/documentation/dev-manual/dev-manual-model.xml deleted file mode 100644 index ff44a3f68..000000000 --- a/yocto-poky/documentation/dev-manual/dev-manual-model.xml +++ /dev/null @@ -1,2195 +0,0 @@ -<!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> |