From f735e50c63ac9f0cd15ad6ad38e46565846fffe8 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Mon, 22 Oct 2012 14:16:22 -0700 Subject: documentation: poky-ref-manual - Final changes before the 1.3 lockdown. various changes as required. (From yocto-docs rev: 7f166508337c9d4aadad23997470a8871c5e42a4) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/poky-ref-manual/introduction.xml | 2 +- documentation/poky-ref-manual/ref-bitbake.xml | 2 +- documentation/poky-ref-manual/ref-classes.xml | 10 +-- documentation/poky-ref-manual/ref-features.xml | 4 +- documentation/poky-ref-manual/ref-structure.xml | 38 +++++----- documentation/poky-ref-manual/ref-variables.xml | 87 +++++++++++----------- .../poky-ref-manual/technical-details.xml | 15 +++- documentation/poky-ref-manual/usingpoky.xml | 16 ++-- 8 files changed, 90 insertions(+), 84 deletions(-) diff --git a/documentation/poky-ref-manual/introduction.xml b/documentation/poky-ref-manual/introduction.xml index fb4cc79d0c..ab2e7d0f31 100644 --- a/documentation/poky-ref-manual/introduction.xml +++ b/documentation/poky-ref-manual/introduction.xml @@ -306,7 +306,7 @@ Development Checkouts Development using the Yocto Project requires a local - source directory. + Source Directory. You can set up the source directory by downloading a Yocto Project release tarball and unpacking it, or by cloning a copy of the upstream Poky Git repository. diff --git a/documentation/poky-ref-manual/ref-bitbake.xml b/documentation/poky-ref-manual/ref-bitbake.xml index d4b8584a46..b81f12fb7a 100644 --- a/documentation/poky-ref-manual/ref-bitbake.xml +++ b/documentation/poky-ref-manual/ref-bitbake.xml @@ -36,7 +36,7 @@ The first thing BitBake does is look for the bitbake.conf file. This file resides in the - source directory + Source Directory within the meta/conf/ directory. BitBake finds it by examining its BBPATH environment diff --git a/documentation/poky-ref-manual/ref-classes.xml b/documentation/poky-ref-manual/ref-classes.xml index cc403a95fa..973d065f58 100644 --- a/documentation/poky-ref-manual/ref-classes.xml +++ b/documentation/poky-ref-manual/ref-classes.xml @@ -13,7 +13,7 @@ Class files are identified by the extension .bbclass and are usually placed in a classes/ directory beneath the meta*/ directory found in the - source directory. + Source Directory. Class files can also be pointed to by BUILDDIR (e.g. build/)in the same way as .conf files in the conf directory. Class files are searched for in BBPATH @@ -302,7 +302,7 @@ PACKAGE_CLASSES variable defined in the local.conf configuration file, which is located in the conf folder of the - source directory. + Source Directory. When defining the variable, you can specify one or more package types. Since images are generated from packages, a packaging class is needed to enable image generation. @@ -538,7 +538,7 @@ you can use this class to specify those packages and associate the users and groups with those packages. The meta-skeleton/recipes-skeleton/useradd/useradd-example.bb - recipe in the source directory + recipe in the Source Directory provides a simple exmample that shows how to add three users and groups to two packages. See the useradd-example.bb for more information on how to @@ -568,7 +568,7 @@ B variable to point to the directory in which the OpenEmbedded build system places the generated objects built from the recipes. By default, the B directory is set to the following, which is separate from the - source directory (S): + Source Directory (S): ${WORKDIR}/${BPN}-{PV}/ @@ -616,7 +616,7 @@ Thus far, this chapter has discussed only the most useful and important classes. However, other classes exist within the meta/classes directory - in the source directory. + in the Source Directory. You can examine the .bbclass files directly for more information. diff --git a/documentation/poky-ref-manual/ref-features.xml b/documentation/poky-ref-manual/ref-features.xml index 063eaadc43..fd0bd29ff7 100644 --- a/documentation/poky-ref-manual/ref-features.xml +++ b/documentation/poky-ref-manual/ref-features.xml @@ -223,7 +223,7 @@ You can disable the feature without affecting other existing distro configurations that need PulseAudio support by adding "pulseaudio" to - DISTRO_FEATURES_BACKFILL_CONSIDERED + DISTRO_FEATURES_BACKFILL_CONSIDERED in your distro's .conf file. Adding the feature to this variable when it also exists in the DISTRO_FEATURES_BACKFILL @@ -240,7 +240,7 @@ You can disable RTC support for your device without affecting other machines that need RTC support by adding the feature to your machine's - MACHINE_FEATURES_BACKFILL_CONSIDERED + MACHINE_FEATURES_BACKFILL_CONSIDERED list in the machine's .conf file. Adding the feature to this variable when it also exists in the MACHINE_FEATURES_BACKFILL diff --git a/documentation/poky-ref-manual/ref-structure.xml b/documentation/poky-ref-manual/ref-structure.xml index ece4894528..be2773b624 100644 --- a/documentation/poky-ref-manual/ref-structure.xml +++ b/documentation/poky-ref-manual/ref-structure.xml @@ -7,14 +7,14 @@ Source Directory Structure - The source directory consists of several components. + The Source Directory consists of several components. Understanding them and knowing where they are located is key to using the Yocto Project well. - This chapter describes the source directory and gives information about the various + This chapter describes the Source Directory and gives information about the various files and directories. - For information on how to establish a local source directory on your development system, see the + For information on how to establish a local Source Directory on your development system, see the "Getting Set Up" section in the Yocto Project Development Manual. @@ -26,7 +26,7 @@ <filename>bitbake/</filename> - The source directory + The Source Directory includes a copy of BitBake for ease of use. The copy usually matches the current stable BitBake release from the BitBake project. BitBake, a metadata interpreter, reads the Yocto Project metadata and runs the tasks @@ -39,7 +39,7 @@ When you run the bitbake command, the wrapper script in scripts/ is executed to run the main BitBake executable, which resides in the bitbake/bin/ directory. - Sourcing the oe-init-build-env + Sourcing the &OE_INIT_FILE; script places the scripts and bitbake/bin directories (in that order) into the shell's PATH environment variable. @@ -59,19 +59,19 @@ This directory contains user configuration files and the output generated by the OpenEmbedded build system in its standard configuration where the source tree is combined with the output. - The build directory + The Build Directory is created initially when you source - the OpenEmbedded build environment setup script oe-init-build-env. + the OpenEmbedded build environment setup script &OE_INIT_FILE;. It is also possible to place output and configuration files in a directory separate from the - source directory + Source Directory by providing a directory name when you source the setup script. - For information on separating output from your local source directory files, see oe-init-build-env. + For information on separating output from your local Source Directory files, see &OE_INIT_FILE;. @@ -141,7 +141,7 @@ This directory contains various integration scripts that implement extra functionality in the Yocto Project environment (e.g. QEMU scripts). - The oe-init-build-env script appends this + The &OE_INIT_FILE; script appends this directory to the shell's PATH environment variable. @@ -153,7 +153,7 @@
- <filename>oe-init-build-env</filename> + <filename>&OE_INIT_FILE;</filename> This script sets up the OpenEmbedded build environment. @@ -166,16 +166,16 @@ - By default, running this script without a build directory argument creates the + By default, running this script without a Build Directory argument creates the build directory. - If you provide a build directory argument when you source + If you provide a Build Directory argument when you source the script, you direct OpenEmbedded build system to create a - build directory of your choice. - For example, the following command creates a build directory named + Build Directory of your choice. + For example, the following command creates a Build Directory named mybuilds that is outside of the - source directory: + Source Directory: - $ source oe-init-build-env ~/mybuilds + $ source &OE_INIT_FILE; ~/mybuilds
@@ -387,7 +387,7 @@ data. Packages that need to share output with other packages do so within this directory. The directory is subdivided by architecture so multiple builds can run within - the one build directory. + the one Build Directory. diff --git a/documentation/poky-ref-manual/ref-variables.xml b/documentation/poky-ref-manual/ref-variables.xml index 8663cc463c..ac068228cf 100644 --- a/documentation/poky-ref-manual/ref-variables.xml +++ b/documentation/poky-ref-manual/ref-variables.xml @@ -93,8 +93,8 @@ B - The build directory. - The OpenEmbedded build system places generated objects into the build directory + The Build Directory. + The OpenEmbedded build system places generated objects into the Build Directory during a recipe's build process. By default, this directory is the same as the S directory: @@ -165,7 +165,7 @@ Use the BBMASK variable from within the conf/local.conf file found - in the build directory. + in the Build Directory. @@ -250,7 +250,7 @@ Lists the layers to enable during the build. This variable is defined in the bblayers.conf configuration - file in the build directory. + file in the Build Directory. Here is an example: BBLAYERS = " \ @@ -362,7 +362,7 @@ than /usr/bin. You can find a list of these variables at the top of the /meta/conf/bitbake.conf file in the - source directory. + Source Directory. @@ -384,7 +384,7 @@ Specifies the list of packages to be added to the image. This variable should only be set in the local.conf configuration file found in the - build directory. + Build Directory. @@ -581,7 +581,7 @@ This directory is self-maintaining and you should not have to touch it. By default, the directory is downloads in the - build directory. + Build Directory. #DL_DIR ?= "${TOPDIR}/downloads" @@ -755,7 +755,7 @@ than /usr/bin. You can find a list of these variables at the top of the /meta/conf/bitbake.conf file in the - source directory. + Source Directory. @@ -821,7 +821,7 @@ The default value for the FILESPATH variable is defined in the base.bbclass class found in meta/classes in the - source directory: + Source Directory: FILESPATH = "${@base_set_filespath([ "${FILE_DIRNAME}/${PF}", \ "${FILE_DIRNAME}/${P}", "${FILE_DIRNAME}/${PN}", \ @@ -848,14 +848,14 @@ FILESPATH = "${@base_set_filespath([ "${FILE_DIRNAME}/${PF}", \ By default, the OpenEmbedded build system uses the fs-perms.txt, which is located in the meta/files folder in the - source directory. + Source Directory. If you create your own file permissions setting table, you should place it in your layer or the distros layer. You define the FILESYSTEM_PERMS_TABLES variable in the conf/local.conf file, which is found in the - build directory, to + Build Directory, to point to your custom fs-perms.txt. You can specify more than a single file permissions setting table. The paths you specify to these files must be defined within the @@ -1200,20 +1200,16 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" Values for this variable are set in the kernel's recipe file and the kernel's append file. For example, if you are using the Yocto Project kernel that is based on the - Linux 3.2 kernel, the kernel recipe file is the - meta/recipes-kernel/linux/linux-yocto_3.2.bb file. - Following is the default value for KBRANCH and the five overrides - for the architectures the Yocto Project supports: + Linux 3.4 kernel, the kernel recipe file is the + meta/recipes-kernel/linux/linux-yocto_3.4.bb file. + Following is the default value for KBRANCH and the default + override for the architectures the Yocto Project supports: - KBRANCH = "standard/default/base" - KBRANCH_qemux86 = "standard/default/common-pc/base" - KBRANCH_qemux86-64 = "standard/default/common-pc-64/base" - KBRANCH_qemuppc = "standard/default/qemu-ppc32" - KBRANCH_qemumips = "standard/default/mti-malta32-be" - KBRANCH_qemuarm = "standard/default/arm-versatile-926ejs" + KBRANCH_DEFAULT = "standard/base" + KBRANCH = "${KBRANCH_DEFAULT}" - Each of the above branches exist in the linux-yocto-3.2 kernel Git - repository . + This branch exists in the linux-yocto-3.4 kernel Git + repository . @@ -1222,16 +1218,16 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" The kernel's append file is located in the BSP layer for a given machine. For example, the kernel append file for the Crown Bay BSP is in the meta-intel Git repository and is named - meta-crownbay/recipes-kernel/linux/linux-yocto_3.2.bbappend. + meta-crownbay/recipes-kernel/linux/linux-yocto_3.4.bbappend. Here are the related statements from the append file: COMPATIBLE_MACHINE_crownbay = "crownbay" KMACHINE_crownbay = "crownbay" - KBRANCH_crownbay = "standard/default/crownbay" - + KBRANCH_crownbay = "standard/crownbay" + COMPATIBLE_MACHINE_crownbay-noemgd = "crownbay-noemgd" KMACHINE_crownbay-noemgd = "crownbay" - KBRANCH_crownbay-noemgd = "standard/default/crownbay" + KBRANCH_crownbay-noemgd = "standard/crownbay" The KBRANCH_* statements identify the kernel branch to use when building for the Crown Bay BSP. @@ -1294,10 +1290,13 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" Kernel machine names are initially defined in the - Yocto Project Kernel in + Yocto Linux Kernel in + the meta branch. + From the meta branch, look in the meta/cfg/kernel-cache/bsp/<bsp_name>/<bsp-name>-<kernel-type>.scc file. - For example, in the linux-yocto-3.4 kernel in the - meta/cfg/kernel-cache/bsp/cedartrail/cedartrail-standard.scc file, + For example, from the meta branch in the + linux-yocto-3.0 kernel, the + meta/cfg/kernel-cache/bsp/cedartrail/cedartrail-standard.scc file has the following: define KMACHINE cedartrail @@ -1307,7 +1306,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" include ktypes/standard branch cedartrail - include cedartrail.scc + include cedartrail.scc You can see that the kernel understands the machine name for the Cedar Trail BSP as cedartrail. @@ -1795,7 +1794,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" This variable, which is set in the local.conf configuration file found in the conf folder of the - source directory, + Source Directory, specifies the package manager to use when packaging data. You can provide one or more arguments for the variable with the first argument being the package manager used to create images: @@ -2134,7 +2133,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" S - The location in the build directory + The location in the Build Directory where unpacked package source code resides. This location is within the working directory (WORKDIR), which @@ -2147,9 +2146,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" ${WORKDIR}/${PN}-${PV} As an example, assume a - source directory top-level + Source Directory top-level folder named poky - and a default build directory + and a default Build Directory at poky/build. In this case, the working directory the build system uses to build the db package is the following: @@ -2578,7 +2577,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" the upstream GCC or CodeSourcery Labs toolchain. The variable identifies the tcmode-* files used in the meta/conf/distro/include directory, which is found in the - source directory. + Source Directory. By default, TCMODE is set to "default", which @@ -2598,14 +2597,14 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" uses when it does its work building images. By default, the TMPDIR variable is named tmp within the - build directory. + Build Directory. If you want to establish this directory in a location other than the default, you can uncomment the following statement in the conf/local.conf file in the - source directory: + Source Directory: #TMPDIR = "${TOPDIR}/tmp" @@ -2617,9 +2616,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" This variable is the - build directory. + Build Directory. BitBake automatically sets this variable. - The OpenEmbedded build system uses the build directory when building images. + The OpenEmbedded build system uses the Build Directory when building images. @@ -2664,9 +2663,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" ${TMPDIR}/work/${PACKAGE_ARCH}-poky-${TARGET_OS}/${PN}-${PV}-${PR} As an example, assume a - source directory top-level + Source Directory top-level folder name poky and a default - build directory + Build Directory at poky/build. In this case, the working directory the build system uses to build the v86d package is the following: @@ -2681,8 +2680,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}-${PV}-${PR} - As an example, again assume a source directory top-level folder - named poky and a default build directory + As an example, again assume a Source Directory top-level folder + named poky and a default Build Directory at poky/build. In this case, the working directory the build system uses to build the acl recipe, which is being built for a diff --git a/documentation/poky-ref-manual/technical-details.xml b/documentation/poky-ref-manual/technical-details.xml index 2e30df1604..654d9252a9 100644 --- a/documentation/poky-ref-manual/technical-details.xml +++ b/documentation/poky-ref-manual/technical-details.xml @@ -129,7 +129,7 @@ between metadata files. An example is the Autotools class, which contains common settings for any application that Autotools uses. - The "Reference: Classes" chapter provides details + The "Classes" chapter provides details about common classes and how to use them. @@ -143,7 +143,7 @@ These files fall into several areas that define machine configuration options, distribution configuration options, compiler tuning options, general common configuration options and user configuration options (local.conf, which is found - in the build directory). + in the Build Directory). @@ -304,7 +304,7 @@ Information based on direct inputs is referred to as the "basehash" in the code. However, there is still the question of a task's indirect inputs - the - things that were already built and present in the build directory. + things that were already built and present in the Build Directory. The checksum (or signature) for a particular task needs to add the hashes of all the tasks on which the particular task depends. Choosing which dependencies to add is a policy decision. @@ -650,7 +650,7 @@ Yocto Project, you can follow these steps to use the x32 spABI: Add the experimental/meta-x32 layer to your local - build directory. + Build Directory. You can find the experimental/meta-x32 source repository at . Edit your conf/bblayers.conf file so that it includes @@ -698,6 +698,13 @@ which by default are disabled. + + For information that can help you maintain compliance with various open + source licensing during the lifecycle of the product, see the + "Maintaining Open Source License Compliance During Your Project's Lifecycle" section + in the Yocto Project Development Manual. + +
Tracking License Changes diff --git a/documentation/poky-ref-manual/usingpoky.xml b/documentation/poky-ref-manual/usingpoky.xml index 18bd8b7eb0..4ae6545479 100644 --- a/documentation/poky-ref-manual/usingpoky.xml +++ b/documentation/poky-ref-manual/usingpoky.xml @@ -30,20 +30,20 @@ The first thing you need to do is set up the OpenEmbedded build environment by sourcing the environment setup script as follows: - $ source oe-init-build-env [build_dir] + $ source &OE_INIT_FILE; [build_dir] The build_dir is optional and specifies the directory the OpenEmbedded build system uses for the build - - the build directory. - If you do not specify a build directory it defaults to build + the Build Directory. + If you do not specify a Build Directory it defaults to build in your current working directory. - A common practice is to use a different build directory for different targets. + A common practice is to use a different Build Directory for different targets. For example, ~/build/x86 for a qemux86 target, and ~/build/arm for a qemuarm target. - See oe-init-build-env + See &OE_INIT_FILE; for more information on this script. @@ -58,7 +58,7 @@ The target is the name of the recipe you want to build. Common targets are the images in meta/recipes-core/images, /meta/recipes-sato/images, etc. all found in the - source directory. + Source Directory. Or, the target can be the name of a recipe for a specific piece of software such as busybox. For more details about the images the OpenEmbedded build system supports, see the @@ -91,7 +91,7 @@ Once an image has been built, it often needs to be installed. The images and kernels built by the OpenEmbedded build system are placed in the - build directory in + Build Directory in tmp/deploy/images. For information on how to run pre-built images such as qemux86 and qemuarm, see the @@ -268,7 +268,7 @@ For guidance on how logging is handled in both Python and Bash recipes, see the logging.bbclass file in the meta/classes folder of the - source directory. + Source Directory.
-- cgit v1.2.3-54-g00ecf