From 85673e5466804f6918be72b3b27328783b5ac5c9 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Mon, 2 Jul 2012 09:59:11 -0700 Subject: documentation/dev-manual: Scrub for Yocto Project term I have replaced the term "Yocto Project" with more appropriate terms where possible. (From yocto-docs rev: 622ef9a2b4897ecd151b641b43d7706ab673c989) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-common-tasks.xml | 173 +++++++----------- documentation/dev-manual/dev-manual-intro.xml | 35 ++-- .../dev-manual/dev-manual-kernel-appendix.xml | 92 ++++------ documentation/dev-manual/dev-manual-model.xml | 137 +++++++------- documentation/dev-manual/dev-manual-newbie.xml | 199 +++++++++++---------- documentation/dev-manual/dev-manual-start.xml | 72 ++++---- 6 files changed, 320 insertions(+), 388 deletions(-) (limited to 'documentation/dev-manual') 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 @@ Common Tasks 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 @@ Understanding and Creating Layers - The Yocto Project build system supports organizing metadata + The OpenEmbedded build system supports organizing metadata 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 @@
- Yocto Project Layers + Layers - 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 meta. - For example, when you set up the Yocto Project Files + For example, when you set up the source directory structure, you will see several layers: meta, meta-demoapps, meta-skeleton, and meta-yocto. Each of these folders is a layer. @@ -69,7 +69,7 @@ Creating Your Own Layer - 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: Check Existing Layers: 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 meta-oe does. Consequently, meta-oe uses .bbappend files to modify the QT_SQL_DRIVER_FLAGS variable to enable the appropriate plugins. This variable was added to the qt4.inc include file in - The Yocto Project specifically to allow the meta-oe layer + the source directory specifically to allow the meta-oe layer to be able to control which plugins are built. @@ -187,10 +188,10 @@ Store custom layers in a Git repository that uses the meta-<layer_name> format. Clone the repository alongside other meta - directories in - Yocto Project Files. + directories in the + source directory. - 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.
@@ -199,11 +200,11 @@ Enabling Your Layer - 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 BBLAYERS variable in your conf/bblayers.conf file, which is found in the - Yocto Project Build Directory. + build directory. The following example shows how to enable a layer named meta-mylayer: LCONF_VERSION = "1" @@ -222,8 +223,8 @@ BBLAYERS variable within the conf/bblayers.conf file. During the processing of each conf/layer.conf 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. @@ -267,7 +268,7 @@ As an example, consider the main formfactor recipe and a corresponding formfactor append file both from the - Yocto Project Files. + source directory. Here is the main formfactor recipe, which is named formfactor_0.0.bb and located in the meta layer at meta/recipes-bsp/formfactor: @@ -450,7 +451,7 @@ Customizing Images - 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. @@ -552,13 +553,11 @@ EXTRA_IMAGE_FEATURES - 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 IMAGE_FEATURES variable. To create these features, the best reference is - meta/classes/core-image.bbclass, which shows how the - Yocto Project achieves this. + meta/classes/core-image.bbclass, which shows how to achieve this. In summary, the file looks at the contents of the IMAGE_FEATURES variable and then maps that into a set of tasks or packages. @@ -569,8 +568,8 @@ with specialized image .bb files. You can also add more features by configuring the EXTRA_IMAGE_FEATURES - variable in the local.conf file found in the Yocto Project - files located in the build directory. + variable in the local.conf file found in the source directory + located in the build directory. @@ -648,7 +647,7 @@ Adding a Package - 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 .bb 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. @@ -1001,53 +1000,7 @@
- Porting the Yocto Project to a New Machine - - + Adding a New Machine 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 - 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 "BSP Development Example" in Appendix A. @@ -1072,7 +1025,8 @@ so that there are some definite steps on how to do this. I need more detail her To add a machine configuration you need to add a .conf file with details of the device being added to the conf/machine/ 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. @@ -1110,12 +1064,12 @@ so that there are some definite steps on how to do this. I need more detail her Adding a Kernel for the Machine - 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 meta/recipes-kernel/linux - directory that you can use as references. + source directory at meta/recipes-kernel/linux + that you can use as references. @@ -1153,8 +1107,8 @@ so that there are some definite steps on how to do this. I need more detail her 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 - 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 machconfig file - in the Yocto Project file's meta/recipes-bsp/formfactor/files + in the meta/recipes-bsp/formfactor/files directory. This directory contains directories for specific machines such as qemuarm and qemux86. @@ -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 meta/conf/multilib.conf - 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 BBCLASSEXTEND variable. Eventually, all recipes will be covered and this list will be unneeded. @@ -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 local.conf configuration file in the - Yocto Project Build Directory. + build directory. An example configuration would be as follows: MACHINE = "qemux86-64" @@ -1311,7 +1265,7 @@ so that there are some definite steps on how to do this. I need more detail her A unique architecture is defined for the Multilib packages, along with creating a unique deploy folder under tmp/deploy/rpm in the - Yocto Project Build Directory. + build directory. For example, consider lib32 in a qemux86-64 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 menuconfig tool in the Yocto Project development environment, you must build the tool using BitBake. The following commands build and invoke menuconfig assuming the - Yocto Project files top-level directory is ~/poky: + source directory top-level folder is ~/poky: $ 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 SRC_URI. - 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 linux-yocto_3.0.bbappend file: @@ -1608,7 +1562,7 @@ so that there are some definite steps on how to do this. I need more detail her 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 distro_check + The OpenEmbedded build system implements a distro_check 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 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 DISTRO_PN_ALIAS 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. $ bitbake world -f -c distro_check The results are stored in the build/tmp/log/distro_check-${DATETIME}.results - file found in the Yocto Project files area. + file found in the source directory.
@@ -1649,18 +1603,18 @@ so that there are some definite steps on how to do this. I need more detail her Building Software from an External Source - By default, the Yocto Project build system does its work from within the - Yocto Project Build Directory. + By default, the OpenEmbedded build system does its work from within the + build directory. The build process involves fetching the source files, unpacking them, and then patching them if necessary before the build takes place. Situations exist where you might want to build software from source files that are external to - and thus outside of the Yocto Project Files. + and thus outside of the source directory. 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 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: /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 - Alternatively, the Yocto Project can build the gdb-cross binary. + Alternatively, you can use BitBake to build the gdb-cross binary. Here is an example: $ bitbake gdb-cross @@ -1871,13 +1825,14 @@ so that there are some definite steps on how to do this. I need more detail her - 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 tmp/rootfs directory. This directory contains the contents of the last built image. This process assumes two things: The image running on the target was the last image to - be built by the Yocto Project. + be built. The package (foo in the following example) that contains the inferior binary to be debugged has been built without optimization and has debugging information available. @@ -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. @@ -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 -fno-omit-framepointer flag. - In the Yocto Project you can achieve this by setting the + You can achieve this by setting the SELECTED_OPTIMIZATION variable to -fexpensive-optimizations -fno-omit-framepointer -frename-registers -O2. @@ -2036,7 +1991,7 @@ so that there are some definite steps on how to do this. I need more detail her To profile the kernel, you would specify the --vmlinux=/path/to/vmlinux option. - The vmlinux file is usually in the Yocto Project file's + The vmlinux file is usually in the source directory in the /boot/ directory and must match the running kernel. @@ -2079,7 +2034,7 @@ so that there are some definite steps on how to do this. I need more detail her - 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 OProfileUI README 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 - Downloaded archives reside in the Yocto Project's build directory in + Downloaded archives reside in the build directory in /tmp and are cleared up when they are no longer in use. If you wish to perform kernel profiling, you need to be sure a vmlinux 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 /boot/vmlinux-KERNELVERSION, where KERNEL-version is the version of the kernel. - The Yocto Project generates separate vmlinux packages for each kernel - it builds. + The OpenEmbedded build system generates separate vmlinux + packages for each kernel it builds. Thus, it should just be a question of making sure a matching package is installed (e.g. opkg install kernel-vmlinux. 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 "Launching GDB on the Host Computer" 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. 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. @@ -44,13 +45,7 @@ applications. An overview and understanding of the emulation environment used with the Yocto Project (QEMU). - - An understanding of basic kernel architecture and - concepts. - + An understanding of basic kernel architecture and concepts. Many references to other sources of related information. @@ -97,7 +92,7 @@ The Yocto Project Reference Manual: 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. @@ -117,7 +112,7 @@ some work flow examples. - Yocto Eclipse Plug-in: A step-by-step instructional video that + Eclipse IDE Yocto Plug-in: A step-by-step instructional video that demonstrates how an application developer uses Yocto Plug-in features within the Eclipse IDE. @@ -158,22 +153,26 @@ Internet Relay Chat (IRC): Two IRC channels on freenode are available for Yocto Project and Poky discussions: #yocto and - #poky. + #poky, respectively. OpenedHand: - The company where the Yocto Project build system Poky was first developed. - OpenedHand has since been acquired by Intel Corporation. + 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. Intel Corporation: - The company that acquired OpenedHand in 2008 and continues development on the - Yocto Project. + A multinational semiconductor chip manufacturer company whose Software and + Services Group created and supports the Yocto Project. + Intel acquired OpenedHand in 2008. OpenEmbedded: - The upstream, generic, embedded distribution the Yocto Project build system (Poky) derives - from and to which it contributes. + 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. - BitBake: The tool used to process Yocto Project metadata. + BitBake: The tool used by the OpenEmbedded build systm + to process project metadata. BitBake User Manual: 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. -
@@ -45,18 +34,17 @@ Briefly, you need the following: A local - Yocto Project Files - Git repository - The + source directory for the + poky Git repository + Local copies of the poky-extras - Git repository placed within the local Yocto Project files Git - repository + Git repository placed within the source directory. A bare clone of the Linux Yocto Kernel upstream Git repository to which you want to push your modifications. A copy of that bare clone in which you make your source - modifcations + modifications @@ -78,18 +66,19 @@ Here is a brief description of the four areas: - Local Yocto Project Files Git Repository: - 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 + Local Source Directory: + 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 poky-extras Git repository. See the bulleted item "Yocto Project Release" - for information on how to get these files. - poky-extras Git Repository: + for information on how to get these files on your local system. + Local copies of thepoky-extras + Git Repository: This area contains the meta-kernel-dev layer, which is where you make changes that append the kernel build recipes. You edit .bbappend files to locate your @@ -133,23 +122,23 @@
- Setting Up the Local Yocto Project Files Git Repository + Setting Up the Local Source Directory - 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 poky Git repository. This example uses poky as the root directory of the - local Yocto Project files Git repository. + local source directory. See the bulleted item "Yocto Project Release" for information on how to get these files. - 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: $ cd poky $ git branch -a @@ -168,15 +157,15 @@
- Setting Up the poky-extras Git Repository + Setting Up the Local poky-extras Git Repository - This example places the poky-extras Git repository inside - of poky. - See the bulleted item - "The + This example creates a local copy of the poky-extras Git + repository inside the poky source directory. + See the bulleted item "The poky-extras Git Repository" - for information on how to get the poky-extras repository. + for information on how to set up a local copy of the + poky-extras repository. @@ -369,7 +358,7 @@ 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. @@ -386,7 +375,7 @@ 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 @@ KSRC_linux_yocto_3_2 ?= "/home/scottrif/linux-yocto-3.2.git" - @@ -494,7 +477,7 @@ $ bitbake -c cleanall linux-yocto Never remove any files by hand from the tmp/deploy - directory insided the local Yocto Project files build directory. + directory insided the build directory. Always use the BitBake cleanall task to clear out previous builds. Next, build the kernel image using this command: @@ -539,7 +522,7 @@ If you took the time to work through the example that modifies the kernel source code in "Modifying the Kernel Source - Code" you should already have the Yocto Project files set up on your + Code" 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 "Examining the Default @@ -548,21 +531,21 @@ - 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 poky Git repository. This example uses poky as the root directory of the - local Yocto Project Files Git repository. + source directory. See the bulleted item "Yocto Project Release" for information on how to get these files. - 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: $ cd poky $ git branch -a @@ -680,7 +663,7 @@ to set kernel configurations. You need to run menuconfig inside the Yocto BitBake environment. Thus, the environment must be set up using the oe-init-build-env - 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: $ 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 linux-yocto-3.2 kernel. - The Yocto Project build environment recognizes this kernel as + The OpenEmbedded build system recognizes this kernel as linux-yocto. 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: ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-3.2.11+git1+84f... @@ -762,7 +744,7 @@ Be sure to make a copy of the .config and don't just rename it. - The Yocto Project build system needs an existing .config + The build system needs an existing .config from which to work. 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. Image Development using Hob: You can use the Hob to build - custom operating system images within the Yocto Project build environment. - Hob provides an efficient interface to the Yocto Project build system. + custom operating system images within the build environment. + Hob provides an efficient interface to the OpenEmbedded build system. @@ -94,18 +94,20 @@ and the "The Packages" sections both in the Yocto Project Quick Start for requirements. - Establish a local copy of the Yocto Project files on your - system: 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 + Establish a local copy of the project files on your + system: You need this source + directory available on your host system. + Having these files on your system gives you access to the build process and to the tools you need. - For information on how to get these files, see the + For information on how to set up the source directory, see the "Getting Setup" section. Establish a local copy of the base BSP files: 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 "Getting Setup" section. - Choose a Yocto Project-supported BSP as your base BSP: + Choose a BSP that is supported by the Yocto Project + as your base BSP: 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 "Understanding and Creating Layers" @@ -146,11 +148,11 @@ For more information on BSP layers, see the "BSP Layers" section in the Yocto Project Board Support Package (BSP) Developer's Guide. - The Yocto Project supports four BSPs that are part of the + Four BSPs exist that are part of the Yocto Project release: atom-pc, beagleboard, mpc8315e, and routerstationpro. The recipes and configurations for these four BSPs are located and dispersed - within the Yocto Project Files. + within the source directory. 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 meta-crownbay layer inside the - local Yocto Project files. + source directory. Make configuration changes to your new BSP layer: The standard BSP layer structure organizes the files you need to edit in conf and several recipes-* @@ -177,15 +179,15 @@ Prepare for the build: Once you have made all the changes to your BSP layer, there remains a few things - you need to do for the 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. The entire process for building an image is overviewed in the section "Building an Image" section of the Yocto Project Quick Start. You might want to reference this information. - Build the image: The Yocto Project uses the BitBake - tool to build images based on the type of image you want to create. + Build the image: The OpenEmbedded build system + uses the BitBake tool to build images based on the type of image you want to create. You can find more information on BitBake here. The build process supports several types of images to satisfy different needs. @@ -295,7 +297,7 @@ 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 @@ 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 @@ 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 SRC_URI variable and gathered in a temporary work area where they are subsequently used to create the unique kernel. Thus, in a sense, the process constructs a local source tree specific to your @@ -375,7 +377,7 @@ - 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 The Yocto Project Kernel Architecture and Use Manual. @@ -404,18 +406,19 @@ "The Linux Distributions" and "The Packages" sections both in the Yocto Project Quick Start for requirements. - Establish a local copy of the Yocto Project files on your - system: Having the Yocto Project files on your system gives you access to - the build process and tools you need. + Establish a local copy of project files on your + system: Having the source + directory on your system gives you access to the build process and tools + you need. For information on how to get these files, see the bulleted item "Yocto Project Release" earlier in this manual. - Set up the poky-extras Git - repository: This repository is the area for your configuration + Set up a local copy of the poky-extras Git + repository: This local repository is the area for your configuration fragments, new kernel recipes, and the kernel .bbappend 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 "The poky-extras Git Repository" earlier in this manual. @@ -453,9 +456,9 @@ .config. Try to resist the temptation of directly editing the .config file found in the - Yocto Project Build Directory at + build directory at tmp/sysroots/<machine-name>/kernel. - 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. Once you are satisfied with the configuration changes made using menuconfig, you can directly examine the @@ -465,7 +468,7 @@ Add or extend kernel recipes if applicable: The standard layer structure organizes recipe files inside the - meta-kernel-dev layer that is within the + meta-kernel-dev layer that is within the local poky-extras Git repository. If you need to add new kernel recipes, you add them within this layer. Also within this area, you will find the .bbappend @@ -475,7 +478,7 @@ Prepare for the build: 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. - Build the image: The Yocto Project - build system Poky uses the BitBake + Build the image: The OpenEmbedded + build system uses the BitBake tool to build images based on the type of image you want to create. You can find more information on BitBake here. @@ -514,7 +517,7 @@
-
+
Application Development Workflow @@ -530,7 +533,7 @@ - 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 @@ Workflow Using the ADT and <trademark class='trade'>Eclipse</trademark> - 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 @@ - This illustration and the following list summarizes the application development general workflow. + The following illustration and list summarize the application development general workflow. @@ -565,27 +567,9 @@ "The Linux Distributions" and "The Packages" sections both in the Yocto Project Quick Start for requirements. - - - Secure the Linux Yocto Kernel Target Image: - You must have a target kernel image that has been built using the Yocto Project. + You must have a target kernel image that has been built using the OpenEmbeded + build system. 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 Install the ADT: 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 Modifying Temporary Source Code - 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 - Yocto Project's Build Directory, and then + build directory, and then you can force a re-compile and quickly test your altered code. Once you settle on a solution, you can then preserve your changes in the form of patches. @@ -728,12 +712,12 @@ WRITER NOTE: The areas to get the kernel and root filesystem are located in the 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 S variable. Below is the default value for the S variable as defined in the meta/conf/bitbake.conf configuration file in the - Yocto Project Files: + source directory: S = ${WORKDIR}/${BP} @@ -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} Let's look at an example without variables. - Assuming a Yocto Project Files top-level directory named poky - and a default Yocto Project Build Directory of poky/build, + Assuming a top-level source directory named poky + and a default build directory of poky/build, the following is the work directory for the acl package: ~/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 ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}-${PV}-${PR} - Again, assuming a Yocto Project Files top-level directory named poky - and a default Yocto Project Build Directory of poky/build, the + Again, assuming top-level source directory named poky + and a default build directory of poky/build, the following is the work directory for the acl package that is being built for a MIPS-based device: @@ -781,7 +765,7 @@ WRITER NOTE: The areas to get the kernel and root filesystem are located in the - 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 WORKDIR, TMPDIR, @@ -817,8 +801,8 @@ WRITER NOTE: The areas to get the kernel and root filesystem are located in the Follow these general steps: Find the Source Code: - 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 "Finding the Temporary Source Code" 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 Copy the Patch File: For simplicity, copy the patch file into a directory named files, 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 SRC_URI @@ -904,16 +888,15 @@ WRITER NOTE: The areas to get the kernel and root filesystem are located in the 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. Follow these general steps: Find the Source Code: - 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 "Finding the Temporary Source Code" 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 Copy the Patch File: For simplicity, copy the patch file into a directory named files, 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 SRC_URI @@ -1024,11 +1007,11 @@ WRITER NOTE: The areas to get the kernel and root filesystem are located in the Image Development Using Hob - The Hob is a graphical user interface for the Yocto - Project build system based on BitBake. + The Hob 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. 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 @@
- Using The Yocto Project in a Team Environment + Using the Yocto Project in a Team Environment It might not be immediately clear how you can use the Yocto Project in a team environment, @@ -97,19 +97,20 @@ 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. 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. @@ -147,8 +148,8 @@ download page 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. @@ -157,22 +158,22 @@ - 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: Source Repositories: 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. + You can create local copies of Git repositories for each of these areas. Index of /releases: This area contains index releases such as the Eclipse - 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. + 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. @@ -199,7 +200,7 @@ Append Files: Files that append build information to a recipe file. Append files are known as BitBake append files and .bbappend 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 (.bb) 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 @@ "Changing recipes-kernel" sections. BitBake: 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 BitBake documentation. + + Build Directory: + This term refers to the area used by the OpenEmbedded build system for builds. + The area is created when you source the setup + environment script that is found in the source directory + (i.e. oe-init-build-env). + The TOPDIR + variable points to the build directory. + + You have a lot of flexibility when creating the build directory. + Following are some examples that show how to create the directory: + + Create the build directory in your current working directory + and name it build. + This is the default behavior. + + $ source oe-init-build-env + + Provide a directory path and specifically name the build + directory. + This next example creates a build directory named YP-&POKYVERSION; + in your home directory within the directory mybuilds. + If mybuilds does not exist, the directory is created for you: + + $ source &OE_INIT_PATH; $HOME/mybuilds/YP-&POKYVERSION; + + Provide an existing directory to use as the build directory. + This example uses the existing mybuilds directory + as the build directory. + + $ source &OE_INIT_PATH; $HOME/mybuilds/ + + + + Build System: 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 + poky term further along in this section. + Classes: 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 @@ Configuration File: Configuration information in various .conf files provides global definitions of variables. The conf/local.conf configuration file in the - Yocto Project Build Directory + build directory contains user-defined variables that affect each build. The meta-yocto/conf/distro/poky.conf 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 + source directory, define variables for specific hardware and are only used when building for that target (e.g. the machine/beagleboard.conf 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. OE-Core: A core set of metadata originating with OpenEmbedded (OE) that is shared between OE and the Yocto Project. - This metadata is found in the meta directory of the Yocto Project - files. + This metadata is found in the meta directory of the source + directory. Package: 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. - Poky: The build tool that the Yocto Project - uses to create images. + Poky: 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. Recipe: 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 .bb file extension. - Tasks: 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 .bb filename - extension. - Upstream: 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. - Yocto Project Files: + Source Directory: 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 git://git.yoctoproject.org/poky. - Sometimes the term "the Yocto Project Files structure" is used as well. - - 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 + poky Git repository git://git.yoctoproject.org/poky. + Sometimes you might here the term "poky directory" used to refer to this + directory structure. + + 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. - The name of the top-level directory of the Yocto Project Files structure + 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 &YOCTO_POKY_TARBALL; - 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 &YOCTO_POKY;. - 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, poky is used as the name of + the top-level folder of the local copy of the poky Git repository. So, for example, cloning the poky Git repository results in a - local Git repository also named poky. + local Git repository whose top-level folder is also named poky. - It is important to understand the differences between Yocto Project Files created - by unpacking a release tarball as compared to cloning + It is important to understand the differences between the source directory created + by unpacking a released tarball as compared to cloning git://git.yoctoproject.org/poky. 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 poky 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. + In this case, any local changes you make to the source directory can be later applied + to active development branches of the upstream poky Git + repository. 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 "Repositories, Tags, and Branches" section. - - Yocto Project Build Directory: - This term refers to the area used by the Yocto Project for builds. - The area is created when you source the Yocto Project setup - environment script that is found in the Yocto Project files area - (i.e. oe-init-build-env). - The TOPDIR - variable points to the build directory. - - You have a lot of flexibility when creating the Yocto Project Build Directory. - Following are some examples that show how to create the directory: - - Create the build directory in your current working directory - and name it build. - This is the default behavior. - - $ cd ~/poky - $ source oe-init-build-env - - Provide a directory path and specifically name the build - directory. - This next example creates a build directory named YP-&POKYVERSION; - in your home directory within the directory mybuilds. - If mybuilds does not exist, the directory is created for you: - - $ source &OE_INIT_PATH; $HOME/mybuilds/YP-&POKYVERSION; - - Provide an existing directory to use as the build directory. - This example uses the existing mybuilds directory - as the build directory. - - $ source &OE_INIT_PATH; $HOME/mybuilds/ - - - + Tasks: 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 .bb filename + extension. + Upstream: 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.
@@ -403,7 +422,7 @@ meta/files/common-licenses. Once the build completes, the list of all licenses found and used during that build are kept in the - Yocto Project Build Directory at + build directory at tmp/deploy/images/licenses. 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 @@ 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. - You can use the Yocto Project build system, which uses + You can use the OpenEmbedded build system, which uses BitBake, 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 @@ Host System: 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. - Packages: The Yocto Project requires certain packages - exist on your development system (e.g. Python 2.6 or 2.7). + Packages: The OpenEmbedded build system + requires certain packages exist on your development system (e.g. Python 2.6 or 2.7). See "The Packages" section in the Yocto Project Quick Start for the exact package requirements and the installation commands to install them for the supported distributions. Yocto Project Release: You need a release of the Yocto Project. - You can get set up with local - Yocto Project Files 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 source directory + one of two ways depending on whether you + are going to contribute back into the Yocto Project or not. - 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." Tarball Extraction: 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 download page. Once you have the tarball, just extract it into a directory of your choice. 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 &YOCTO_POKY;: + into the current working directory and sets up the local source directory + with a top-level folder named &YOCTO_POKY;: $ tar xfj &YOCTO_POKY_TARBALL; - 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. + This method does not produce a local Git repository. + Instead, you simply end up with a snapshot of the release. Git Repository Method: 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 poky 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. - The following transcript shows how to clone the Yocto Project Files' + The following transcript shows how to clone the poky Git repository into the current working directory. - The name of the Yocto Project Files Git repository in the Yocto Project Files - Source Repositories is poky. - You can view the Yocto Project Source Repositories at + You can view the Yocto Project Source Repositories at The command creates the local repository in a directory named poky. 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. + source directory (usually poky). As an example, the following transcript shows how to create the bare clone of the linux-yocto-3.2 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. + kernel's source files from upstream each time you make changes to the kernel. You can find the poky-extras Git Repository in the "Yocto Metadata Layers" area of the Yocto Project Source Repositories at . - It is good practice to create this Git repository inside the Yocto Project - files Git repository. + It is good practice to create this Git repository inside the source directory. Following is an example that creates the poky-extras Git - repository inside the Yocto Project files Git repository, which is named - poky in this case: + repository inside the source directory, which is named poky + in this case: $ 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: @@ -220,16 +214,16 @@ Again, this method just produces a snapshot of the BSP layer in the form of a hierarchical directory structure. Git Repository Method: 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 meta-intel Git repository. You can locate the meta-intel Git repository in the "Yocto Metadata Layers" area of the Yocto Project Source Repositories at . Typically, you set up the meta-intel Git repository inside - the Yocto Project Files Git repository. + the source directory. For example, the following transcript shows the steps to clone the meta-intel - Git repository inside the poky Git repository. + Git repository inside the local poky Git repository. $ git clone git://git.yoctoproject.org/meta-intel.git Initialized empty Git repository in /home/scottrif/poky/meta-intel/.git/ @@ -268,13 +262,13 @@ The build process is as follows: - Make sure you have the Yocto Project files as described in the + Make sure you have set up the source directory described in the previous section. Initialize the build environment by sourcing a build environment script. Optionally ensure the conf/local.conf configuration file, which is found in the - Yocto Project Build Directory, + build directory, is set up how you want it. This file defines many aspects of the build environment including the target machine architecture through the -- cgit v1.2.3-54-g00ecf