From 01a70aaea95d4d6d20d196191157f09b3b903d29 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Wed, 31 Jan 2018 13:03:11 -0800 Subject: concepts-manual: General edits Removed redundant links, changed some wordings. This was a general scrub of the prose. (From yocto-docs rev: 2c0ff0af7df3aa46fc05aaf28039a2ffb380424a) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../concepts-manual/concepts-manual-concepts.xml | 119 ++++++++++----------- 1 file changed, 58 insertions(+), 61 deletions(-) (limited to 'documentation') diff --git a/documentation/concepts-manual/concepts-manual-concepts.xml b/documentation/concepts-manual/concepts-manual-concepts.xml index 4ad4ebc74b..010eda6191 100644 --- a/documentation/concepts-manual/concepts-manual-concepts.xml +++ b/documentation/concepts-manual/concepts-manual-concepts.xml @@ -5,13 +5,6 @@ Yocto Project Concepts - - This chapter describes concepts for various areas of the Yocto Project. - Currently, topics include Yocto Project components, cross-development - generation, shared state (sstate) cache, runtime dependencies, - Pseudo and Fakeroot, x32 psABI, Wayland support, and Licenses. - -
Yocto Project Components @@ -67,8 +60,9 @@ BitBake - BitBake is the tool at the heart of the OpenEmbedded build - system and is responsible for parsing the + BitBake is the tool at the heart of the + OpenEmbedded build system + and is responsible for parsing the Metadata, generating a list of tasks from it, and then executing those tasks. @@ -93,8 +87,7 @@ The most common usage for BitBake is bitbake packagename, where packagename is the name of the - package you want to build (referred to as the "target" in this - manual). + package you want to build (referred to as the "target"). The target often equates to the first part of a recipe's filename (e.g. "foo" for a recipe named foo_1.3.0-r0.bb). @@ -180,8 +173,10 @@ in the build's configuration file (e.g. poky/build/conf/local.conf). - Any recipe that PROVIDES a virtual/* - item that is ultimately not selected through + Any recipe that + PROVIDES + a virtual/* item that is ultimately + not selected through PREFERRED_PROVIDER does not get built. Preventing these recipes from building is usually the desired behavior since this mechanism's purpose is to @@ -224,9 +219,7 @@ Class files (.bbclass) contain information - that is useful to share between - Metadata - files. + that is useful to share between Metadata files. An example is the autotools class, which contains common settings for any application that @@ -288,16 +281,18 @@ Most of the work occurs on the Build Host. - This is the machine used to build images and generally work within the - the Yocto Project environment. - When you run BitBake to create an image, the OpenEmbedded build system + This is the machine used to build images and generally work within + the the Yocto Project environment. + When you run + BitBake + to create an image, the OpenEmbedded build system uses the host gcc compiler to bootstrap a cross-compiler named gcc-cross. The gcc-cross compiler is what BitBake uses to compile source files when creating the target image. You can think of gcc-cross simply as an - automatically generated cross-compiler that is used internally within - BitBake only. + automatically generated cross-compiler that is used internally + within BitBake only. The extensible SDK does not use gcc-cross-canadian since this SDK @@ -370,11 +365,11 @@ You can use the OpenEmbedded build system to build an installer for the relocatable SDK used to develop applications. - When you run the installer, it installs the toolchain, which contains - the development tools (e.g., the - gcc-cross-canadian), + When you run the installer, it installs the toolchain, which + contains the development tools (e.g., + gcc-cross-canadian, binutils-cross-canadian, and other - nativesdk-* tools, + nativesdk-* tools), which are tools native to the SDK (i.e. native to SDK_ARCH), you need to cross-compile and test your software. @@ -476,8 +471,9 @@ By design, the OpenEmbedded build system builds everything from - scratch unless BitBake can determine that parts do not need to be - rebuilt. + scratch unless + BitBake + can determine that parts do not need to be rebuilt. Fundamentally, building from scratch is attractive as it means all parts are built fresh and there is no possibility of stale data causing problems. @@ -518,9 +514,10 @@ - For the first question, the build system detects changes in the - "inputs" to a given task by creating a checksum (or signature) of - the task's inputs. + For the first question, the + OpenEmbedded build system + detects changes in the "inputs" to a given task by creating a + checksum (or signature) of the task's inputs. If the checksum changes, the system assumes the inputs have changed and the task needs to be rerun. For the second question, the shared state (sstate) code tracks @@ -607,7 +604,8 @@ Also, the build process has the objective of making native or cross packages relocatable. - Both native and cross packages run on the build host. + Both native and cross packages run on the + build host. However, cross packages generate output for the target architecture. @@ -629,7 +627,7 @@ - So far we have solutions for shell scripts. + So far, solutions for shell scripts exist. What about Python tasks? The same approach applies even though these tasks are more difficult. @@ -643,7 +641,7 @@ Like the WORKDIR case, situations exist where dependencies should be ignored. - For these cases, you can instruct the build process to + For these situations, you can instruct the build process to ignore a dependency by using a line like the following: PACKAGE_ARCHS[vardepsexclude] = "MACHINE" @@ -656,7 +654,7 @@ - Equally, there are cases where we need to add dependencies + Equally, there are cases where you need to add dependencies BitBake is not able to find. You can accomplish this by using a line like the following: @@ -668,7 +666,7 @@ - Consider a case with in-line Python, for example, where + As an example, consider a case with in-line Python where BitBake is not able to figure out dependencies. When running in debug mode (i.e. using -DDD), BitBake produces output when it @@ -696,9 +694,9 @@ - At the code level, there are a variety of ways both the + At the code level, a variety of ways exist by which both the basehash and the dependent task hashes can be influenced. - Within the BitBake configuration file, we can give BitBake + Within the BitBake configuration file, you can give BitBake some extra information to help it construct the basehash. The following statement effectively results in a list of global variable dependency excludes - variables never @@ -799,8 +797,8 @@ - There are two types of output, one is just about creating a - directory in + Two types of output exist. + One type is just about creating a directory in WORKDIR. A good example is the output of either do_install @@ -1156,8 +1154,7 @@ current version of the package that provides the shared library must be used, as if "package (>= version)" - had been added to - RDEPENDS. + had been added to RDEPENDS. This forces an upgrade of the package containing the shared library when installing the package that depends on the library, if needed. @@ -1170,18 +1167,15 @@ pcdeps: - During the - do_package - task of each recipe, all pkg-config modules + During the do_package task of each + recipe, all pkg-config modules (*.pc files) installed by the recipe are located. For each module, the package that contains the module is registered as providing the module. The resulting module-to-package mapping is saved globally in - PKGDATA_DIR - by the - do_packagedata - task. + PKGDATA_DIR by the + do_packagedata task. Simultaneously, all pkg-config modules installed by the recipe are inspected to see what other pkg-config @@ -1238,8 +1232,7 @@ The do_package task depends on the - do_packagedata - task of each recipe in + do_packagedata task of each recipe in DEPENDS through use of a [deptask] @@ -1268,7 +1261,9 @@ One approach to allowing tasks to perform root-only operations - would be to require BitBake to run as root. + would be to require + BitBake + to run as root. However, this method is cumbersome and has security issues. The approach that is actually used is to run tasks that benefit from root privileges in a "fake" root environment. @@ -1288,8 +1283,9 @@ - In the OpenEmbedded build system, the program that implements - fakeroot is known as Pseudo. + In the + OpenEmbedded build system, + the program that implements fakeroot is known as Pseudo. Pseudo overrides system calls by using the environment variable LD_PRELOAD, which results in the illusion of running as root. @@ -1469,8 +1465,9 @@ Licenses - This section describes the mechanism by which the OpenEmbedded - build system tracks changes to licensing text. + This section describes the mechanism by which the + OpenEmbedded build system + tracks changes to licensing text. The section also describes how to enable commercially licensed recipes, which by default are disabled. @@ -1611,7 +1608,9 @@ If you specify an empty or invalid "md5" - parameter, BitBake returns an md5 mis-match + parameter, + BitBake + returns an md5 mis-match error and displays the correct "md5" parameter value during the build. The correct parameter is also captured in @@ -1704,9 +1703,8 @@ License flag matching allows you to control what recipes the OpenEmbedded build system includes in the build. Fundamentally, the build system attempts to match - LICENSE_FLAGS - strings found in recipes against - LICENSE_FLAGS_WHITELIST + LICENSE_FLAGS strings found in recipes + against LICENSE_FLAGS_WHITELIST strings found in the whitelist. A match causes the build system to include a recipe in the build, while failure to find a match causes the build @@ -1834,8 +1832,7 @@ Of course, you could also create a matching whitelist for those components using the more general "commercial" in the whitelist, but that would also enable all the - other packages with - LICENSE_FLAGS + other packages with LICENSE_FLAGS containing "commercial", which you may or may not want: LICENSE_FLAGS_WHITELIST = "commercial" -- cgit v1.2.3-54-g00ecf