From 707224b57a9d646bbeb619bfe1054e9e4c021b23 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Wed, 10 Jan 2018 12:35:02 -0800 Subject: ref-manual, overview-manual, yocto-project-qs: Moved YP Components Fixes [YOCTO #12370] Moved the "Yocto Project Components" section from the ref-manual to the overview-manual. This material falls into the "concepts" area and is being moved from the ref-manual. One link in the yocto-project-qs was affected and updated. Oh... another link in the ref-manual for a variable also fixed. (From yocto-docs rev: 75ced485bb223373591eb41d1b343d0c2b315345) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../overview-manual/overview-concepts.xml | 368 +++++++++++++++++---- documentation/ref-manual/ref-variables.xml | 5 +- documentation/ref-manual/technical-details.xml | 222 ------------- documentation/yocto-project-qs/qs.xml | 5 +- 4 files changed, 314 insertions(+), 286 deletions(-) diff --git a/documentation/overview-manual/overview-concepts.xml b/documentation/overview-manual/overview-concepts.xml index dea30bc907..aa8d35e3f9 100644 --- a/documentation/overview-manual/overview-concepts.xml +++ b/documentation/overview-manual/overview-concepts.xml @@ -6,72 +6,320 @@ Yocto Project Concepts - This chapter presents key 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. -
- x32 psABI +
+ Yocto Project Components - - x32 processor-specific Application Binary Interface - (x32 psABI) - is a native 32-bit processor-specific ABI for - Intel 64 (x86-64) - architectures. - An ABI defines the calling conventions between functions in a - processing environment. - The interface determines what registers are used and what the sizes are - for various C data types. - + + The + BitBake + task executor together with various types of configuration files + form the OpenEmbedded Core. + This section overviews these components by describing their use and + how they interact. + - - Some processing environments prefer using 32-bit applications even when - running on Intel 64-bit platforms. - Consider the i386 psABI, which is a very old 32-bit ABI for Intel - 64-bit platforms. - The i386 psABI does not provide efficient use and access of the - Intel 64-bit processor resources, leaving the system underutilized. - Now consider the x86_64 psABI. - This ABI is newer and uses 64-bits for data sizes and program pointers. - The extra bits increase the footprint size of the programs, libraries, - and also increases the memory and file system size requirements. - Executing under the x32 psABI enables user programs to utilize CPU - and system resources more efficiently while keeping the memory - footprint of the applications low. - Extra bits are used for registers but not for addressing mechanisms. - + + BitBake handles the parsing and execution of the data files. + The data itself is of various types: + + + Recipes: + Provides details about particular pieces of software. + + + Class Data: + Abstracts common build information (e.g. how to build a + Linux kernel). + + + Configuration Data: + Defines machine-specific settings, policy decisions, and + so forth. + Configuration data acts as the glue to bind everything + together. + + + - - The Yocto Project supports the final specifications of x32 psABI - as follows: - - - You can create packages and images in x32 psABI format on - x86_64 architecture targets. - - - You can successfully build recipes with the x32 toolchain. - - - You can create and boot - core-image-minimal and - core-image-sato images. - - - RPM Package Manager (RPM) support exists for x32 binaries. - - - Support for large images exists. - - - + + BitBake knows how to combine multiple data sources together and + refers to each data source as a layer. + For information on layers, see the + "Understanding and Creating Layers" + section of the Yocto Project Development Tasks Manual. + - - For steps on how to use x32 psABI, see the - "Using x32 psABI" - section in the Yocto Project Development Tasks Manual. - -
+ + Following are some brief details on these core components. + For additional information on how these components interact during + a build, see the + "Development Concepts" + section. + + +
+ BitBake + + + 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. + + + + This section briefly introduces BitBake. + If you want more information on BitBake, see the + BitBake User Manual. + + + + To see a list of the options BitBake supports, use either of + the following commands: + + $ bitbake -h + $ bitbake --help + + + + + 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). + 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). + So, to process the + matchbox-desktop_1.2.3.bb recipe file, you + might type the following: + + $ bitbake matchbox-desktop + + Several different versions of + matchbox-desktop might exist. + BitBake chooses the one selected by the distribution + configuration. + You can get more details about how BitBake chooses between + different target versions and providers in the + "Preferences" + section of the BitBake User Manual. + + + + BitBake also tries to execute any dependent tasks first. + So for example, before building + matchbox-desktop, BitBake would build a + cross compiler and glibc if they had not + already been built. + + + + A useful BitBake option to consider is the + -k or --continue + option. + This option instructs BitBake to try and continue processing + the job as long as possible even after encountering an error. + When an error occurs, the target that failed and those that + depend on it cannot be remade. + However, when you use this option other dependencies can + still be processed. + +
+ +
+ Metadata (Recipes) + + + Files that have the .bb suffix are + "recipes" files. + In general, a recipe contains information about a single piece + of software. + This information includes the location from which to download + the unaltered source, any source patches to be applied to that + source (if needed), which special configuration options to + apply, how to compile the source files, and how to package the + compiled output. + + + + The term "package" is sometimes used to refer to recipes. + However, since the word "package" is used for the packaged + output from the OpenEmbedded build system (i.e. + .ipk or .deb files), + this document avoids using the term "package" when referring + to recipes. + +
+ +
+ Metadata (Virtual Providers) + + + Prior to the build, if you know that several different recipes + provide the same functionality, you can use a virtual provider + (i.e. virtual/*) as a placeholder for the + actual provider. + The actual provider would be determined at build time. + In this case, you should add virtual/* + to + DEPENDS, + rather than listing the specified provider. + You would select the actual provider by setting the + PREFERRED_PROVIDER + variable (i.e. + PREFERRED_PROVIDER_virtual/*) + 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 + PREFERRED_PROVIDER does not get built. + Preventing these recipes from building is usually the + desired behavior since this mechanism's purpose is to + select between mutually exclusive alternative providers. + + + + + The following lists specific examples of virtual providers: + + + virtual/mesa: + Provides gbm.pc. + + + virtual/egl: + Provides egl.pc and possibly + wayland-egl.pc. + + + virtual/libgl: + Provides gl.pc (i.e. libGL). + + + virtual/libgles1: + Provides glesv1_cm.pc + (i.e. libGLESv1_CM). + + + virtual/libgles2: + Provides glesv2.pc + (i.e. libGLESv2). + + + +
+ +
+ Classes + + + Class files (.bbclass) contain information + that is useful to share between + Metadata + files. + An example is the + autotools + class, which contains common settings for any application that + Autotools uses. + The + "Classes" + chapter in the Yocto Project Reference Manual provides + details about classes and how to use them. + +
+ +
+ Configuration + + + The configuration files (.conf) define + various configuration variables that govern the OpenEmbedded + build process. + 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 in + local.conf, which is found in the + Build Directory. + +
+
+ +
+ x32 psABI + + + x32 processor-specific Application Binary Interface + (x32 psABI) + is a native 32-bit processor-specific ABI for + Intel 64 (x86-64) + architectures. + An ABI defines the calling conventions between functions in a + processing environment. + The interface determines what registers are used and what the sizes are + for various C data types. + + + + Some processing environments prefer using 32-bit applications even + when running on Intel 64-bit platforms. + Consider the i386 psABI, which is a very old 32-bit ABI for Intel + 64-bit platforms. + The i386 psABI does not provide efficient use and access of the + Intel 64-bit processor resources, leaving the system underutilized. + Now consider the x86_64 psABI. + This ABI is newer and uses 64-bits for data sizes and program + pointers. + The extra bits increase the footprint size of the programs, + libraries, and also increases the memory and file system size + requirements. + Executing under the x32 psABI enables user programs to utilize CPU + and system resources more efficiently while keeping the memory + footprint of the applications low. + Extra bits are used for registers but not for addressing mechanisms. + + + + The Yocto Project supports the final specifications of x32 psABI + as follows: + + + You can create packages and images in x32 psABI format on + x86_64 architecture targets. + + + You can successfully build recipes with the x32 toolchain. + + + You can create and boot + core-image-minimal and + core-image-sato images. + + + RPM Package Manager (RPM) support exists for x32 binaries. + + + Support for large images exists. + + + + + + For steps on how to use x32 psABI, see the + "Using x32 psABI" + section in the Yocto Project Development Tasks Manual. + +