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 | 1654 |
1 files changed, 0 insertions, 1654 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 deleted file mode 100644 index 1008e1169..000000000 --- a/import-layers/yocto-poky/documentation/dev-manual/dev-manual-model.xml +++ /dev/null @@ -1,1654 +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. - See the - "<ulink url='&YOCTO_DOCS_REF_URL;#ref-devtool-reference'><filename>devtool</filename> Quick Reference</ulink>" - in the Yocto Project Reference Manual for a - <filename>devtool</filename> quick reference. - </para> - - <section id='use-devtool-to-integrate-new-code'> - <title>Use <filename>devtool add</filename> to Add an Application</title> - - <para> - The <filename>devtool add</filename> command generates - a new recipe based on existing source code. - This command takes advantage of the - <ulink url='&YOCTO_DOCS_DEV_URL;#devtool-the-workspace-layer-structure'>workspace</ulink> - 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. - If required, <filename>devtool</filename> - always 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>: - <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>Finish Your Work With the Recipe</emphasis>: - The <filename>devtool finish</filename> command creates - any patches corresponding to commits in the local - Git repository, moves the new recipe to a more permanent - layer, and then resets the recipe so that the recipe is - built normally rather than from the workspace. - <literallayout class='monospaced'> - $ devtool finish <replaceable>recipe layer</replaceable> - </literallayout> - <note> - Any changes you want to turn into patches must be - committed to the Git repository in the source tree. - </note></para> - - <para>As mentioned, the <filename>devtool finish</filename> - command moves the final recipe to its permanent layer. - </para> - - <para>As a final process of the - <filename>devtool finish</filename> command, the state - of the standard layers and the upstream source is - restored so that you can build the recipe from those - areas rather than the workspace. - <note> - You can use the <filename>devtool reset</filename> - command to put things back should you decide you - do not want to proceed with your work. - If you do use this command, realize that the source - tree is preserved. - </note> - </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 Modify the Source of an Existing Component</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. - </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>Finish Your Work With the Recipe</emphasis>: - The <filename>devtool finish</filename> command creates - any patches corresponding to commits in the local - Git repository, updates the recipe to point to them - (or creates a <filename>.bbappend</filename> file to do - so, depending on the specified destination layer), and - then resets the recipe so that the recipe is built normally - rather than from the workspace. - <literallayout class='monospaced'> - $ devtool finish <replaceable>recipe layer</replaceable> - </literallayout> - <note> - Any changes you want to turn into patches must be - committed to the Git repository in the source tree. - </note></para> - - <para>Because there is no need to move the recipe, - <filename>devtool finish</filename> either updates the - original recipe in the original layer or the command - creates a <filename>.bbappend</filename> in a different - layer as provided by <replaceable>layer</replaceable>. - </para> - - <para>As a final process of the - <filename>devtool finish</filename> command, the state - of the standard layers and the upstream source is - restored so that you can build the recipe from those - areas rather than the workspace. - <note> - You can use the <filename>devtool reset</filename> - command to put things back should you decide you - do not want to proceed with your work. - If you do use this command, realize that the source - tree is preserved. - </note> - </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>Finish Your Work With the Recipe</emphasis>: - The <filename>devtool finish</filename> command creates - any patches corresponding to commits in the local - Git repository, moves the new recipe to a more permanent - layer, and then resets the recipe so that the recipe is - built normally rather than from the workspace. - If you specify a destination layer that is the same as - the original source, then the old version of the - recipe and associated files will be removed prior to - adding the new version. - <literallayout class='monospaced'> - $ devtool finish <replaceable>recipe layer</replaceable> - </literallayout> - <note> - Any changes you want to turn into patches must be - committed to the Git repository in the source tree. - </note></para> - <para>As a final process of the - <filename>devtool finish</filename> command, the state - of the standard layers and the upstream source is - restored so that you can build the recipe from those - areas rather than the workspace. - <note> - You can use the <filename>devtool reset</filename> - command to put things back should you decide you - do not want to proceed with your work. - If you do use this command, realize that the source - tree is preserved. - </note> - </para></listitem> - </orderedlist> - </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> - -<section id="platdev-appdev-devpyshell"> - <title>Using a Development Python Shell</title> - - <para> - Similar to working within a development shell as described in - the previous section, you can also spawn and work within an - interactive Python development shell. - When debugging certain commands or even when just editing packages, - <filename>devpyshell</filename> can be a useful tool. - When you invoke <filename>devpyshell</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. - Additionally, key Python objects and code are available in the same - way they are to BitBake tasks, in particular, the data store 'd'. - So, commands such as the following are useful when exploring the data - store and running functions: - <literallayout class='monospaced'> - pydevshell> d.getVar("STAGING_DIR", True) - '/media/build1/poky/build/tmp/sysroots' - pydevshell> d.getVar("STAGING_DIR", False) - '${TMPDIR}/sysroots' - pydevshell> d.setVar("FOO", "bar") - pydevshell> d.getVar("FOO", True) - 'bar' - pydevshell> d.delVar("FOO") - pydevshell> d.getVar("FOO", True) - pydevshell> bb.build.exec_func("do_unpack", d) - pydevshell> - </literallayout> - 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>devpyshell</filename> on a target named - <filename>matchbox-desktop</filename>: - <literallayout class='monospaced'> - $ bitbake matchbox-desktop -c devpyshell - </literallayout> - </para> - - <para> - This command spawns a terminal and places you in an interactive - Python interpreter 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> - When you are finished using <filename>devpyshell</filename>, you - can exit the shell either by using Ctrl+d or closing the terminal - window. - </para> -</section> - -</chapter> |