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 ++++++++------------- 1 file changed, 64 insertions(+), 109 deletions(-) (limited to 'documentation/dev-manual/dev-manual-common-tasks.xml') 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. -- cgit v1.2.3-54-g00ecf