diff options
Diffstat (limited to 'documentation')
| -rw-r--r-- | documentation/dev-manual/dev-manual-common-tasks.xml | 173 | ||||
| -rw-r--r-- | documentation/dev-manual/dev-manual-intro.xml | 35 | ||||
| -rw-r--r-- | documentation/dev-manual/dev-manual-kernel-appendix.xml | 92 | ||||
| -rw-r--r-- | documentation/dev-manual/dev-manual-model.xml | 137 | ||||
| -rw-r--r-- | documentation/dev-manual/dev-manual-newbie.xml | 199 | ||||
| -rw-r--r-- | documentation/dev-manual/dev-manual-start.xml | 72 |
6 files changed, 320 insertions, 388 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index 067b5dfcc2..f326dc5209 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -7,7 +7,7 @@ <title>Common Tasks</title> <para> This chapter describes standard tasks such as adding new - software packages, extending or customizing images, and porting the Yocto Project to + software packages, extending or customizing images, and porting work to new hardware (adding a new machine). The chapter also describes how to combine multiple versions of library files into a single image, how to handle a package name alias, and @@ -18,7 +18,7 @@ <title>Understanding and Creating Layers</title> <para> - The Yocto Project build system supports organizing <link linkend='metadata'>metadata</link> + The OpenEmbedded build system supports organizing <link linkend='metadata'>metadata</link> into multiple layers. Layers allow you to isolate different types of customizations from each other. You might find it tempting to keep everything in one layer when working on a single project. @@ -43,13 +43,13 @@ </para> <section id='yocto-project-layers'> - <title>Yocto Project Layers</title> + <title>Layers</title> <para> - The Yocto Project contains several layers right out of the box. - You can easily identify a layer in the Yocto Project by the name of its folder. + The source directory contains several layers right out of the box. + You can easily identify a layer in the source directory by its folder name. Folders that are layers begin with the string <filename>meta</filename>. - For example, when you set up the <link linkend='yocto-project-files'>Yocto Project Files</link> + For example, when you set up the <link linkend='source-directory'>source directory</link> structure, you will see several layers: <filename>meta</filename>, <filename>meta-demoapps</filename>, <filename>meta-skeleton</filename>, and <filename>meta-yocto</filename>. Each of these folders is a layer. @@ -69,7 +69,7 @@ <title>Creating Your Own Layer</title> <para> - It is very easy to create your own layer to use with the Yocto Project. + It is very easy to create your own layer to use with the OpenEmbedded build system. Follow these general steps to create your layer: <orderedlist> <listitem><para><emphasis>Check Existing Layers:</emphasis> Before creating a new layer, @@ -170,13 +170,14 @@ If this is the case, you need to address that deficiency instead of overlaying the include file. For example, consider how Qt 4 database support plugins are configured. - The Yocto Project does not have MySQL or PostgreSQL, however OpenEmbedded's + The source directory does not have + MySQL or PostgreSQL, however OpenEmbedded's layer <filename>meta-oe</filename> does. Consequently, <filename>meta-oe</filename> uses <filename>.bbappend</filename> files to modify the <filename>QT_SQL_DRIVER_FLAGS</filename> variable to enable the appropriate plugins. This variable was added to the <filename>qt4.inc</filename> include file in - The Yocto Project specifically to allow the <filename>meta-oe</filename> layer + the source directory specifically to allow the <filename>meta-oe</filename> layer to be able to control which plugins are built.</para></listitem> </itemizedlist> </para> @@ -187,10 +188,10 @@ <listitem><para>Store custom layers in a Git repository that uses the <filename>meta-<layer_name></filename> format.</para></listitem> <listitem><para>Clone the repository alongside other <filename>meta</filename> - directories in - <link linkend='yocto-project-files'>Yocto Project Files</link>.</para></listitem> + directories in the + <link linkend='source-directory'>source directory</link>.</para></listitem> </itemizedlist> - Following these recommendations keeps your Yocto Project files area and + Following these recommendations keeps your source directory and its configuration entirely inside the Yocto Project's core base. </para> </section> @@ -199,11 +200,11 @@ <title>Enabling Your Layer</title> <para> - Before the Yocto Project build system can use your new layer, you need to enable it. + Before the OpenEmbedded build system can use your new layer, you need to enable it. To enable your layer, simply add your layer's path to the <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'>BBLAYERS</ulink></filename> variable in your <filename>conf/bblayers.conf</filename> file, which is found in the - <link linkend='yocto-project-build-directory'>Yocto Project Build Directory</link>. + <link linkend='build-directory'>build directory</link>. The following example shows how to enable a layer named <filename>meta-mylayer</filename>: <literallayout class='monospaced'> LCONF_VERSION = "1" @@ -222,8 +223,8 @@ <filename>BBLAYERS</filename> variable within the <filename>conf/bblayers.conf</filename> file. During the processing of each <filename>conf/layer.conf</filename> file, BitBake adds the - recipes, classes and configurations contained within the particular layer to the Yocto - Project. + recipes, classes and configurations contained within the particular layer to the source + directory. </para> </section> @@ -267,7 +268,7 @@ <para> As an example, consider the main formfactor recipe and a corresponding formfactor append file both from the - <link linkend='yocto-project-files'>Yocto Project Files</link>. + <link linkend='source-directory'>source directory</link>. Here is the main formfactor recipe, which is named <filename>formfactor_0.0.bb</filename> and located in the meta layer at <filename>meta/recipes-bsp/formfactor</filename>: <literallayout class='monospaced'> @@ -450,7 +451,7 @@ <title>Customizing Images</title> <para> - You can customize Yocto Project images to satisfy particular requirements. + You can customize images to satisfy particular requirements. This section describes several methods and provides guidelines for each. </para> @@ -552,13 +553,11 @@ <filename>EXTRA_IMAGE_FEATURES</filename></title> <para> - Ultimately users might want to add extra image features to the set used by - Yocto Project with the + Ultimately users might want to add extra image features to the set by using the <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'>IMAGE_FEATURES</ulink></filename> variable. To create these features, the best reference is - <filename>meta/classes/core-image.bbclass</filename>, which shows how the - Yocto Project achieves this. + <filename>meta/classes/core-image.bbclass</filename>, which shows how to achieve this. In summary, the file looks at the contents of the <filename>IMAGE_FEATURES</filename> variable and then maps that into a set of tasks or packages. @@ -569,8 +568,8 @@ with specialized image <filename>.bb</filename> files. You can also add more features by configuring the <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</ulink></filename> - variable in the <filename>local.conf</filename> file found in the Yocto Project - files located in the build directory. + variable in the <filename>local.conf</filename> file found in the source directory + located in the build directory. </para> <para> @@ -648,7 +647,7 @@ <title>Adding a Package</title> <para> - To add a package into the Yocto Project you need to write a recipe for it. + To add a package you need to write a recipe for it. Writing a recipe means creating a <filename>.bb</filename> file that sets some variables. For information on variables that are useful for recipes and for information about recipe naming @@ -662,7 +661,7 @@ whether someone else has written one already. OpenEmbedded is a good place to look as it has a wider scope and range of packages. Because the Yocto Project aims to be compatible with OpenEmbedded, most recipes - you find there should work in Yocto Project. + you find there should work for you. </para> <para> @@ -1001,53 +1000,7 @@ </section> <section id="platdev-newmachine"> - <title>Porting the Yocto Project to a New Machine</title> - -<!-- -WRITER NOTES: - -I had this chat with Richard: - -scottrif: Terminology question: We speak of "New Machines" or "Adding a New Machine" - in YP. Are "Machines" restricted to architectures? In poky/meta/conf/machine we have .conf - files for the five architectures. What exactly does the term "Machine" mean? - - RP: no, each architecture has multiple different machines. A "machine" can correspond - to a particular reference board or hardware product - we just have one reference machine per architecture - We're a little vague sometimes as "machine" can refer to either an individual platform, - or in some cases a set of different platforms with common structure - (e.g. netbooks) - -scottrif: So our reference machines we supply are the five qemu* machines? - - RP: in oe-core, plus one "real" target in meta-yocto - (per arch) - -scottrif: I see four in meta-yocto/conf/machine. Shouldn't there be five if there is one - "real" target per architecture? - - RP: yes, we don't have one for x86_64 :/ - -scottrif: I think it is a bit difficult to map our four poky/meta-yocto/conf/machines to one of our - five architectures. Some have key words in there that identify the architecture but - beagleboard and atom-pc don't. - We have a section that describes adding a Machine Configuration file to Yocto and - it states that TARGET_ARCH is one of the most important variables that need to be - set in the .conf file. The four I am looking at don't have that variable. - - RP: That has changed a little now. You need to include the appropriate tune file - which will set it for you - People had a tendency not to set all the right pieces so it got abstracted - -scottrif: Got it. I see them in poky/meta/conf/machine/include. - -SOME CONCLUSIONS: - -I need to define the term machine. It is confusing. Then, this section needs to be cleared up -so that there are some definite steps on how to do this. I need more detail here. - ---> + <title>Adding a New Machine</title> <para> Adding a new machine to the Yocto Project is a straightforward process. @@ -1060,7 +1013,7 @@ so that there are some definite steps on how to do this. I need more detail her </para> <para> - For a complete example that shows how to add a new machine to the Yocto Project, + For a complete example that shows how to add a new machine, see the "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-bsp-appendix'>BSP Development Example</ulink>" in Appendix A. @@ -1072,7 +1025,8 @@ so that there are some definite steps on how to do this. I need more detail her <para> To add a machine configuration you need to add a <filename>.conf</filename> file with details of the device being added to the <filename>conf/machine/</filename> file. - The name of the file determines the name the Yocto Project uses to reference the new machine. + The name of the file determines the name the OpenEmbedded build system + uses to reference the new machine. </para> <para> @@ -1110,12 +1064,12 @@ so that there are some definite steps on how to do this. I need more detail her <title>Adding a Kernel for the Machine</title> <para> - The Yocto Project needs to be able to build a kernel for the machine. + The OpenEmbedded build system needs to be able to build a kernel for the machine. You need to either create a new kernel recipe for this machine, or extend an existing recipe. You can find several kernel examples in the - Yocto Project file's <filename>meta/recipes-kernel/linux</filename> - directory that you can use as references. + source directory at <filename>meta/recipes-kernel/linux</filename> + that you can use as references. </para> <para> @@ -1153,8 +1107,8 @@ so that there are some definite steps on how to do this. I need more detail her <para> A formfactor configuration file provides information about the - target hardware for which the Yocto Project is building and information that - the Yocto Project cannot obtain from other sources such as the kernel. + target hardware for which the image is being built and information that + the build system cannot obtain from other sources such as the kernel. Some examples of information contained in a formfactor configuration file include framebuffer orientation, whether or not the system has a keyboard, the positioning of the keyboard in relation to the screen, and @@ -1162,9 +1116,9 @@ so that there are some definite steps on how to do this. I need more detail her </para> <para> - The Yocto Project uses reasonable defaults in most cases, but if customization is + The build system uses reasonable defaults in most cases, but if customization is necessary you need to create a <filename>machconfig</filename> file - in the Yocto Project file's <filename>meta/recipes-bsp/formfactor/files</filename> + in the <filename>meta/recipes-bsp/formfactor/files</filename> directory. This directory contains directories for specific machines such as <filename>qemuarm</filename> and <filename>qemux86</filename>. @@ -1237,7 +1191,7 @@ so that there are some definite steps on how to do this. I need more detail her extended to support multiple libraries. Many standard recipes are already extended and support multiple libraries. You can check in the <filename>meta/conf/multilib.conf</filename> - configuration file in the Yocto Project files directory to see how this is + configuration file in the source directory to see how this is done using the <filename>BBCLASSEXTEND</filename> variable. Eventually, all recipes will be covered and this list will be unneeded. </para> @@ -1266,7 +1220,7 @@ so that there are some definite steps on how to do this. I need more detail her combination of multiple libraries you want to build. You accomplish this through your <filename>local.conf</filename> configuration file in the - <link linkend='yocto-project-build-directory'>Yocto Project Build Directory</link>. + <link linkend='build-directory'>build directory</link>. An example configuration would be as follows: <literallayout class='monospaced'> MACHINE = "qemux86-64" @@ -1311,7 +1265,7 @@ so that there are some definite steps on how to do this. I need more detail her <listitem><para>A unique architecture is defined for the Multilib packages, along with creating a unique deploy folder under <filename>tmp/deploy/rpm</filename> in the - <link linkend='yocto-project-build-directory'>Yocto Project Build Directory</link>. + <link linkend='build-directory'>build directory</link>. For example, consider <filename>lib32</filename> in a <filename>qemux86-64</filename> image. The possible architectures in the system are "all", "qemux86_64", @@ -1386,7 +1340,7 @@ so that there are some definite steps on how to do this. I need more detail her To use the <filename>menuconfig</filename> tool in the Yocto Project development environment, you must build the tool using BitBake. The following commands build and invoke <filename>menuconfig</filename> assuming the - Yocto Project files top-level directory is <filename>~/poky</filename>: + source directory top-level folder is <filename>~/poky</filename>: <literallayout class='monospaced'> $ cd ~/poky $ source oe-init-build-env @@ -1426,7 +1380,7 @@ so that there are some definite steps on how to do this. I need more detail her Where do you put your configuration files? You can place these configuration files in the same area pointed to by <filename>SRC_URI</filename>. - The Yocto Project build process will pick up the configuration and add it to the + The OpenEmbedded build system will pick up the configuration and add it to the kernel's configuration. For example, assume you add the following to your <filename>linux-yocto_3.0.bbappend</filename> file: @@ -1608,7 +1562,7 @@ so that there are some definite steps on how to do this. I need more detail her <para> Sometimes a package name you are using might exist under an alias or as a similarly named package in a different distribution. - The Yocto Project implements a <filename>distro_check</filename> + The OpenEmbedded build system implements a <filename>distro_check</filename> task that automatically connects to major distributions and checks for these situations. If the package exists under a different name in a different distribution, you get a @@ -1631,17 +1585,17 @@ so that there are some definite steps on how to do this. I need more detail her <para> If you have more than one distribution alias, separate them with a space. - Note that the Yocto Project currently automatically checks the + Note that the build system currently automatically checks the Fedora, OpenSuSE, Debian, Ubuntu, and Mandriva distributions for source package recipes without having to specify them using the <filename>DISTRO_PN_ALIAS</filename> variable. For example, the following command generates a report that lists the Linux distributions - that include the sources for each of the Yocto Project recipes. + that include the sources for each of the recipes. <literallayout class='monospaced'> $ bitbake world -f -c distro_check </literallayout> The results are stored in the <filename>build/tmp/log/distro_check-${DATETIME}.results</filename> - file found in the Yocto Project files area. + file found in the source directory. </para> </section> @@ -1649,18 +1603,18 @@ so that there are some definite steps on how to do this. I need more detail her <title>Building Software from an External Source</title> <para> - By default, the Yocto Project build system does its work from within the - <link linkend='yocto-project-build-directory'>Yocto Project Build Directory</link>. + By default, the OpenEmbedded build system does its work from within the + <link linkend='build-directory'>build directory</link>. The build process involves fetching the source files, unpacking them, and then patching them if necessary before the build takes place. </para> <para> Situations exist where you might want to build software from source files that are external to - and thus outside of the <link linkend='yocto-project-files'>Yocto Project Files</link>. + and thus outside of the <link linkend='source-directory'>source directory</link>. For example, suppose you have a project that includes a new BSP with a heavily customized kernel, a very minimal image, and some new user-space recipes. - And, you want to minimize the exposure to the Yocto Project build system to the + And, you want to minimize the exposure to the build system to the development team so that they can focus on their project and maintain everyone's workflow as much as possible. In this case, you want a kernel source directory on the development machine where the @@ -1829,7 +1783,7 @@ so that there are some definite steps on how to do this. I need more detail her <para> A suitable GDB cross-binary is required that runs on your host computer but also knows about the the ABI of the remote target. - You can get this binary from the the Yocto Project meta-toolchain. + You can get this binary from the meta-toolchain. Here is an example: <literallayout class='monospaced'> /usr/local/poky/eabi-glibc/arm/bin/arm-poky-linux-gnueabi-gdb @@ -1839,7 +1793,7 @@ so that there are some definite steps on how to do this. I need more detail her </para> <para> - Alternatively, the Yocto Project can build the <filename>gdb-cross</filename> binary. + Alternatively, you can use BitBake to build the <filename>gdb-cross</filename> binary. Here is an example: <literallayout class='monospaced'> $ bitbake gdb-cross @@ -1871,13 +1825,14 @@ so that there are some definite steps on how to do this. I need more detail her </para> <para> - Alternatively, Yocto Project can build a custom directory of files for a specific + Alternatively, the OpenEmbedded build system can build a custom directory of files + for a specific debugging purpose by reusing its <filename>tmp/rootfs</filename> directory. This directory contains the contents of the last built image. This process assumes two things: <itemizedlist> <listitem><para>The image running on the target was the last image to - be built by the Yocto Project.</para></listitem> + be built.</para></listitem> <listitem><para>The package (<filename>foo</filename> in the following example) that contains the inferior binary to be debugged has been built without optimization and has debugging information available.</para></listitem> @@ -1975,8 +1930,8 @@ so that there are some definite steps on how to do this. I need more detail her bottlenecks in both userspace software and in the kernel. This profiler provides answers to questions like "Which functions does my application spend the most time in when doing X?" - Because the Yocto Project is well integrated with OProfile, it makes profiling applications on target - hardware straightforward. + Because the OpenEmbedded build system is well integrated with OProfile, it makes profiling + applications on target hardware straightforward. </para> <para> @@ -1994,7 +1949,7 @@ so that there are some definite steps on how to do this. I need more detail her For successful call graph analysis, the binaries must preserve the frame pointer register and should also be compiled with the <filename>-fno-omit-framepointer</filename> flag. - In the Yocto Project you can achieve this by setting the + You can achieve this by setting the <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</ulink></filename> variable to <filename>-fexpensive-optimizations -fno-omit-framepointer -frename-registers -O2</filename>. @@ -2036,7 +1991,7 @@ so that there are some definite steps on how to do this. I need more detail her <note> To profile the kernel, you would specify the <filename>--vmlinux=/path/to/vmlinux</filename> option. - The <filename>vmlinux</filename> file is usually in the Yocto Project file's + The <filename>vmlinux</filename> file is usually in the source directory in the <filename>/boot/</filename> directory and must match the running kernel. </note> </para> @@ -2079,7 +2034,7 @@ so that there are some definite steps on how to do this. I need more detail her </para> <para> - Even though the Yocto Project usually includes all needed patches on the target device, you + Even though the source directory usually includes all needed patches on the target device, you might find you need other OProfile patches for recent OProfileUI features. If so, see the <ulink url='&YOCTO_GIT_URL;/cgit.cgi/oprofileui/tree/README'> OProfileUI README</ulink> for the most recent information. @@ -2142,18 +2097,18 @@ so that there are some definite steps on how to do this. I need more detail her </para> <para> - Downloaded archives reside in the Yocto Project's build directory in + Downloaded archives reside in the build directory in <filename>/tmp</filename> and are cleared up when they are no longer in use. </para> <para> If you wish to perform kernel profiling, you need to be sure a <filename>vmlinux</filename> file that matches the running kernel is available. - In the Yocto Project, that file is usually located in + In the source directory, that file is usually located in <filename>/boot/vmlinux-KERNELVERSION</filename>, where <filename>KERNEL-version</filename> is the version of the kernel. - The Yocto Project generates separate <filename>vmlinux</filename> packages for each kernel - it builds. + The OpenEmbedded build system generates separate <filename>vmlinux</filename> + packages for each kernel it builds. Thus, it should just be a question of making sure a matching package is installed (e.g. <filename>opkg install kernel-vmlinux</filename>. The files are automatically installed into development and profiling images @@ -2169,7 +2124,7 @@ so that there are some definite steps on how to do this. I need more detail her on the viewer system. The "<link linkend='platdev-gdb-remotedebug-launch-gdb'>Launching GDB on the Host Computer</link>" section covers how to create such a directory with - the Yocto Project and how to use the OProfileUI Settings dialog to specify the location. + the source directory and how to use the OProfileUI Settings dialog to specify the location. If you specify the directory, it will be used when the file checksums match those on the system you are profiling. </para> diff --git a/documentation/dev-manual/dev-manual-intro.xml b/documentation/dev-manual/dev-manual-intro.xml index fd35e283c2..7caa6eb720 100644 --- a/documentation/dev-manual/dev-manual-intro.xml +++ b/documentation/dev-manual/dev-manual-intro.xml @@ -18,7 +18,8 @@ sources where you can find more detail. For example, detailed information on Git, repositories and open source in general can be found in many places. - Another example is how to get set up to use the Yocto Project, which our Yocto Project Quick Start covers. + Another example is how to get set up to use the Yocto Project, which our Yocto Project + Quick Start covers. </para> <para> @@ -44,13 +45,7 @@ applications.</para></listitem> <listitem><para>An overview and understanding of the emulation environment used with the Yocto Project (QEMU).</para></listitem> -<!-- <listitem><para>A discussion of target-level analysis techniques, tools, tips, - and tricks.</para></listitem> - <listitem><para>Considerations for deploying your final product.</para></listitem> --> - <listitem><para>An understanding of basic kernel architecture and - concepts.</para></listitem> -<!-- <listitem><para>Information that will help you migrate an existing project to the - Yocto Project development environment.</para></listitem> --> + <listitem><para>An understanding of basic kernel architecture and concepts.</para></listitem> <listitem><para>Many references to other sources of related information.</para></listitem> </itemizedlist> </para> @@ -97,7 +92,7 @@ <listitem><para><emphasis> <ulink url='&YOCTO_DOCS_REF_URL;'> The Yocto Project Reference Manual</ulink>:</emphasis> This manual is a reference - guide to the Yocto Project build component known as "Poky." + guide to the OpenEmbedded build system known as "Poky." The manual also contains a reference chapter on Board Support Package (BSP) layout.</para></listitem> <listitem><para><emphasis> @@ -117,7 +112,7 @@ some work flow examples.</para></listitem> <listitem><para><emphasis> <ulink url='http://www.youtube.com/watch?v=3ZlOu-gLsh0'> - Yocto Eclipse Plug-in</ulink>:</emphasis> A step-by-step instructional video that + Eclipse IDE Yocto Plug-in</ulink>:</emphasis> A step-by-step instructional video that demonstrates how an application developer uses Yocto Plug-in features within the Eclipse IDE.</para></listitem> <listitem><para><emphasis> @@ -158,22 +153,26 @@ <listitem><para><emphasis>Internet Relay Chat (IRC):</emphasis> Two IRC channels on freenode are available for Yocto Project and Poky discussions: <filename>#yocto</filename> and - <filename>#poky</filename>.</para></listitem> + <filename>#poky</filename>, respectively.</para></listitem> <listitem><para><emphasis> <ulink url='&OH_HOME_URL;'>OpenedHand</ulink>:</emphasis> - The company where the Yocto Project build system Poky was first developed. - OpenedHand has since been acquired by Intel Corporation.</para></listitem> + The company that initially developed the Poky project, which is the basis + for the OpenEmbedded build system used by the Yocto Project. + OpenedHand was acquired by Intel Corporation in 2008.</para></listitem> <listitem><para><emphasis> <ulink url='http://www.intel.com/'>Intel Corporation</ulink>:</emphasis> - The company that acquired OpenedHand in 2008 and continues development on the - Yocto Project.</para></listitem> + A multinational semiconductor chip manufacturer company whose Software and + Services Group created and supports the Yocto Project. + Intel acquired OpenedHand in 2008.</para></listitem> <listitem><para><emphasis> <ulink url='&OE_HOME_URL;'>OpenEmbedded</ulink>:</emphasis> - The upstream, generic, embedded distribution the Yocto Project build system (Poky) derives - from and to which it contributes.</para></listitem> + The build system used by the Yocto Project. + This project is the upstream, generic, embedded distribution from which the Yocto + Project derives its build system (Poky) from and to which it contributes.</para></listitem> <listitem><para><emphasis> <ulink url='http://developer.berlios.de/projects/bitbake/'> - BitBake</ulink>:</emphasis> The tool used to process Yocto Project metadata.</para></listitem> + BitBake</ulink>:</emphasis> The tool used by the OpenEmbedded build systm + to process project metadata.</para></listitem> <listitem><para><emphasis> <ulink url='http://bitbake.berlios.de/manual/'> BitBake User Manual</ulink>:</emphasis> A comprehensive guide to the BitBake tool. diff --git a/documentation/dev-manual/dev-manual-kernel-appendix.xml b/documentation/dev-manual/dev-manual-kernel-appendix.xml index 0f69ef1067..04db02a7a6 100644 --- a/documentation/dev-manual/dev-manual-kernel-appendix.xml +++ b/documentation/dev-manual/dev-manual-kernel-appendix.xml @@ -12,17 +12,6 @@ or even altering the source code itself. This appendix presents simple examples that modify the kernel source code, change the kernel configuration, and add a kernel source recipe. -<!-- [WRITER'S NOTE: I might want to work in information about applying a local - change to a kernel layer and also pushing a change upstream into the tree] - <orderedlist> - <listitem><para>Iteratively determine and set kernel configurations and make - kernel recipe changes.</para></listitem> - <listitem><para>Apply your configuration changes to your local kernel layer. - </para></listitem> - <listitem><para>Push your configuration and recipe changes upstream into the - Yocto Project source repositories to make them available to the community. - </para></listitem> - </orderedlist> --> </para> <section id='modifying-the-kernel-source-code'> @@ -45,18 +34,17 @@ Briefly, you need the following: <itemizedlist> <listitem><para>A local - <link linkend='yocto-project-files'>Yocto Project Files</link> - Git repository</para></listitem> - <listitem><para>The + <link linkend='source-directory'>source directory</link> for the + poky Git repository</para></listitem> + <listitem><para>Local copies of the <link linkend='poky-extras-repo'><filename>poky-extras</filename></link> - Git repository placed within the local Yocto Project files Git - repository</para></listitem> + Git repository placed within the source directory.</para></listitem> <listitem><para>A bare clone of the <link linkend='local-kernel-files'>Linux Yocto Kernel</link> upstream Git repository to which you want to push your modifications. </para></listitem> <listitem><para>A copy of that bare clone in which you make your source - modifcations</para></listitem> + modifications</para></listitem> </itemizedlist> </para> @@ -78,18 +66,19 @@ <para> Here is a brief description of the four areas: <itemizedlist> - <listitem><para><emphasis>Local Yocto Project Files Git Repository:</emphasis> - This area contains all the metadata that supports building images in the - Yocto Project build environment - the local Yocto Project files. - In this example, the local Yocto Project files Git repository also + <listitem><para><emphasis>Local Source Directory:</emphasis> + This area contains all the metadata that supports building images + using the OpenEmbedded build system. + In this example, the source directory also contains the build directory, which contains the configuration directory that lets you control the build. - In this example, the repository also contains the + Also in this example, the source directory contains local copies of the <filename>poky-extras</filename> Git repository.</para> <para>See the bulleted item "<link linkend='local-yp-release'>Yocto Project Release</link>" - for information on how to get these files.</para></listitem> - <listitem><para><emphasis><filename>poky-extras</filename> Git Repository:</emphasis> + for information on how to get these files on your local system.</para></listitem> + <listitem><para><emphasis>Local copies of the<filename>poky-extras</filename> + Git Repository:</emphasis> This area contains the <filename>meta-kernel-dev</filename> layer, which is where you make changes that append the kernel build recipes. You edit <filename>.bbappend</filename> files to locate your @@ -133,23 +122,23 @@ </section> <section id='setting-up-the-local-yocto-project-files-git-repository'> - <title>Setting Up the Local Yocto Project Files Git Repository</title> + <title>Setting Up the Local Source Directory</title> <para> - You can get the local Yocto Project files through tarball extraction or by + You can set up the source directory through tarball extraction or by cloning the <filename>poky</filename> Git repository. This example uses <filename>poky</filename> as the root directory of the - local Yocto Project files Git repository. + local source directory. See the bulleted item "<link linkend='local-yp-release'>Yocto Project Release</link>" for information on how to get these files. </para> <para> - Once you have the repository set up, + Once you have source directory set up, you have many development branches from which you can work. - From inside the repository you can see the branch names and the tag names used - in the Git repository using either of the following two commands: + From inside the local repository you can see the branch names and the tag names used + in the upstream Git repository by using either of the following commands: <literallayout class='monospaced'> $ cd poky $ git branch -a @@ -168,15 +157,15 @@ </section> <section id='setting-up-the-poky-extras-git-repository'> - <title>Setting Up the poky-extras Git Repository</title> + <title>Setting Up the Local poky-extras Git Repository</title> <para> - This example places the <filename>poky-extras</filename> Git repository inside - of <filename>poky</filename>. - See the bulleted item - "<link linkend='poky-extras-repo'>The + This example creates a local copy of the <filename>poky-extras</filename> Git + repository inside the <filename>poky</filename> source directory. + See the bulleted item "<link linkend='poky-extras-repo'>The <filename>poky-extras</filename> Git Repository</link>" - for information on how to get the <filename>poky-extras</filename> repository. + for information on how to set up a local copy of the + <filename>poky-extras</filename> repository. </para> <para> @@ -369,7 +358,7 @@ <para> Once the source code has been modified, you need to use Git to push the changes to the bare clone. - If you do not push the changes, then the Yocto Project build system will not pick + If you do not push the changes, then the OpenEmbedded build system will not pick up the changed source files. </para> @@ -386,7 +375,7 @@ <para> At this point, the source has been changed and pushed. - The example now defines some variables used by the Yocto Project build system + The example now defines some variables used by the OpenEmbedded build system to locate your kernel source. You essentially need to identify where to find the kernel recipe and the changed source code. You also need to be sure some basic configurations are in place that identify the @@ -447,12 +436,6 @@ <literallayout class='monospaced'> KSRC_linux_yocto_3_2 ?= "/home/scottrif/linux-yocto-3.2.git" </literallayout></para></listitem> -<!-- <listitem><para><emphasis>Specify the Kernel Machine:</emphasis> Also in the - <filename>linux-yocto_3.2.bbappend</filename> file, you need to specify - the kernel machine with the following statement: - <literallayout class='monospaced'> - KMACHINE_qemux86 = "standard/default/common-pc/base" - </literallayout></para></listitem> --> </itemizedlist> </para> @@ -494,7 +477,7 @@ $ bitbake -c cleanall linux-yocto </literallayout></para> <para><note>Never remove any files by hand from the <filename>tmp/deploy</filename> - directory insided the local Yocto Project files build directory. + directory insided the build directory. Always use the BitBake <filename>cleanall</filename> task to clear out previous builds.</note></para></listitem> <listitem><para>Next, build the kernel image using this command: @@ -539,7 +522,7 @@ <para> If you took the time to work through the example that modifies the kernel source code in "<link linkend='modifying-the-kernel-source-code'>Modifying the Kernel Source - Code</link>" you should already have the Yocto Project files set up on your + Code</link>" you should already have the source directory set up on your host machine. If this is the case, go to the next section, which is titled "<link linkend='examining-the-default-config-smp-behavior'>Examining the Default @@ -548,21 +531,21 @@ </para> <para> - If you don't have the Yocto Project files established on your system, + If you don't have the source directory established on your system, you can get them through tarball extraction or by cloning the <filename>poky</filename> Git repository. This example uses <filename>poky</filename> as the root directory of the - local <link linkend='yocto-project-files'>Yocto Project Files</link> Git repository. + <link linkend='source-directory'>source directory</link>. See the bulleted item "<link linkend='local-yp-release'>Yocto Project Release</link>" for information on how to get these files. </para> <para> - Once you have the repository set up, + Once you have the local copy of the repository set up, you have many development branches from which you can work. From inside the repository you can see the branch names and the tag names used - in the Git repository using either of the following two commands: + in the upstream Git repository using either of the following commands: <literallayout class='monospaced'> $ cd poky $ git branch -a @@ -680,7 +663,7 @@ to set kernel configurations. You need to run <filename>menuconfig</filename> inside the Yocto BitBake environment. Thus, the environment must be set up using the <filename>oe-init-build-env</filename> - script found in the Yocto Project files Git repository build directory. + script found in the build directory. If you have not sourced this script do so with the following commands: <literallayout class='monospaced'> $ cd ~/poky @@ -693,7 +676,7 @@ to use the tool to interactively change the kernel configuration. In this example, we are basing our changes on the <filename>linux-yocto-3.2</filename> kernel. - The Yocto Project build environment recognizes this kernel as + The OpenEmbedded build system recognizes this kernel as <filename>linux-yocto</filename>. Thus, the following commands from the shell in which you previously sourced the environment initialization script cleans the shared state memory and the @@ -727,8 +710,7 @@ is updated. This is the file that the build system uses to configure the Linux Yocto kernel when it is built. - You can find and examine this file in the Yocto Project Files Git repository in - the build directory. + You can find and examine this file in the build directory. This example uses the following: <literallayout class='monospaced'> ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-3.2.11+git1+84f... @@ -762,7 +744,7 @@ <note> Be sure to make a copy of the <filename>.config</filename> and don't just rename it. - The Yocto Project build system needs an existing <filename>.config</filename> + The build system needs an existing <filename>.config</filename> from which to work. </note> </para> diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml index 69e09e6466..a4120f84db 100644 --- a/documentation/dev-manual/dev-manual-model.xml +++ b/documentation/dev-manual/dev-manual-model.xml @@ -34,8 +34,8 @@ get the changes upstream and applied in the affected recipes.</para></listitem> <listitem><para><emphasis>Image Development using Hob:</emphasis> You can use the <ulink url='&YOCTO_HOME_URL;/projects/hob'>Hob</ulink> to build - custom operating system images within the Yocto Project build environment. - Hob provides an efficient interface to the Yocto Project build system.</para></listitem> + custom operating system images within the build environment. + Hob provides an efficient interface to the OpenEmbedded build system.</para></listitem> </itemizedlist> </para> @@ -94,18 +94,20 @@ and the "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" sections both in the Yocto Project Quick Start for requirements.</para></listitem> - <listitem><para><emphasis>Establish a local copy of the Yocto Project files on your - system</emphasis>: You need to have the Yocto Project files available on your host system. - Having the Yocto Project files on your system gives you access to the build + <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 get these files, see the + For information on how to set up the source directory, see the "<link linkend='getting-setup'>Getting Setup</link>" section.</para></listitem> <listitem><para><emphasis>Establish a local copy of the base BSP files</emphasis>: Having the BSP files on your system gives you access to the build process and to the tools you need for creating a BSP. For information on how to get these files, see the "<link linkend='getting-setup'>Getting Setup</link>" section.</para></listitem> - <listitem><para><emphasis>Choose a Yocto Project-supported BSP as your base BSP</emphasis>: + <listitem><para><emphasis>Choose a BSP that is supported by the Yocto Project + as your base BSP</emphasis>: The Yocto Project ships with several BSPs that support various hardware. It is best to base your new BSP on an existing BSP rather than create all the recipes and configuration files from scratch. @@ -138,7 +140,7 @@ 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 Yocto Project build + 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>" @@ -146,11 +148,11 @@ 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.</para> - <note>The Yocto Project supports four BSPs that are part of the + <note>Four BSPs exist that are part of the Yocto Project release: <filename>atom-pc</filename>, <filename>beagleboard</filename>, <filename>mpc8315e</filename>, and <filename>routerstationpro</filename>. The recipes and configurations for these four BSPs are located and dispersed - within the <link linkend='yocto-project-files'>Yocto Project Files</link>. + within the <link linkend='source-directory'>source directory</link>. On the other hand, BSP layers for Crown Bay, Emenlow, Jasper Forest, N450, Cedar Trail, Fish River, Fish River Island II, Romley, sys940x, tlk, and Sugar Bay exist in their own separate layers within the larger @@ -163,7 +165,7 @@ configuration information. You can see the standard layout for the Crown Bay BSP in this example by examining the directory structure of the <filename>meta-crownbay</filename> layer inside the - local Yocto Project files.</para></listitem> + 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> @@ -177,15 +179,15 @@ </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 Yocto Project build system in order for it to create your image. + 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 and you need to be sure two key configuration files are configured appropriately.</para> <para>The entire process for building an image is overviewed in the section "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</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 Yocto Project uses the BitBake - tool to build images based on the type of image you want to create. + <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 on BitBake <ulink url='http://bitbake.berlios.de/manual/'>here</ulink>.</para> <para>The build process supports several types of images to satisfy different needs. @@ -295,7 +297,7 @@ <para> The overall result is a Git-maintained repository from which all the supported - Yocto Project kernel types can be derived for all the supported Yocto Project devices. + 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. @@ -313,7 +315,7 @@ <para> Storage of all the available kernel source code is one thing, while representing the code on your host development system is another. - Conceptually, you can think of the Yocto Project kernel source repositories as all the + 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 on which you are working. @@ -358,7 +360,7 @@ <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 Yocto Project source repositories pointed to by the + are taken from the source repositories pointed to by the <filename>SRC_URI</filename> 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 @@ -375,7 +377,7 @@ </para> <para> - Again, for a complete discussion of the Yocto Project kernel's architcture and its + Again, for a complete discussion of the Yocto Project kernel's architecture and its branching strategy, see <ulink url='&YOCTO_DOCS_KERNEL_URL;'> The Yocto Project Kernel Architecture and Use Manual</ulink>. @@ -404,18 +406,19 @@ "<ulink url='&YOCTO_DOCS_QS_URL;#the-linux-distro'>The Linux Distributions</ulink>" and "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" sections both in the Yocto Project Quick Start for requirements.</para></listitem> - <listitem><para><emphasis>Establish a local copy of the Yocto Project files on your - system</emphasis>: Having the Yocto Project files on your system gives you access to - the build process and tools you need. + <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>Set up the <filename>poky-extras</filename> Git - repository</emphasis>: This repository is the area for your configuration + <listitem><para><emphasis>Set up a local copy of the <filename>poky-extras</filename> Git + repository</emphasis>: This local repository is the area for your configuration fragments, new kernel recipes, and the kernel <filename>.bbappend</filename> file used during the build. - It is good practice to set this repository up inside the local Yocto - Project files Git repository. + It is good practice to set this repository up inside your local + source directory. For information on how to get these files, see the bulleted item "<link linkend='poky-extras-repo'>The <filename>poky-extras</filename> Git Repository</link>" earlier in this manual. @@ -453,9 +456,9 @@ <filename>.config</filename>. Try to resist the temptation of directly editing the <filename>.config</filename> file found in the - <link linkend='yocto-project-build-directory'>Yocto Project Build Directory</link> at + <link linkend='build-directory'>build directory</link> at <filename>tmp/sysroots/<machine-name>/kernel</filename>. - Doing so, can produce unexpected results when the Yocto Project build system + Doing so, can produce unexpected results when the OpenEmbedded build system regenerates the configuration file.</para> <para>Once you are satisfied with the configuration changes made using <filename>menuconfig</filename>, you can directly examine the @@ -465,7 +468,7 @@ <listitem><para><emphasis>Add or extend kernel recipes if applicable</emphasis>: The standard layer structure organizes recipe files inside the - <filename>meta-kernel-dev</filename> layer that is within the + <filename>meta-kernel-dev</filename> layer that is within the local <filename>poky-extras</filename> Git repository. If you need to add new kernel recipes, you add them within this layer. Also within this area, you will find the <filename>.bbappend</filename> @@ -475,7 +478,7 @@ <listitem><para><emphasis>Prepare for the build</emphasis>: Once you have made all the changes to your kernel (configurations, source code changes, recipe additions, or recipe changes), there remains a few things - you need to do in order for the Yocto Project build system (BitBake) to create your image. + you need to do in order for the build system to create your image. If you have not done so, you need to get the build environment ready by sourcing the environment setup script described earlier. You also need to be sure two key configuration files @@ -487,8 +490,8 @@ You might want to reference this information. Also, you should look at the detailed examples found in the appendices at at the end of this manual.</para></listitem> - <listitem><para><emphasis>Build the image</emphasis>: The Yocto Project - build system Poky uses the BitBake + <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 on BitBake <ulink url='http://bitbake.berlios.de/manual/'>here</ulink>.</para> @@ -514,7 +517,7 @@ </section> </section> -<section id='place-holder-section-two'> +<section id='application-development-workflow'> <title>Application Development Workflow</title> <para> @@ -530,7 +533,7 @@ </para> <para> - While we strongly suggest using the Yocto Project ADT to develop your application, you might + While we strongly suggest using the ADT to develop your application, you might not want to. If this is the case, you can still use pieces of the Yocto Project for your development process. However, because the process can vary greatly, this manual does not provide detail on the process. @@ -540,8 +543,7 @@ <title>Workflow Using the ADT and <trademark class='trade'>Eclipse</trademark></title> <para> - To help you understand how application development works in the Yocto Project ADT - environment, this section + To help you understand how application development works using the ADT, this section provides an overview of the general development process. If you want to see a detailed example of the process as it is used from within the Eclipse IDE, see @@ -550,7 +552,7 @@ </para> <para> - This illustration and the following list summarizes the application development general workflow. + The following illustration and list summarize the application development general workflow. </para> <para> @@ -565,27 +567,9 @@ "<ulink url='&YOCTO_DOCS_QS_URL;#the-linux-distro'>The Linux Distributions</ulink>" and "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" sections both in the Yocto Project Quick Start for requirements.</para></listitem> - -<!-- -WRITER NOTE: The areas to get the kernel and root filesystem are located in the Index of - downloads. There are many forms of each. The files that have "rootfs" are just the - target root filesystems. The file that is very small and starts with bzImage is just - the kernel image isolated so that it can be written to a special on-board area of - flash memory. Some systems require this. In the machines directory there are - files that combine the kernel image and the root filesystem. These files are the ISO - and HDDIMG files. ISO images are designed to be deployed on a DVD or CD. The ISO - images are designed to be deployed on a USB stick. There might be some relics in - the machine directory. For example, there is the "emenlow-bernard-5.0.0.tar.bz2" - file. Nobody seems to know what this is. If a developer needs the image and the - root filesystem I think that they want the small kernel image and a matching root - filesystem. Although, Paul Eggleton says that the HDDIMG types could be used to - develop on. I am not sure that we can use one of those in the ADT though as they - want you to point to the kernel image and the target root filesystem. Maybe you - could just point to the same spot. I am not sure. ---> - <listitem><para><emphasis>Secure the Linux Yocto Kernel Target Image</emphasis>: - You must have a target kernel image that has been built using the Yocto Project.</para> + You must have a target kernel image that has been built using the OpenEmbeded + build system.</para> <para>Depending on whether the Yocto Project has a pre-built image that matches your target architecture and where you are going to run the image while you develop your application (QEMU or real hardware), the area from which you get the image differs. @@ -616,7 +600,7 @@ WRITER NOTE: The areas to get the kernel and root filesystem are located in the <listitem><para><emphasis>Install the ADT</emphasis>: The ADT provides a target-specific cross-development toolchain, the root filesystem, the QEMU emulator, and other tools that can help you develop your application. - While it is possible to get these pieces separately, the Yocto Project provides an + While it is possible to get these pieces separately, the ADT Installer provides an easy method. You can get these pieces by running an ADT installer script, which is configurable. For information on how to install the ADT, see the @@ -707,14 +691,14 @@ WRITER NOTE: The areas to get the kernel and root filesystem are located in the <title>Modifying Temporary Source Code</title> <para> - Although the Yocto Project is typically used to build software, you might + 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='yocto-project-build-directory'>Yocto Project's Build Directory</link>, and then + <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. @@ -728,12 +712,12 @@ WRITER NOTE: The areas to get the kernel and root filesystem are located in the <para> During a build, the unpacked temporary source code used by recipes - to build packages is available in the Yocto Project Build Directory as + 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='yocto-project-files'>Yocto Project Files</link>: + <link linkend='source-directory'>source directory</link>: <literallayout class='monospaced'> S = ${WORKDIR}/${BP} </literallayout> @@ -758,8 +742,8 @@ WRITER NOTE: The areas to get the kernel and root filesystem are located in the ${TMPDIR}/work/${PACKAGE_ARCH}-poky-${TARGET_OS}/${PN}-${PV}-${PR} </literallayout> Let's look at an example without variables. - Assuming a Yocto Project Files top-level directory named <filename>poky</filename> - and a default Yocto Project Build Directory of <filename>poky/build</filename>, + Assuming a top-level source directory named <filename>poky</filename> + and a default build directory of <filename>poky/build</filename>, the following is the work directory for the <filename>acl</filename> package: <literallayout class='monospaced'> ~/poky/build/tmp/work/i586-poky-linux/acl-2.2.51-r3 @@ -771,8 +755,8 @@ WRITER NOTE: The areas to get the kernel and root filesystem are located in the <literallayout class='monospaced'> ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}-${PV}-${PR} </literallayout> - Again, assuming a Yocto Project Files top-level directory named <filename>poky</filename> - and a default Yocto Project Build Directory of <filename>poky/build</filename>, the + Again, assuming top-level source directory named <filename>poky</filename> + and a default build directory of <filename>poky/build</filename>, the following is the work directory for the <filename>acl</filename> package that is being built for a MIPS-based device: <literallayout class='monospaced'> @@ -781,7 +765,7 @@ WRITER NOTE: The areas to get the kernel and root filesystem are located in the </para> <note> - To better understand how the Yocto Project build system resolves directories during the + To better understand how the OpenEmbedded build system resolves directories during the build process, see the glossary entries for the <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>, <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>, @@ -817,8 +801,8 @@ WRITER NOTE: The areas to get the kernel and root filesystem are located in the Follow these general steps: <orderedlist> <listitem><para><emphasis>Find the Source Code:</emphasis> - The temporary source code used by the Yocto Project build system is kept in the - Yocto Project Build Directory. + The temporary source code used by the OpenEmbedded build system is kept in the + build directory. See the "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>" section to learn how to locate the directory that has the temporary source code for a @@ -875,7 +859,7 @@ WRITER NOTE: The areas to get the kernel and root filesystem are located in the <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 as the recipe. - Placing the patch here guarantees that the Yocto Project build system will find + 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> @@ -904,16 +888,15 @@ WRITER NOTE: The areas to get the kernel and root filesystem are located in the <note> This workflow uses Git only for its ability to manage local changes to the source code - and produce patches independent of any version control used on the Yocto Project - Files. + and produce patches independent of any version control system used with the Yocto Project. </note> <para> Follow these general steps: <orderedlist> <listitem><para><emphasis>Find the Source Code:</emphasis> - The temporary source code used by the Yocto Project build system is kept in the - Yocto Project Build Directory. + The temporary source code used by the OpenEmbedded build system is kept in the + build directory. See the "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>" section to learn how to locate the directory that has the temporary source code for a @@ -1002,7 +985,7 @@ WRITER NOTE: The areas to get the kernel and root filesystem are located in the <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 as the recipe. - Placing the patch here guarantees that the Yocto Project build system will find + 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> @@ -1024,11 +1007,11 @@ WRITER NOTE: The areas to get the kernel and root filesystem are located in the <title>Image Development Using Hob</title> <para> - The <ulink url='&YOCTO_HOME_URL;/projects/hob'>Hob</ulink> is a graphical user interface for the Yocto - Project build system based on BitBake. + The <ulink url='&YOCTO_HOME_URL;/projects/hob'>Hob</ulink> is a graphical user interface for the + OpenEmbedded build system, which is based on BitBake. You can use the Hob to build custom operating system images within the Yocto Project build environment. Hob simply provides a friendly interface over the build system used during system development. - In other words, building images with the Hob lets you take care of common Yocto Project build tasks more easily. + In other words, building images with the Hob lets you take care of common build tasks more easily. </para> <para> diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml index 6a8d39caae..94f3471f13 100644 --- a/documentation/dev-manual/dev-manual-newbie.xml +++ b/documentation/dev-manual/dev-manual-newbie.xml @@ -55,7 +55,7 @@ </section> <section id="usingpoky-changes-collaborate"> - <title>Using The Yocto Project in a Team Environment</title> + <title>Using the Yocto Project in a Team Environment</title> <para> It might not be immediately clear how you can use the Yocto Project in a team environment, @@ -97,19 +97,20 @@ <para> Most teams have many pieces of software undergoing active development at any given time. You can derive large benefits by putting these pieces under the control of a source - control system that is compatible with the Yocto Project (i.e. Git or Subversion (SVN)). + control system that is compatible (i.e. Git or Subversion (SVN)) with the OpenEmbeded + build system that the Yocto Project uses. You can then set the autobuilder to pull the latest revisions of the packages and test the latest commits by the builds. This practice quickly highlights issues. - The Yocto Project easily supports testing configurations that use both a + The build system easily supports testing configurations that use both a stable known good revision and a floating revision. - The Yocto Project can also take just the changes from specific source control branches. + The build system can also take just the changes from specific source control branches. This capability allows you to track and test specific changes. </para> <para> Perhaps the hardest part of setting this up is defining the software project or - the Yocto Project metadata policies that surround the different source control systems. + the metadata policies that surround the different source control systems. Of course circumstances will be different in each case. However, this situation reveals one of the Yocto Project's advantages - the system itself does not @@ -129,7 +130,7 @@ From the interface, you can click on any particular item in the "Name" column and see the URL at the bottom of the page that you need to set up a Git repository for that particular item. - Having a local Git repository of the Yocto Project files allows you to + Having a local Git repository of the source directory (poky) allows you to make changes, contribute to the history, and ultimately enhance the Yocto Project's tools, Board Support Packages, and so forth. </para> @@ -147,8 +148,8 @@ <ulink url='&YOCTO_HOME_URL;/download'>download page</ulink> and get a tarball of the release. You can also go to this site to download any supported BSP tarballs. - Unpacking the tarball gives you a hierarchical directory structure of Yocto Project - files that lets you develop using the Yocto Project. + Unpacking the tarball gives you a hierarchical source directory that lets you develop + using the Yocto Project. </para> <para> @@ -157,22 +158,22 @@ </para> <para> - In summary, here is where you can get the Yocto Project files needed for development: + In summary, here is where you can get the project files needed for development: <itemizedlist> <listitem><para id='source-repositories'><emphasis><ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'>Source Repositories:</ulink></emphasis> This area contains IDE Plugins, Matchbox, Poky, Poky Support, Tools, Yocto Linux Kernel, and Yocto Metadata Layers. - You can create Git repositories for each of these areas.</para> + You can create local copies of Git repositories for each of these areas.</para> <para> <imagedata fileref="figures/source-repos.png" align="center" width="6in" depth="4in" /> </para></listitem> <listitem><para><anchor id='index-downloads' /><emphasis><ulink url='&YOCTO_DL_URL;/releases/'>Index of /releases:</ulink></emphasis> This area contains index releases such as the <trademark class='trade'>Eclipse</trademark> - Yocto Plug-in, miscellaneous support, Poky, pseudo, cross-development toolchains, + Yocto Plug-in, miscellaneous support, poky, pseudo, cross-development toolchains, and all released versions of Yocto Project in the form of images or tarballs. - Downloading and extracting these files does not produce a Git repository but rather - a snapshot of a particular release or image.</para> + Downloading and extracting these files does not produce a local copy of the + Git repository but rather a snapshot of a particular release or image.</para> <para> <imagedata fileref="figures/index-downloads.png" align="center" width="6in" depth="4in" /> </para></listitem> @@ -199,7 +200,7 @@ <listitem><para><emphasis>Append Files:</emphasis> Files that append build information to a recipe file. Append files are known as BitBake append files and <filename>.bbappend</filename> files. - The Yocto Project build system expects every append file to have a corresponding and + The OpenEmbedded build system expects every append file to have a corresponding and underlying recipe (<filename>.bb</filename>) file. Furthermore, the append file and the underlying recipe must have the same root filename. The filenames can differ only in the file type suffix used (e.g. @@ -211,9 +212,49 @@ "<link linkend='changing-recipes-kernel'>Changing <filename>recipes-kernel</filename></link>" sections.</para></listitem> <listitem><para><emphasis>BitBake:</emphasis> The task executor and scheduler used by - the Yocto Project to build images. + the OpenEmbedded build system to build images. For more information on BitBake, see the <ulink url='http://bitbake.berlios.de/manual/'> BitBake documentation</ulink>.</para></listitem> + <listitem> + <para id='build-directory'><emphasis>Build Directory:</emphasis> + This term refers to the area used by the OpenEmbedded build system for builds. + The area is created when you <filename>source</filename> the setup + environment script that is found in the source directory + (i.e. <filename>oe-init-build-env</filename>). + The <ulink url='&YOCTO_DOCS_REF_URL;#var-TOPDIR'><filename>TOPDIR</filename></ulink> + variable points to the build directory.</para> + + <para>You have a lot of flexibility when creating the build directory. + Following are some examples that show how to create the directory: + <itemizedlist> + <listitem><para>Create the build directory in your current working directory + and name it <filename>build</filename>. + This is the default behavior. + <literallayout class='monospaced'> + $ source oe-init-build-env + </literallayout></para></listitem> + <listitem><para>Provide a directory path and specifically name the build + directory. + This next example creates a build directory named <filename>YP-&POKYVERSION;</filename> + in your home directory within the directory <filename>mybuilds</filename>. + If <filename>mybuilds</filename> does not exist, the directory is created for you: + <literallayout class='monospaced'> + $ source &OE_INIT_PATH; $HOME/mybuilds/YP-&POKYVERSION; + </literallayout></para></listitem> + <listitem><para>Provide an existing directory to use as the build directory. + This example uses the existing <filename>mybuilds</filename> directory + as the build directory. + <literallayout class='monospaced'> + $ source &OE_INIT_PATH; $HOME/mybuilds/ + </literallayout></para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para><emphasis>Build System:</emphasis> In the context of the Yocto Project + this term refers to the OpenEmbedded build system used by the project. + This build system is based on the project known as "Poky." + For some historical information about Poky, see the + <link linkend='poky'>poky</link> term further along in this section. + </para></listitem> <listitem><para><emphasis>Classes:</emphasis> Files that provide for logic encapsulation and inheritance allowing commonly used patterns to be defined once and easily used in multiple recipes. @@ -222,13 +263,14 @@ <listitem><para><emphasis>Configuration File:</emphasis> Configuration information in various <filename>.conf</filename> files provides global definitions of variables. The <filename>conf/local.conf</filename> configuration file in the - <link linkend='yocto-project-build-directory'>Yocto Project Build Directory</link> + <link linkend='build-directory'>build directory</link> contains user-defined variables that affect each build. The <filename>meta-yocto/conf/distro/poky.conf</filename> configuration file defines Yocto ‘distro’ configuration variables used only when building with this policy. Machine configuration files, which - are located throughout the Yocto Project file structure, define + are located throughout the + <link linkend='source-directory'>source directory</link>, define variables for specific hardware and are only used when building for that target (e.g. the <filename>machine/beagleboard.conf</filename> configuration file defines variables for the Texas Instruments ARM Cortex-A8 development board). @@ -239,7 +281,8 @@ tools and utilities that allow you to develop software for targeted architectures. This toolchain contains cross-compilers, linkers, and debuggers that are specific to an architecture. - You can use the Yocto Project to build cross-development toolchains in tarball form that, when + You can use the OpenEmbedded build system to build cross-development toolchains in tarball + form that, when unpacked, contain the development tools you need to cross-compile and test your software. The Yocto Project ships with images that contain toolchains for supported architectures as well. @@ -261,64 +304,63 @@ Metadata includes recipes, classes, and configuration files.</para></listitem> <listitem><para><emphasis>OE-Core:</emphasis> A core set of metadata originating with OpenEmbedded (OE) that is shared between OE and the Yocto Project. - This metadata is found in the <filename>meta</filename> directory of the Yocto Project - files.</para></listitem> + This metadata is found in the <filename>meta</filename> directory of the source + directory.</para></listitem> <listitem><para><emphasis>Package:</emphasis> The packaged output from a baked recipe. A package is generally the compiled binaries produced from the recipe's sources. You ‘bake’ something by running it through BitBake.</para></listitem> - <listitem><para><emphasis>Poky:</emphasis> The build tool that the Yocto Project - uses to create images.</para></listitem> + <listitem><para id='poky'><emphasis>Poky:</emphasis> The term "poky" can mean several things. + In its most general sence, it is an open-source project that was initially developed + by OpenedHand. With OpenedHand, poky was developed off of the existing OpenEmbedded + build system becoming a build system for embedded images. + After Intel Corporation aquired OpenedHand, the project poky became the basis for + the Yocto Project's build system. + Within the Yocto Project source repositories, poky exists as a separate Git repository + that can be cloned to yield a local copy on the host system. + Thus, "poky" can refer to the local copy of the source directory used to develop within + the Yocto Project.</para></listitem> <listitem><para><emphasis>Recipe:</emphasis> A set of instructions for building packages. A recipe describes where you get source code and which patches to apply. Recipes describe dependencies for libraries or for other recipes, and they also contain configuration and compilation options. Recipes contain the logical unit of execution, the software/images to build, and use the <filename>.bb</filename> file extension.</para></listitem> - <listitem><para><emphasis>Tasks:</emphasis> Arbitrary groups of software Recipes. - You simply use Tasks to hold recipes that, when built, usually accomplish a single task. - For example, a task could contain the recipes for a company’s proprietary or value-add software. - Or, the task could contain the recipes that enable graphics. - A task is really just another recipe. - Because task files are recipes, they end with the <filename>.bb</filename> filename - extension.</para></listitem> - <listitem><para><emphasis>Upstream:</emphasis> A reference to source code or repositories - that are not local to the development system but located in a master area that is controlled - by the maintainer of the source code. - For example, in order for a developer to work on a particular piece of code, they need to - first get a copy of it from an "upstream" source.</para></listitem> <listitem> - <para id='yocto-project-files'><emphasis>Yocto Project Files:</emphasis> + <para id='source-directory'><emphasis>Source Directory:</emphasis> This term refers to the directory structure created as a result of either downloading - and unpacking a Yocto Project release tarball or setting up a Git repository - by cloning <filename>git://git.yoctoproject.org/poky</filename>. - Sometimes the term "the Yocto Project Files structure" is used as well.</para> - - <para>The Yocto Project Files contain BitBake, Documentation, metadata and - other files that all support the development environment. - Consequently, you must have the Yocto Project Files in place on your development + and unpacking a Yocto Project release tarball or creating a local copy of + <filename>poky</filename> Git repository <filename>git://git.yoctoproject.org/poky</filename>. + Sometimes you might here the term "poky directory" used to refer to this + directory structure.</para> + + <para>The source directory contains BitBake, Documentation, metadata and + other files that all support the Yocto Project. + Consequently, you must have the source directory in place on your development system in order to do any development using the Yocto Project.</para> - <para>The name of the top-level directory of the Yocto Project Files structure + <para>For tarball expansion, the name of the top-level directory of the source directory is derived from the Yocto Project release tarball. For example, downloading and unpacking <filename>&YOCTO_POKY_TARBALL;</filename> - results in a Yocto Project file structure whose Yocto Project source directory is named + results in a source directory whose top-level folder is named <filename>&YOCTO_POKY;</filename>. - If you create a Git repository, then you can name the repository anything you like. - Throughout much of the documentation, the name of the Git repository is used as the - name for the local folder. + If you create a local copy of the Git repository, then you can name the repository + anything you like. + Throughout much of the documentation, <filename>poky</filename> is used as the name of + the top-level folder of the local copy of the poky Git repository. So, for example, cloning the <filename>poky</filename> Git repository results in a - local Git repository also named <filename>poky</filename>.</para> + local Git repository whose top-level folder is also named <filename>poky</filename>.</para> - <para>It is important to understand the differences between Yocto Project Files created - by unpacking a release tarball as compared to cloning + <para>It is important to understand the differences between the source directory created + by unpacking a released tarball as compared to cloning <filename>git://git.yoctoproject.org/poky</filename>. When you unpack a tarball, you have an exact copy of the files based on the time of release - a fixed release point. - Any changes you make to your local Yocto Project Files are on top of the release. - On the other hand, when you clone the Yocto Project Git repository, you have an + Any changes you make to your local files in the source directory are on top of the release. + On the other hand, when you clone the <filename>poky</filename> Git repository, you have an active development repository. - In this case, any local changes you make to the Yocto Project can be later applied - to active development branches of the upstream Yocto Project Git repository.</para> + In this case, any local changes you make to the source directory can be later applied + to active development branches of the upstream <filename>poky</filename> Git + repository.</para> <para>Finally, if you want to track a set of local changes while starting from the same point as a release tarball, you can create a local Git branch that @@ -329,41 +371,18 @@ see the "<link linkend='repositories-tags-and-branches'>Repositories, Tags, and Branches</link>" section.</para></listitem> - <listitem> - <para id='yocto-project-build-directory'><emphasis>Yocto Project Build Directory:</emphasis> - This term refers to the area used by the Yocto Project for builds. - The area is created when you <filename>source</filename> the Yocto Project setup - environment script that is found in the Yocto Project files area - (i.e. <filename>oe-init-build-env</filename>). - The <ulink url='&YOCTO_DOCS_REF_URL;#var-TOPDIR'><filename>TOPDIR</filename></ulink> - variable points to the build directory.</para> - - <para>You have a lot of flexibility when creating the Yocto Project Build Directory. - Following are some examples that show how to create the directory: - <itemizedlist> - <listitem><para>Create the build directory in your current working directory - and name it <filename>build</filename>. - This is the default behavior. - <literallayout class='monospaced'> - $ cd ~/poky - $ source oe-init-build-env - </literallayout></para></listitem> - <listitem><para>Provide a directory path and specifically name the build - directory. - This next example creates a build directory named <filename>YP-&POKYVERSION;</filename> - in your home directory within the directory <filename>mybuilds</filename>. - If <filename>mybuilds</filename> does not exist, the directory is created for you: - <literallayout class='monospaced'> - $ source &OE_INIT_PATH; $HOME/mybuilds/YP-&POKYVERSION; - </literallayout></para></listitem> - <listitem><para>Provide an existing directory to use as the build directory. - This example uses the existing <filename>mybuilds</filename> directory - as the build directory. - <literallayout class='monospaced'> - $ source &OE_INIT_PATH; $HOME/mybuilds/ - </literallayout></para></listitem> - </itemizedlist> - </para></listitem> + <listitem><para><emphasis>Tasks:</emphasis> Arbitrary groups of software Recipes. + You simply use Tasks to hold recipes that, when built, usually accomplish a single task. + For example, a task could contain the recipes for a company’s proprietary or value-add software. + Or, the task could contain the recipes that enable graphics. + A task is really just another recipe. + Because task files are recipes, they end with the <filename>.bb</filename> filename + extension.</para></listitem> + <listitem><para><emphasis>Upstream:</emphasis> A reference to source code or repositories + that are not local to the development system but located in a master area that is controlled + by the maintainer of the source code. + For example, in order for a developer to work on a particular piece of code, they need to + first get a copy of it from an "upstream" source.</para></listitem> </itemizedlist> </para> </section> @@ -403,7 +422,7 @@ <filename>meta/files/common-licenses</filename>. Once the build completes, the list of all licenses found and used during that build are kept in the - <link linkend='yocto-project-build-directory'>Yocto Project Build Directory</link> at + <link linkend='build-directory'>build directory</link> at <filename>tmp/deploy/images/licenses</filename>. </para> diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml index 4dc2cfca00..15748ebfac 100644 --- a/documentation/dev-manual/dev-manual-start.xml +++ b/documentation/dev-manual/dev-manual-start.xml @@ -24,14 +24,15 @@ <para> The Yocto Project is an open-source collaboration project focused on embedded Linux development. - The project currently provides a build system, which is sometimes referred to as "Poky", - and provides various ancillary tools suitable for the embedded developer. - The Yocto Project also features the Sato reference User Interface, which is optimized for + The project currently provides a build system, which is + referred to as the OpenEmbedded build system in the Yocto Project documentation. + The Yocto Project provides various ancillary tools suitable for the embedded developer + and also features the Sato reference User Interface, which is optimized for stylus driven, low-resolution screens. </para> <para> - You can use the Yocto Project build system, which uses + You can use the OpenEmbedded build system, which uses <ulink url='http://bitbake.berlios.de/manual/'>BitBake</ulink>, to develop complete Linux images and associated user-space applications for architectures based on ARM, MIPS, PowerPC, x86 and x86-64. @@ -53,56 +54,50 @@ <listitem><para><emphasis>Host System:</emphasis> You should have a reasonably current Linux-based host system. You will have the best results with a recent release of Fedora, - OpenSUSE, or Ubuntu as these releases are frequently tested against the Yocto Project + OpenSUSE, Ubuntu, or CentOS as these releases are frequently tested against the Yocto Project and officially supported. You should also have about 100 gigabytes of free disk space for building images. </para></listitem> - <listitem><para><emphasis>Packages:</emphasis> The Yocto Project requires certain packages - exist on your development system (e.g. Python 2.6 or 2.7). + <listitem><para><emphasis>Packages:</emphasis> The OpenEmbedded build system + requires certain packages exist on your development system (e.g. Python 2.6 or 2.7). See "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" section in the Yocto Project Quick Start for the exact package requirements and the installation commands to install them for the supported distributions.</para></listitem> <listitem id='local-yp-release'><para><emphasis>Yocto Project Release:</emphasis> You need a release of the Yocto Project. - You can get set up with local - <link linkend='yocto-project-files'>Yocto Project Files</link> one of two ways - depending on whether you - are going to be contributing back into the Yocto Project source repository or not. + You set up a with local <link linkend='source-directory'>source directory</link> + one of two ways depending on whether you + are going to contribute back into the Yocto Project or not. <note> - Regardless of the method you use, this manual refers to the resulting - hierarchical set of files as the "Yocto Project Files" or the "Yocto Project File - Structure." + Regardless of the method you use, this manual refers to the resulting local + hierarchical set of files as the "source directory." </note> <itemizedlist> <listitem><para><emphasis>Tarball Extraction:</emphasis> If you are not going to contribute - back into the Yocto Project, you can simply download the Yocto Project release you want + back into the Yocto Project, you can simply download a Yocto Project release you want from the website’s <ulink url='&YOCTO_HOME_URL;/download'>download page</ulink>. Once you have the tarball, just extract it into a directory of your choice.</para> <para>For example, the following command extracts the Yocto Project &DISTRO; release tarball - into the current working directory and sets up the Yocto Project file structure - with a top-level directory named <filename>&YOCTO_POKY;</filename>: + into the current working directory and sets up the local source directory + with a top-level folder named <filename>&YOCTO_POKY;</filename>: <literallayout class='monospaced'> $ tar xfj &YOCTO_POKY_TARBALL; </literallayout></para> - <para>This method does not produce a Git repository. - Instead, you simply end up with a local snapshot of the - Yocto Project files that are based on the particular release in the - tarball.</para></listitem> + <para>This method does not produce a local Git repository. + Instead, you simply end up with a snapshot of the release.</para></listitem> <listitem><para><emphasis>Git Repository Method:</emphasis> If you are going to be contributing back into the Yocto Project or you simply want to keep up with the latest developments, you should use Git commands to set up a local - Git repository of the Yocto Project Files. - Doing so creates a Git repository with a complete history of changes and allows + Git repository of the upstream <filename>poky</filename> source repository. + Doing so creates a repository with a complete history of changes and allows you to easily submit your changes upstream to the project. Because you cloned the repository, you have access to all the Yocto Project development branches and tag names used in the upstream repository.</para> - <para>The following transcript shows how to clone the Yocto Project Files' + <para>The following transcript shows how to clone the <filename>poky</filename> Git repository into the current working directory. - <note>The name of the Yocto Project Files Git repository in the Yocto Project Files - Source Repositories is <filename>poky</filename>. - You can view the Yocto Project Source Repositories at + <note>You can view the Yocto Project Source Repositories at <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink></note> The command creates the local repository in a directory named <filename>poky</filename>. For information on Git used within the Yocto Project, see the @@ -131,7 +126,7 @@ copying that cloned repository. You can create the bare clone and the copy of the bare clone anywhere you like. For simplicity, it is recommended that you create these structures outside of the - Yocto Project Files Git repository.</para> + source directory (usually <filename>poky</filename>).</para> <para>As an example, the following transcript shows how to create the bare clone of the <filename>linux-yocto-3.2</filename> kernel and then create a copy of that clone. @@ -166,15 +161,14 @@ edit to point to your locally modified kernel source files and to build the kernel image. Pointing to these local files is much more efficient than requiring a download of the - source files from upstream each time you make changes to the kernel.</para> + kernel's source files from upstream each time you make changes to the kernel.</para> <para>You can find the <filename>poky-extras</filename> Git Repository in the "Yocto Metadata Layers" area of the Yocto Project Source Repositories at <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>. - It is good practice to create this Git repository inside the Yocto Project - files Git repository.</para> + It is good practice to create this Git repository inside the source directory.</para> <para>Following is an example that creates the <filename>poky-extras</filename> Git - repository inside the Yocto Project files Git repository, which is named - <filename>poky</filename> in this case: + repository inside the source directory, which is named <filename>poky</filename> + in this case: <literallayout class='monospaced'> $ git clone git://git.yoctoproject.org/poky-extras poky-extras Initialized empty Git repository in /home/scottrif/poky/poky-extras/.git/ @@ -194,7 +188,7 @@ layer. You can get set up for BSP development one of two ways: tarball extraction or with a local Git repository. - It is a good idea to use the same method used to set up the Yocto Project Files. + It is a good idea to use the same method that you used to set up the source directory. Regardless of the method you use, the Yocto Project uses the following BSP layer naming scheme: <literallayout class='monospaced'> @@ -220,16 +214,16 @@ Again, this method just produces a snapshot of the BSP layer in the form of a hierarchical directory structure.</para></listitem> <listitem><para><emphasis>Git Repository Method:</emphasis> If you are working - with a Yocto Project Files Git repository, you should also use this method + with a local Git repository for your source directory, you should also use this method to set up the <filename>meta-intel</filename> Git repository. You can locate the <filename>meta-intel</filename> Git repository in the "Yocto Metadata Layers" area of the Yocto Project Source Repositories at <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.</para> <para>Typically, you set up the <filename>meta-intel</filename> Git repository inside - the Yocto Project Files Git repository. + the source directory. For example, the following transcript shows the steps to clone the <filename>meta-intel</filename> - Git repository inside the <filename>poky</filename> Git repository. + Git repository inside the local <filename>poky</filename> Git repository. <literallayout class='monospaced'> $ git clone git://git.yoctoproject.org/meta-intel.git Initialized empty Git repository in /home/scottrif/poky/meta-intel/.git/ @@ -268,13 +262,13 @@ <para> The build process is as follows: <orderedlist> - <listitem><para>Make sure you have the Yocto Project files as described in the + <listitem><para>Make sure you have set up the source directory described in the previous section.</para></listitem> <listitem><para>Initialize the build environment by sourcing a build environment script.</para></listitem> <listitem><para>Optionally ensure the <filename>conf/local.conf</filename> configuration file, which is found in the - <link linkend='yocto-project-build-directory'>Yocto Project Build Directory</link>, + <link linkend='build-directory'>build directory</link>, is set up how you want it. This file defines many aspects of the build environment including the target machine architecture through the |