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.
+
+