From c555881ac8e62e1bc1ddd9e0337e0c70a560b3b6 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Thu, 12 Apr 2018 10:52:45 -0700 Subject: poky.ent: Added YOCTO_DOCS_OM_URL entity The variabe for the "getting-started" manual goes away and is replaced by this one for the new "overview-manual." (From yocto-docs rev: 45fc9beac6db4c40c3660fc9e54cc11e9c1f96c4) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/Makefile | 10 +- .../getting-started/figures/YP-flow-diagram.png | Bin 190715 -> 0 bytes .../figures/analysis-for-package-splitting.png | Bin 63291 -> 0 bytes .../figures/configuration-compile-autoreconf.png | Bin 46080 -> 0 bytes .../figures/cross-development-toolchains.png | Bin 82633 -> 0 bytes .../figures/getting-started-title.png | Bin 13472 -> 0 bytes .../getting-started/figures/git-workflow.png | Bin 26586 -> 0 bytes .../getting-started/figures/image-generation.png | Bin 112991 -> 0 bytes documentation/getting-started/figures/images.png | Bin 22926 -> 0 bytes .../getting-started/figures/index-downloads.png | Bin 36362 -> 0 bytes .../getting-started/figures/key-dev-elements.png | Bin 20424 -> 0 bytes .../getting-started/figures/layer-input.png | Bin 45856 -> 0 bytes .../getting-started/figures/package-feeds.png | Bin 30112 -> 0 bytes documentation/getting-started/figures/patching.png | Bin 42523 -> 0 bytes .../figures/poky-reference-distribution.png | Bin 23784 -> 0 bytes .../getting-started/figures/sdk-generation.png | Bin 115643 -> 0 bytes documentation/getting-started/figures/sdk.png | Bin 67478 -> 0 bytes .../getting-started/figures/source-fetching.png | Bin 38860 -> 0 bytes .../getting-started/figures/source-input.png | Bin 39872 -> 0 bytes .../getting-started/figures/source-repos.png | Bin 298757 -> 0 bytes .../getting-started/figures/user-configuration.png | Bin 74109 -> 0 bytes .../figures/yocto-environment-ref.png | Bin 83206 -> 0 bytes .../getting-started/figures/yp-download.png | Bin 82939 -> 0 bytes .../getting-started/getting-started-concepts.xml | 3612 -------------------- .../getting-started-customization.xsl | 27 - .../getting-started-development-environment.xml | 972 ------ .../getting-started-eclipse-customization.xsl | 35 - .../getting-started/getting-started-intro.xml | 111 - .../getting-started/getting-started-style.css | 988 ------ .../getting-started/getting-started-yp-intro.xml | 1335 -------- documentation/getting-started/getting-started.xml | 108 - .../mega-manual/figures/getting-started-title.png | Bin 13472 -> 0 bytes .../mega-manual/figures/overview-manual-title.png | Bin 0 -> 21648 bytes documentation/mega-manual/mega-manual.xml | 12 +- .../overview-manual/figures/YP-flow-diagram.png | Bin 0 -> 190715 bytes .../figures/analysis-for-package-splitting.png | Bin 0 -> 63291 bytes .../figures/configuration-compile-autoreconf.png | Bin 0 -> 46080 bytes .../figures/cross-development-toolchains.png | Bin 0 -> 82633 bytes .../overview-manual/figures/git-workflow.png | Bin 0 -> 26586 bytes .../overview-manual/figures/image-generation.png | Bin 0 -> 112991 bytes documentation/overview-manual/figures/images.png | Bin 0 -> 22926 bytes .../overview-manual/figures/index-downloads.png | Bin 0 -> 36362 bytes .../overview-manual/figures/key-dev-elements.png | Bin 0 -> 20424 bytes .../overview-manual/figures/layer-input.png | Bin 0 -> 45856 bytes .../figures/overview-manual-title.png | Bin 0 -> 21648 bytes .../overview-manual/figures/package-feeds.png | Bin 0 -> 30112 bytes documentation/overview-manual/figures/patching.png | Bin 0 -> 42523 bytes .../figures/poky-reference-distribution.png | Bin 0 -> 23784 bytes .../overview-manual/figures/sdk-generation.png | Bin 0 -> 115643 bytes documentation/overview-manual/figures/sdk.png | Bin 0 -> 67478 bytes .../overview-manual/figures/source-fetching.png | Bin 0 -> 38860 bytes .../overview-manual/figures/source-input.png | Bin 0 -> 39872 bytes .../overview-manual/figures/source-repos.png | Bin 0 -> 298757 bytes .../overview-manual/figures/user-configuration.png | Bin 0 -> 74109 bytes .../figures/yocto-environment-ref.png | Bin 0 -> 83206 bytes .../overview-manual/figures/yp-download.png | Bin 0 -> 82939 bytes .../overview-manual/overview-manual-concepts.xml | 3612 ++++++++++++++++++++ .../overview-manual-customization.xsl | 27 + .../overview-manual-development-environment.xml | 972 ++++++ .../overview-manual-eclipse-customization.xsl | 35 + .../overview-manual/overview-manual-intro.xml | 111 + .../overview-manual/overview-manual-style.css | 988 ++++++ .../overview-manual/overview-manual-yp-intro.xml | 1335 ++++++++ documentation/overview-manual/overview-manual.xml | 108 + documentation/poky.ent | 2 +- documentation/tools/mega-manual.sed | 4 +- 66 files changed, 7202 insertions(+), 7202 deletions(-) delete mode 100644 documentation/getting-started/figures/YP-flow-diagram.png delete mode 100644 documentation/getting-started/figures/analysis-for-package-splitting.png delete mode 100644 documentation/getting-started/figures/configuration-compile-autoreconf.png delete mode 100644 documentation/getting-started/figures/cross-development-toolchains.png delete mode 100644 documentation/getting-started/figures/getting-started-title.png delete mode 100644 documentation/getting-started/figures/git-workflow.png delete mode 100644 documentation/getting-started/figures/image-generation.png delete mode 100644 documentation/getting-started/figures/images.png delete mode 100644 documentation/getting-started/figures/index-downloads.png delete mode 100644 documentation/getting-started/figures/key-dev-elements.png delete mode 100644 documentation/getting-started/figures/layer-input.png delete mode 100644 documentation/getting-started/figures/package-feeds.png delete mode 100644 documentation/getting-started/figures/patching.png delete mode 100644 documentation/getting-started/figures/poky-reference-distribution.png delete mode 100755 documentation/getting-started/figures/sdk-generation.png delete mode 100644 documentation/getting-started/figures/sdk.png delete mode 100644 documentation/getting-started/figures/source-fetching.png delete mode 100644 documentation/getting-started/figures/source-input.png delete mode 100644 documentation/getting-started/figures/source-repos.png delete mode 100644 documentation/getting-started/figures/user-configuration.png delete mode 100644 documentation/getting-started/figures/yocto-environment-ref.png delete mode 100644 documentation/getting-started/figures/yp-download.png delete mode 100644 documentation/getting-started/getting-started-concepts.xml delete mode 100644 documentation/getting-started/getting-started-customization.xsl delete mode 100644 documentation/getting-started/getting-started-development-environment.xml delete mode 100644 documentation/getting-started/getting-started-eclipse-customization.xsl delete mode 100644 documentation/getting-started/getting-started-intro.xml delete mode 100644 documentation/getting-started/getting-started-style.css delete mode 100644 documentation/getting-started/getting-started-yp-intro.xml delete mode 100644 documentation/getting-started/getting-started.xml delete mode 100644 documentation/mega-manual/figures/getting-started-title.png create mode 100644 documentation/mega-manual/figures/overview-manual-title.png create mode 100644 documentation/overview-manual/figures/YP-flow-diagram.png create mode 100644 documentation/overview-manual/figures/analysis-for-package-splitting.png create mode 100644 documentation/overview-manual/figures/configuration-compile-autoreconf.png create mode 100644 documentation/overview-manual/figures/cross-development-toolchains.png create mode 100644 documentation/overview-manual/figures/git-workflow.png create mode 100644 documentation/overview-manual/figures/image-generation.png create mode 100644 documentation/overview-manual/figures/images.png create mode 100644 documentation/overview-manual/figures/index-downloads.png create mode 100644 documentation/overview-manual/figures/key-dev-elements.png create mode 100644 documentation/overview-manual/figures/layer-input.png create mode 100644 documentation/overview-manual/figures/overview-manual-title.png create mode 100644 documentation/overview-manual/figures/package-feeds.png create mode 100644 documentation/overview-manual/figures/patching.png create mode 100644 documentation/overview-manual/figures/poky-reference-distribution.png create mode 100755 documentation/overview-manual/figures/sdk-generation.png create mode 100644 documentation/overview-manual/figures/sdk.png create mode 100644 documentation/overview-manual/figures/source-fetching.png create mode 100644 documentation/overview-manual/figures/source-input.png create mode 100644 documentation/overview-manual/figures/source-repos.png create mode 100644 documentation/overview-manual/figures/user-configuration.png create mode 100644 documentation/overview-manual/figures/yocto-environment-ref.png create mode 100644 documentation/overview-manual/figures/yp-download.png create mode 100644 documentation/overview-manual/overview-manual-concepts.xml create mode 100644 documentation/overview-manual/overview-manual-customization.xsl create mode 100644 documentation/overview-manual/overview-manual-development-environment.xml create mode 100644 documentation/overview-manual/overview-manual-eclipse-customization.xsl create mode 100644 documentation/overview-manual/overview-manual-intro.xml create mode 100644 documentation/overview-manual/overview-manual-style.css create mode 100644 documentation/overview-manual/overview-manual-yp-intro.xml create mode 100644 documentation/overview-manual/overview-manual.xml (limited to 'documentation') diff --git a/documentation/Makefile b/documentation/Makefile index c95725ef24..4423807580 100644 --- a/documentation/Makefile +++ b/documentation/Makefile @@ -99,10 +99,10 @@ STYLESHEET = $(DOC)/*.css endif -ifeq ($(DOC),getting-started) +ifeq ($(DOC),overview-manual) XSLTOPTS = --xinclude ALLPREQ = html eclipse tarball -TARFILES = getting-started-style.css getting-started.html figures/getting-started-title.png \ +TARFILES = overview-manual-style.css overview-manual.html figures/overview-manual-title.png \ figures/git-workflow.png figures/source-repos.png figures/index-downloads.png \ figures/yp-download.png figures/YP-flow-diagram.png figures/key-dev-elements.png \ figures/poky-reference-distribution.png \ @@ -269,7 +269,7 @@ TARFILES = mega-manual.html mega-style.css \ figures/sdk-devtool-add-flow.png figures/sdk-installed-extensible-sdk-directory.png \ figures/sdk-devtool-modify-flow.png figures/sdk-eclipse-dev-flow.png \ figures/sdk-devtool-upgrade-flow.png figures/bitbake-build-flow.png figures/bypqs-title.png \ - figures/getting-started-title.png + figures/overview-manual-title.png endif MANUALS = $(DOC)/$(DOC).html @@ -418,11 +418,11 @@ eclipse: eclipse-generate eclipse-resolve-links .PHONY : eclipse-generate eclipse-resolve-links eclipse-generate: -ifeq ($(filter $(DOC), getting-started sdk-manual bsp-guide dev-manual kernel-dev profile-manual ref-manual brief-yoctoprojectqs),) +ifeq ($(filter $(DOC), overview-manual sdk-manual bsp-guide dev-manual kernel-dev profile-manual ref-manual brief-yoctoprojectqs),) @echo " " @echo "ERROR: You can only create eclipse documentation" @echo " of the following documentation parts:" - @echo " - getting-started" + @echo " - overview-manual" @echo " - sdk-manual" @echo " - bsp-guide" @echo " - dev-manual" diff --git a/documentation/getting-started/figures/YP-flow-diagram.png b/documentation/getting-started/figures/YP-flow-diagram.png deleted file mode 100644 index 8264410504..0000000000 Binary files a/documentation/getting-started/figures/YP-flow-diagram.png and /dev/null differ diff --git a/documentation/getting-started/figures/analysis-for-package-splitting.png b/documentation/getting-started/figures/analysis-for-package-splitting.png deleted file mode 100644 index 04f2794ea9..0000000000 Binary files a/documentation/getting-started/figures/analysis-for-package-splitting.png and /dev/null differ diff --git a/documentation/getting-started/figures/configuration-compile-autoreconf.png b/documentation/getting-started/figures/configuration-compile-autoreconf.png deleted file mode 100644 index a07464f04c..0000000000 Binary files a/documentation/getting-started/figures/configuration-compile-autoreconf.png and /dev/null differ diff --git a/documentation/getting-started/figures/cross-development-toolchains.png b/documentation/getting-started/figures/cross-development-toolchains.png deleted file mode 100644 index cbe8371c05..0000000000 Binary files a/documentation/getting-started/figures/cross-development-toolchains.png and /dev/null differ diff --git a/documentation/getting-started/figures/getting-started-title.png b/documentation/getting-started/figures/getting-started-title.png deleted file mode 100644 index f38b078ab7..0000000000 Binary files a/documentation/getting-started/figures/getting-started-title.png and /dev/null differ diff --git a/documentation/getting-started/figures/git-workflow.png b/documentation/getting-started/figures/git-workflow.png deleted file mode 100644 index e401330a12..0000000000 Binary files a/documentation/getting-started/figures/git-workflow.png and /dev/null differ diff --git a/documentation/getting-started/figures/image-generation.png b/documentation/getting-started/figures/image-generation.png deleted file mode 100644 index 71a48dc6f4..0000000000 Binary files a/documentation/getting-started/figures/image-generation.png and /dev/null differ diff --git a/documentation/getting-started/figures/images.png b/documentation/getting-started/figures/images.png deleted file mode 100644 index d99eac1fbf..0000000000 Binary files a/documentation/getting-started/figures/images.png and /dev/null differ diff --git a/documentation/getting-started/figures/index-downloads.png b/documentation/getting-started/figures/index-downloads.png deleted file mode 100644 index 96303b8781..0000000000 Binary files a/documentation/getting-started/figures/index-downloads.png and /dev/null differ diff --git a/documentation/getting-started/figures/key-dev-elements.png b/documentation/getting-started/figures/key-dev-elements.png deleted file mode 100644 index 76c44050fd..0000000000 Binary files a/documentation/getting-started/figures/key-dev-elements.png and /dev/null differ diff --git a/documentation/getting-started/figures/layer-input.png b/documentation/getting-started/figures/layer-input.png deleted file mode 100644 index 0a4f2e74f3..0000000000 Binary files a/documentation/getting-started/figures/layer-input.png and /dev/null differ diff --git a/documentation/getting-started/figures/package-feeds.png b/documentation/getting-started/figures/package-feeds.png deleted file mode 100644 index 37c9c32506..0000000000 Binary files a/documentation/getting-started/figures/package-feeds.png and /dev/null differ diff --git a/documentation/getting-started/figures/patching.png b/documentation/getting-started/figures/patching.png deleted file mode 100644 index 8ecd018502..0000000000 Binary files a/documentation/getting-started/figures/patching.png and /dev/null differ diff --git a/documentation/getting-started/figures/poky-reference-distribution.png b/documentation/getting-started/figures/poky-reference-distribution.png deleted file mode 100644 index 1be89ae68e..0000000000 Binary files a/documentation/getting-started/figures/poky-reference-distribution.png and /dev/null differ diff --git a/documentation/getting-started/figures/sdk-generation.png b/documentation/getting-started/figures/sdk-generation.png deleted file mode 100755 index adbe1f4acf..0000000000 Binary files a/documentation/getting-started/figures/sdk-generation.png and /dev/null differ diff --git a/documentation/getting-started/figures/sdk.png b/documentation/getting-started/figures/sdk.png deleted file mode 100644 index 5c36b7548b..0000000000 Binary files a/documentation/getting-started/figures/sdk.png and /dev/null differ diff --git a/documentation/getting-started/figures/source-fetching.png b/documentation/getting-started/figures/source-fetching.png deleted file mode 100644 index 26aefb50c2..0000000000 Binary files a/documentation/getting-started/figures/source-fetching.png and /dev/null differ diff --git a/documentation/getting-started/figures/source-input.png b/documentation/getting-started/figures/source-input.png deleted file mode 100644 index f7515058ef..0000000000 Binary files a/documentation/getting-started/figures/source-input.png and /dev/null differ diff --git a/documentation/getting-started/figures/source-repos.png b/documentation/getting-started/figures/source-repos.png deleted file mode 100644 index 603300b6d2..0000000000 Binary files a/documentation/getting-started/figures/source-repos.png and /dev/null differ diff --git a/documentation/getting-started/figures/user-configuration.png b/documentation/getting-started/figures/user-configuration.png deleted file mode 100644 index c298401fc3..0000000000 Binary files a/documentation/getting-started/figures/user-configuration.png and /dev/null differ diff --git a/documentation/getting-started/figures/yocto-environment-ref.png b/documentation/getting-started/figures/yocto-environment-ref.png deleted file mode 100644 index 650c6c8030..0000000000 Binary files a/documentation/getting-started/figures/yocto-environment-ref.png and /dev/null differ diff --git a/documentation/getting-started/figures/yp-download.png b/documentation/getting-started/figures/yp-download.png deleted file mode 100644 index bfd12b678a..0000000000 Binary files a/documentation/getting-started/figures/yp-download.png and /dev/null differ diff --git a/documentation/getting-started/getting-started-concepts.xml b/documentation/getting-started/getting-started-concepts.xml deleted file mode 100644 index b7b31b33d9..0000000000 --- a/documentation/getting-started/getting-started-concepts.xml +++ /dev/null @@ -1,3612 +0,0 @@ - %poky; ] > - - -Yocto Project Concepts - -
- Yocto Project Components - - - 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. - - - - 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. - - - - - - 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. - - - - 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"). - 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. - -
- -
- 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. - -
-
- -
- Layers - - - Layers are repositories that contain related sets of instructions - that tell the OpenEmbedded build system what to do. - You use different layers to logically separate information in your - build. - You can collaborate, share, and reuse layers. - The Layer Model simultaneously supports collaboration and - customization. - - - - For more introductory information on the Yocto Project's layer - model, see the - "The Yocto Project Layer Model" - section in the Yocto Project Overview and Concepts Manual. - For procedures on how to create layers, see the - "Understanding and Creating Layers" - section in the Yocto Project Development Tasks Manual. - -
- -
- Development Concepts - - - This section takes a more detailed look inside the build - process used by the OpenEmbedded build system. - The following diagram represents the build at a high level. - The remainder of this section expands on the fundamental input, - output, process, and - Metadata - blocks that make up the build process. - - - - - - - - In general, the build process consists of several functional areas: - - - User Configuration: - Metadata you can use to control the build process. - - - Metadata Layers: - Various layers that provide software, machine, and - distro Metadata. - - - Source Files: - Upstream releases, local projects, and SCMs. - - - Build System: - Processes under the control of - BitBake. - This block expands on how BitBake fetches source, applies - patches, completes compilation, analyzes output for package - generation, creates and tests packages, generates images, - and generates cross-development tools. - - - Package Feeds: - Directories containing output packages (RPM, DEB or IPK), - which are subsequently used in the construction of an - image or SDK, produced by the build system. - These feeds can also be copied and shared using a web - server or other means to facilitate extending or updating - existing images on devices at runtime if runtime package - management is enabled. - - - Images: - Images produced by the development process. - - - Application Development SDK: - Cross-development tools that are produced along with - an image or separately with BitBake. - - - - -
- User Configuration - - - User configuration helps define the build. - Through user configuration, you can tell BitBake the - target architecture for which you are building the image, - where to store downloaded source, and other build properties. - - - - The following figure shows an expanded representation of the - "User Configuration" box of the - general Build Process figure: - - - - - - - - BitBake needs some basic configuration files in order to - complete a build. - These files are *.conf files. - The minimally necessary ones reside as example files in the - Source Directory. - For simplicity, this section refers to the Source Directory as - the "Poky Directory." - - - - When you clone the poky Git repository - or you download and unpack a Yocto Project release, you - can set up the Source Directory to be named anything you want. - For this discussion, the cloned repository uses the default - name poky. - - The - Poky - repository is primarily an aggregation of existing - repositories. - It is not a canonical upstream source. - - - - - The meta-poky layer inside Poky contains - a conf directory that has example - configuration files. - These example files are used as a basis for creating actual - configuration files when you source the build environment - script - (i.e. - &OE_INIT_FILE;). - - - - Sourcing the build environment script creates a - Build Directory - if one does not already exist. - BitBake uses the Build Directory for all its work during - builds. - The Build Directory has a conf directory - that contains default versions of your - local.conf and - bblayers.conf configuration files. - These default configuration files are created only if versions - do not already exist in the Build Directory at the time you - source the build environment setup script. - - - - Because the Poky repository is fundamentally an aggregation of - existing repositories, some users might be familiar with - running the &OE_INIT_FILE; script - in the context of separate - OpenEmbedded-Core - and BitBake repositories rather than a single Poky repository. - This discussion assumes the script is executed from - within a cloned or unpacked version of Poky. - - - - Depending on where the script is sourced, different - sub-scripts are called to set up the Build Directory - (Yocto or OpenEmbedded). - Specifically, the script - scripts/oe-setup-builddir inside the - poky directory sets up the Build Directory and seeds the - directory (if necessary) with configuration files appropriate - for the Yocto Project development environment. - - The scripts/oe-setup-builddir script - uses the $TEMPLATECONF variable to - determine which sample configuration files to locate. - - - - - The local.conf file provides many - basic variables that define a build environment. - Here is a list of a few. - To see the default configurations in a - local.conf file created by the build - environment script, see the - local.conf.sample in the - meta-poky layer: - - - Parallelism Options: - Controlled by the - BB_NUMBER_THREADS, - PARALLEL_MAKE, - and - BB_NUMBER_PARSE_THREADS - variables. - - - Target Machine Selection: - Controlled by the - MACHINE - variable. - - - Download Directory: - Controlled by the - DL_DIR - variable. - - - Shared State Directory: - Controlled by the - SSTATE_DIR - variable. - - - Build Output: - Controlled by the - TMPDIR - variable. - - - - Configurations set in the - conf/local.conf file can also be set - in the conf/site.conf and - conf/auto.conf configuration files. - - - - - The bblayers.conf file tells BitBake what - layers you want considered during the build. - By default, the layers listed in this file include layers - minimally needed by the build system. - However, you must manually add any custom layers you have - created. - You can find more information on working with the - bblayers.conf file in the - "Enabling Your Layer" - section in the Yocto Project Development Tasks Manual. - - - - The files site.conf and - auto.conf are not created by the - environment initialization script. - If you want the site.conf file, you - need to create that yourself. - The auto.conf file is typically created by - an autobuilder: - - - site.conf: - You can use the conf/site.conf - configuration file to configure multiple - build directories. - For example, suppose you had several build environments - and they shared some common features. - You can set these default build properties here. - A good example is perhaps the packaging format to use - through the - PACKAGE_CLASSES - variable. - - One useful scenario for using the - conf/site.conf file is to extend - your - BBPATH - variable to include the path to a - conf/site.conf. - Then, when BitBake looks for Metadata using - BBPATH, it finds the - conf/site.conf file and applies - your common configurations found in the file. - To override configurations in a particular build - directory, alter the similar configurations within - that build directory's - conf/local.conf file. - - - auto.conf: - The file is usually created and written to by - an autobuilder. - The settings put into the file are typically the - same as you would find in the - conf/local.conf or the - conf/site.conf files. - - - - - - You can edit all configuration files to further define - any particular build environment. - This process is represented by the "User Configuration Edits" - box in the figure. - - - - When you launch your build with the - bitbake target - command, BitBake sorts out the configurations to ultimately - define your build environment. - It is important to understand that the - OpenEmbedded build system - reads the configuration files in a specific order: - site.conf, auto.conf, - and local.conf. - And, the build system applies the normal assignment statement - rules. - Because the files are parsed in a specific order, variable - assignments for the same variable could be affected. - For example, if the auto.conf file and - the local.conf set - variable1 to different values, - because the build system parses local.conf - after auto.conf, - variable1 is assigned the value from - the local.conf file. - -
- -
- Metadata, Machine Configuration, and Policy Configuration - - - The previous section described the user configurations that - define BitBake's global behavior. - This section takes a closer look at the layers the build system - uses to further control the build. - These layers provide Metadata for the software, machine, and - policy. - - - - In general, three types of layer input exist: - - - Policy Configuration: - Distribution Layers provide top-level or general - policies for the image or SDK being built. - For example, this layer would dictate whether BitBake - produces RPM or IPK packages. - - - Machine Configuration: - Board Support Package (BSP) layers provide machine - configurations. - This type of information is specific to a particular - target architecture. - - - Metadata: - Software layers contain user-supplied recipe files, - patches, and append files. - - - - - - The following figure shows an expanded representation of the - Metadata, Machine Configuration, and Policy Configuration input - (layers) boxes of the - general Build Process figure: - - - - - - - - In general, all layers have a similar structure. - They all contain a licensing file - (e.g. COPYING) if the layer is to be - distributed, a README file as good - practice and especially if the layer is to be distributed, a - configuration directory, and recipe directories. - - - - The Yocto Project has many layers that can be used. - You can see a web-interface listing of them on the - Source Repositories - page. - The layers appear at the bottom categorized under - "Yocto Metadata Layers." - These layers are fundamentally a subset of the - OpenEmbedded Metadata Index, - which lists all layers provided by the OpenEmbedded community. - - Layers exist in the Yocto Project Source Repositories that - cannot be found in the OpenEmbedded Metadata Index. - These layers are either deprecated or experimental - in nature. - - - - - BitBake uses the conf/bblayers.conf file, - which is part of the user configuration, to find what layers it - should be using as part of the build. - - - - For more information on layers, see the - "Understanding and Creating Layers" - section in the Yocto Project Development Tasks Manual. - - -
- Distro Layer - - - The distribution layer provides policy configurations for - your distribution. - Best practices dictate that you isolate these types of - configurations into their own layer. - Settings you provide in - conf/distro/distro.conf override - similar settings that BitBake finds in your - conf/local.conf file in the Build - Directory. - - - - The following list provides some explanation and references - for what you typically find in the distribution layer: - - - classes: - Class files (.bbclass) hold - common functionality that can be shared among - recipes in the distribution. - When your recipes inherit a class, they take on the - settings and functions for that class. - You can read more about class files in the - "Classes" - chapter of the Yocto Reference Manual. - - - conf: - This area holds configuration files for the - layer (conf/layer.conf), - the distribution - (conf/distro/distro.conf), - and any distribution-wide include files. - - - recipes-*: - Recipes and append files that affect common - functionality across the distribution. - This area could include recipes and append files - to add distribution-specific configuration, - initialization scripts, custom image recipes, - and so forth. - - - -
- -
- BSP Layer - - - The BSP Layer provides machine configurations. - Everything in this layer is specific to the machine for - which you are building the image or the SDK. - A common structure or form is defined for BSP layers. - You can learn more about this structure in the - Yocto Project Board Support Package (BSP) Developer's Guide. - - In order for a BSP layer to be considered compliant - with the Yocto Project, it must meet some structural - requirements. - - - - - The BSP Layer's configuration directory contains - configuration files for the machine - (conf/machine/machine.conf) - and, of course, the layer - (conf/layer.conf). - - - - The remainder of the layer is dedicated to specific recipes - by function: recipes-bsp, - recipes-core, - recipes-graphics, and - recipes-kernel. - Metadata can exist for multiple formfactors, graphics - support systems, and so forth. - - While the figure shows several - recipes-* directories, not all - these directories appear in all BSP layers. - - -
- -
- Software Layer - - - The software layer provides the Metadata for additional - software packages used during the build. - This layer does not include Metadata that is specific to - the distribution or the machine, which are found in their - respective layers. - - - - This layer contains any new recipes that your project - needs in the form of recipe files. - -
-
- -
- Sources - - - In order for the OpenEmbedded build system to create an - image or any target, it must be able to access source files. - The - general Build Process figure - represents source files using the "Upstream Project Releases", - "Local Projects", and "SCMs (optional)" boxes. - The figure represents mirrors, which also play a role in - locating source files, with the "Source Mirror(s)" box. - - - - The method by which source files are ultimately organized is - a function of the project. - For example, for released software, projects tend to use - tarballs or other archived files that can capture the - state of a release guaranteeing that it is statically - represented. - On the other hand, for a project that is more dynamic or - experimental in nature, a project might keep source files in a - repository controlled by a Source Control Manager (SCM) such as - Git. - Pulling source from a repository allows you to control - the point in the repository (the revision) from which you - want to build software. - Finally, a combination of the two might exist, which would - give the consumer a choice when deciding where to get - source files. - - - - BitBake uses the - SRC_URI - variable to point to source files regardless of their location. - Each recipe must have a SRC_URI variable - that points to the source. - - - - Another area that plays a significant role in where source - files come from is pointed to by the - DL_DIR - variable. - This area is a cache that can hold previously downloaded - source. - You can also instruct the OpenEmbedded build system to create - tarballs from Git repositories, which is not the default - behavior, and store them in the DL_DIR - by using the - BB_GENERATE_MIRROR_TARBALLS - variable. - - - - Judicious use of a DL_DIR directory can - save the build system a trip across the Internet when looking - for files. - A good method for using a download directory is to have - DL_DIR point to an area outside of your - Build Directory. - Doing so allows you to safely delete the Build Directory - if needed without fear of removing any downloaded source file. - - - - The remainder of this section provides a deeper look into the - source files and the mirrors. - Here is a more detailed look at the source file area of the - general Build Process figure: - - - -
- Upstream Project Releases - - - Upstream project releases exist anywhere in the form of an - archived file (e.g. tarball or zip file). - These files correspond to individual recipes. - For example, the figure uses specific releases each for - BusyBox, Qt, and Dbus. - An archive file can be for any released product that can be - built using a recipe. - -
- -
- Local Projects - - - Local projects are custom bits of software the user - provides. - These bits reside somewhere local to a project - perhaps - a directory into which the user checks in items (e.g. - a local directory containing a development source tree - used by the group). - - - - The canonical method through which to include a local - project is to use the - externalsrc - class to include that local project. - You use either the local.conf or a - recipe's append file to override or set the - recipe to point to the local directory on your disk to pull - in the whole source tree. - - - - For information on how to use the - externalsrc class, see the - "externalsrc.bbclass" - section. - -
- -
- Source Control Managers (Optional) - - - Another place the build system can get source files from is - through an SCM such as Git or Subversion. - In this case, a repository is cloned or checked out. - The - do_fetch - task inside BitBake uses - the SRC_URI - variable and the argument's prefix to determine the correct - fetcher module. - - For information on how to have the OpenEmbedded build - system generate tarballs for Git repositories and place - them in the - DL_DIR - directory, see the - BB_GENERATE_MIRROR_TARBALLS - variable. - - - - - When fetching a repository, BitBake uses the - SRCREV - variable to determine the specific revision from which to - build. - -
- -
- Source Mirror(s) - - - Two kinds of mirrors exist: pre-mirrors and regular - mirrors. - The - PREMIRRORS - and - MIRRORS - variables point to these, respectively. - BitBake checks pre-mirrors before looking upstream for any - source files. - Pre-mirrors are appropriate when you have a shared - directory that is not a directory defined by the - DL_DIR - variable. - A Pre-mirror typically points to a shared directory that is - local to your organization. - - - - Regular mirrors can be any site across the Internet - that is used as an alternative location for source - code should the primary site not be functioning for - some reason or another. - -
-
- -
- Package Feeds - - - When the OpenEmbedded build system generates an image or an - SDK, it gets the packages from a package feed area located - in the - Build Directory. - The - general Build Process figure - shows this package feeds area in the upper-right corner. - - - - This section looks a little closer into the package feeds - area used by the build system. - Here is a more detailed look at the area: - - - - - Package feeds are an intermediary step in the build process. - The OpenEmbedded build system provides classes to generate - different package types, and you specify which classes to - enable through the - PACKAGE_CLASSES - variable. - Before placing the packages into package feeds, - the build process validates them with generated output quality - assurance checks through the - insane - class. - - - - The package feed area resides in the Build Directory. - The directory the build system uses to temporarily store - packages is determined by a combination of variables and the - particular package manager in use. - See the "Package Feeds" box in the illustration and note the - information to the right of that area. - In particular, the following defines where package files are - kept: - - - DEPLOY_DIR: - Defined as tmp/deploy in the Build - Directory. - - - DEPLOY_DIR_*: - Depending on the package manager used, the package type - sub-folder. - Given RPM, IPK, or DEB packaging and tarball creation, - the - DEPLOY_DIR_RPM, - DEPLOY_DIR_IPK, - DEPLOY_DIR_DEB, - or - DEPLOY_DIR_TAR, - variables are used, respectively. - - - PACKAGE_ARCH: - Defines architecture-specific sub-folders. - For example, packages could exist for the i586 or - qemux86 architectures. - - - - - - BitBake uses the - do_package_write_* - tasks to generate packages and place them into the package - holding area (e.g. do_package_write_ipk - for IPK packages). - See the - "do_package_write_deb", - "do_package_write_ipk", - "do_package_write_rpm", - and - "do_package_write_tar" - sections in the Yocto Project Reference Manual - for additional information. - As an example, consider a scenario where an IPK packaging - manager is being used and package architecture support for - both i586 and qemux86 exist. - Packages for the i586 architecture are placed in - build/tmp/deploy/ipk/i586, while packages - for the qemux86 architecture are placed in - build/tmp/deploy/ipk/qemux86. - -
- -
- BitBake - - - The OpenEmbedded build system uses - BitBake - to produce images. - You can see from the - general Build Process figure, - the BitBake area consists of several functional areas. - This section takes a closer look at each of those areas. - - - - Separate documentation exists for the BitBake tool. - See the - BitBake User Manual - for reference material on BitBake. - - -
- Source Fetching - - - The first stages of building a recipe are to fetch and - unpack the source code: - - - - - The - do_fetch - and - do_unpack - tasks fetch the source files and unpack them into the work - directory. - - For every local file (e.g. file://) - that is part of a recipe's - SRC_URI - statement, the OpenEmbedded build system takes a - checksum of the file for the recipe and inserts the - checksum into the signature for the - do_fetch. - If any local file has been modified, the - do_fetch task and all tasks that - depend on it are re-executed. - - By default, everything is accomplished in the - Build Directory, - which has a defined structure. - For additional general information on the Build Directory, - see the - "build/" - section in the Yocto Project Reference Manual. - - - - Unpacked source files are pointed to by the - S - variable. - Each recipe has an area in the Build Directory where the - unpacked source code resides. - The name of that directory for any given recipe is defined - from several different variables. - You can see the variables that define these directories - by looking at the figure: - - - TMPDIR: - The base directory where the OpenEmbedded build - system performs all its work during the build. - - - PACKAGE_ARCH: - The architecture of the built package or packages. - - - TARGET_OS: - The operating system of the target device. - - - PN: - The name of the built package. - - - PV: - The version of the recipe used to build the - package. - - - PR: - The revision of the recipe used to build the - package. - - - WORKDIR: - The location within TMPDIR - where a specific package is built. - - - S: - Contains the unpacked source files for a given - recipe. - - - -
- -
- Patching - - - Once source code is fetched and unpacked, BitBake locates - patch files and applies them to the source files: - - - - - The - do_patch - task processes recipes by using the - SRC_URI - variable to locate applicable patch files, which by default - are *.patch or - *.diff files, or any file if - "apply=yes" is specified for the file in - SRC_URI. - - - - BitBake finds and applies multiple patches for a single - recipe in the order in which it finds the patches. - Patches are applied to the recipe's source files located - in the - S - directory. - - - - For more information on how the source directories are - created, see the - "Source Fetching" - section. - -
- -
- Configuration and Compilation - - - After source code is patched, BitBake executes tasks that - configure and compile the source code: - - - - - This step in the build process consists of three tasks: - - - do_prepare_recipe_sysroot: - This task sets up the two sysroots in - ${WORKDIR} - (i.e. recipe-sysroot and - recipe-sysroot-native) so that - the sysroots contain the contents of the - do_populate_sysroot - tasks of the recipes on which the recipe - containing the tasks depends. - A sysroot exists for both the target and for the - native binaries, which run on the host system. - - - do_configure: - This task configures the source by enabling and - disabling any build-time and configuration options - for the software being built. - Configurations can come from the recipe itself as - well as from an inherited class. - Additionally, the software itself might configure - itself depending on the target for which it is - being built. - - The configurations handled by the - do_configure - task are specific to source code configuration for - the source code being built by the recipe. - - If you are using the - autotools - class, you can add additional configuration options - by using the - EXTRA_OECONF - or - PACKAGECONFIG_CONFARGS - variables. - For information on how this variable works within - that class, see the - meta/classes/autotools.bbclass - file. - - - do_compile: - Once a configuration task has been satisfied, BitBake - compiles the source using the - do_compile - task. - Compilation occurs in the directory pointed to by - the - B - variable. - Realize that the B directory - is, by default, the same as the - S - directory. - - - do_install: - Once compilation is done, BitBake executes the - do_install - task. - This task copies files from the - B directory and places them - in a holding area pointed to by the - D - variable. - - - -
- -
- Package Splitting - - - After source code is configured and compiled, the - OpenEmbedded build system analyzes - the results and splits the output into packages: - - - - - The - do_package - and - do_packagedata - tasks combine to analyze the files found in the - D - directory and split them into subsets based on available - packages and files. - The analyzing process involves the following as well as - other items: splitting out debugging symbols, looking at - shared library dependencies between packages, and looking - at package relationships. - The do_packagedata task creates - package metadata based on the analysis such that the - OpenEmbedded build system can generate the final packages. - Working, staged, and intermediate results of the analysis - and package splitting process use these areas: - - - PKGD: - The destination directory for packages before they - are split. - - - PKGDATA_DIR: - A shared, global-state directory that holds data - generated during the packaging process. - - - PKGDESTWORK: - A temporary work area used by the - do_package task. - - - PKGDEST: - The parent directory for packages after they have - been split. - - - The - FILES - variable defines the files that go into each package in - PACKAGES. - If you want details on how this is accomplished, you can - look at the - package - class. - - - - Depending on the type of packages being created (RPM, DEB, - or IPK), the - do_package_write_* - task creates the actual packages and places them in the - Package Feed area, which is - ${TMPDIR}/deploy. - You can see the - "Package Feeds" - section for more detail on that part of the build process. - - Support for creating feeds directly from the - deploy/* directories does not - exist. - Creating such feeds usually requires some kind of feed - maintenance mechanism that would upload the new - packages into an official package feed (e.g. the - Ångström distribution). - This functionality is highly distribution-specific - and thus is not provided out of the box. - - -
- -
- Image Generation - - - Once packages are split and stored in the Package Feeds - area, the OpenEmbedded build system uses BitBake to - generate the root filesystem image: - - - - - The image generation process consists of several stages and - depends on several tasks and variables. - The - do_rootfs - task creates the root filesystem (file and directory - structure) for an image. - This task uses several key variables to help create the - list of packages to actually install: - - - IMAGE_INSTALL: - Lists out the base set of packages to install from - the Package Feeds area. - - - PACKAGE_EXCLUDE: - Specifies packages that should not be installed. - - - IMAGE_FEATURES: - Specifies features to include in the image. - Most of these features map to additional packages - for installation. - - - PACKAGE_CLASSES: - Specifies the package backend to use and - consequently helps determine where to locate - packages within the Package Feeds area. - - - IMAGE_LINGUAS: - Determines the language(s) for which additional - language support packages are installed. - - - PACKAGE_INSTALL: - The final list of packages passed to the package manager - for installation into the image. - - - - - - With - IMAGE_ROOTFS - pointing to the location of the filesystem under - construction and the PACKAGE_INSTALL - variable providing the final list of packages to install, - the root file system is created. - - - - Package installation is under control of the package - manager (e.g. dnf/rpm, opkg, or apt/dpkg) regardless of - whether or not package management is enabled for the - target. - At the end of the process, if package management is not - enabled for the target, the package manager's data files - are deleted from the root filesystem. - As part of the final stage of package installation, - postinstall scripts that are part of the packages are run. - Any scripts that fail to run - on the build host are run on the target when the target - system is first booted. - If you are using a - read-only root filesystem, - all the post installation scripts must succeed during the - package installation phase since the root filesystem is - read-only. - - - - The final stages of the do_rootfs task - handle post processing. - Post processing includes creation of a manifest file and - optimizations. - - - - The manifest file (.manifest) resides - in the same directory as the root filesystem image. - This file lists out, line-by-line, the installed packages. - The manifest file is useful for the - testimage - class, for example, to determine whether or not to run - specific tests. - See the - IMAGE_MANIFEST - variable for additional information. - - - - Optimizing processes run across the image include - mklibs, prelink, - and any other post-processing commands as defined by the - ROOTFS_POSTPROCESS_COMMAND - variable. - The mklibs process optimizes the size - of the libraries, while the prelink - process optimizes the dynamic linking of shared libraries - to reduce start up time of executables. - - - - After the root filesystem is built, processing begins on - the image through the - do_image - task. - The build system runs any pre-processing commands as - defined by the - IMAGE_PREPROCESS_COMMAND - variable. - This variable specifies a list of functions to call before - the OpenEmbedded build system creates the final image - output files. - - - - The OpenEmbedded build system dynamically creates - do_image_* tasks as needed, based - on the image types specified in the - IMAGE_FSTYPES - variable. - The process turns everything into an image file or a set of - image files and can compress the root filesystem image to - reduce the overall size of the image. - The formats used for the root filesystem depend on the - IMAGE_FSTYPES variable. - Compression depends on whether the formats support - compression. - - - - As an example, a dynamically created task when creating a - particular image type would - take the following form: - - do_image_type - - So, if the type as specified by - the IMAGE_FSTYPES were - ext4, the dynamically generated task - would be as follows: - - do_image_ext4 - - - - - The final task involved in image creation is the - do_image_complete - task. - This task completes the image by applying any image - post processing as defined through the - IMAGE_POSTPROCESS_COMMAND - variable. - The variable specifies a list of functions to call once the - OpenEmbedded build system has created the final image - output files. - - The entire image generation process is run under - Pseudo. - Running under Pseudo ensures that the files in the - root filesystem have correct ownership. - - -
- -
- SDK Generation - - - The OpenEmbedded build system uses BitBake to generate the - Software Development Kit (SDK) installer script for both - the standard and extensible SDKs: - - - For more information on the cross-development toolchain - generation, see the - "Cross-Development Toolchain Generation" - section. - For information on advantages gained when building a - cross-development toolchain using the - do_populate_sdk - task, see the - "Building an SDK Installer" - section in the Yocto Project Application Development - and the Extensible Software Development Kit (SDK) - manual. - - - - - Like image generation, the SDK script process consists of - several stages and depends on many variables. - The do_populate_sdk and - do_populate_sdk_ext tasks use these - key variables to help create the list of packages to - actually install. - For information on the variables listed in the figure, - see the - "Application Development SDK" - section. - - - - The do_populate_sdk task helps create - the standard SDK and handles two parts: a target part and a - host part. - The target part is the part built for the target hardware - and includes libraries and headers. - The host part is the part of the SDK that runs on the - SDKMACHINE. - - - - The do_populate_sdk_ext task helps - create the extensible SDK and handles host and target parts - differently than its counter part does for the standard SDK. - For the extensible SDK, the task encapsulates the build - system, which includes everything needed (host and target) - for the SDK. - - - - Regardless of the type of SDK being constructed, the - tasks perform some cleanup after which a cross-development - environment setup script and any needed configuration files - are created. - The final output is the Cross-development - toolchain installation script (.sh - file), which includes the environment setup script. - -
- -
- Stamp Files and the Rerunning of Tasks - - - For each task that completes successfully, BitBake writes a - stamp file into the - STAMPS_DIR - directory. - The beginning of the stamp file's filename is determined - by the - STAMP - variable, and the end of the name consists of the task's - name and current - input checksum. - - This naming scheme assumes that - BB_SIGNATURE_HANDLER - is "OEBasicHash", which is almost always the case in - current OpenEmbedded. - - To determine if a task needs to be rerun, BitBake checks - if a stamp file with a matching input checksum exists - for the task. - If such a stamp file exists, the task's output is - assumed to exist and still be valid. - If the file does not exist, the task is rerun. - - The stamp mechanism is more general than the - shared state (sstate) cache mechanism described in the - "Setscene Tasks and Shared State" - section. - BitBake avoids rerunning any task that has a valid - stamp file, not just tasks that can be accelerated - through the sstate cache. - - However, you should realize that stamp files only - serve as a marker that some work has been done and that - these files do not record task output. - The actual task output would usually be somewhere in - TMPDIR - (e.g. in some recipe's - WORKDIR.) - What the sstate cache mechanism adds is a way to cache - task output that can then be shared between build - machines. - - Since STAMPS_DIR is usually a - subdirectory of TMPDIR, removing - TMPDIR will also remove - STAMPS_DIR, which means tasks will - properly be rerun to repopulate - TMPDIR. - - - - If you want some task to always be considered "out of - date", you can mark it with the - nostamp - varflag. - If some other task depends on such a task, then that - task will also always be considered out of date, which - might not be what you want. - - - - For details on how to view information about a task's - signature, see the - "Viewing Task Variable Dependencies" - section in the Yocto Project Development Tasks Manual. - -
- -
- Setscene Tasks and Shared State - - - The description of tasks so far assumes that BitBake needs - to build everything and there are no prebuilt objects - available. - BitBake does support skipping tasks if prebuilt objects are - available. - These objects are usually made available in the form of a - shared state (sstate) cache. - - For information on variables affecting sstate, see the - SSTATE_DIR - and - SSTATE_MIRRORS - variables. - - - - - The idea of a setscene task (i.e - do_taskname_setscene) - is a version of the task where - instead of building something, BitBake can skip to the end - result and simply place a set of files into specific - locations as needed. - In some cases, it makes sense to have a setscene task - variant (e.g. generating package files in the - do_package_write_* - task). - In other cases, it does not make sense, (e.g. a - do_patch - task or - do_unpack - task) since the work involved would be equal to or greater - than the underlying task. - - - - In the OpenEmbedded build system, the common tasks that - have setscene variants are - do_package, - do_package_write_*, - do_deploy, - do_packagedata, - and - do_populate_sysroot. - Notice that these are most of the tasks whose output is an - end result. - - - - The OpenEmbedded build system has knowledge of the - relationship between these tasks and other tasks that - precede them. - For example, if BitBake runs - do_populate_sysroot_setscene for - something, there is little point in running any of the - do_fetch, - do_unpack, - do_patch, - do_configure, - do_compile, and - do_install tasks. - However, if do_package needs to be - run, BitBake would need to run those other tasks. - - - - It becomes more complicated if everything can come - from an sstate cache because some objects are simply - not required at all. - For example, you do not need a compiler or native tools, - such as quilt, if there is nothing to compile or patch. - If the do_package_write_* packages - are available from sstate, BitBake does not need the - do_package task data. - - - - To handle all these complexities, BitBake runs in two - phases. - The first is the "setscene" stage. - During this stage, BitBake first checks the sstate cache - for any targets it is planning to build. - BitBake does a fast check to see if the object exists - rather than a complete download. - If nothing exists, the second phase, which is the setscene - stage, completes and the main build proceeds. - - - - If objects are found in the sstate cache, the OpenEmbedded - build system works backwards from the end targets specified - by the user. - For example, if an image is being built, the OpenEmbedded - build system first looks for the packages needed for - that image and the tools needed to construct an image. - If those are available, the compiler is not needed. - Thus, the compiler is not even downloaded. - If something was found to be unavailable, or the - download or setscene task fails, the OpenEmbedded build - system then tries to install dependencies, such as the - compiler, from the cache. - - - - The availability of objects in the sstate cache is - handled by the function specified by the - BB_HASHCHECK_FUNCTION - variable and returns a list of the objects that are - available. - The function specified by the - BB_SETSCENE_DEPVALID - variable is the function that determines whether a given - dependency needs to be followed, and whether for any given - relationship the function needs to be passed. - The function returns a True or False value. - -
-
- -
- Images - - - The images produced by the OpenEmbedded build system - are compressed forms of the - root filesystem that are ready to boot on a target device. - You can see from the - general Build Process figure - that BitBake output, in part, consists of images. - This section is going to look more closely at this output: - - - - - For a list of example images that the Yocto Project provides, - see the - "Images" - chapter in the Yocto Project Reference Manual. - - - - Images are written out to the - Build Directory - inside the - tmp/deploy/images/machine/ - folder as shown in the figure. - This folder contains any files expected to be loaded on the - target device. - The - DEPLOY_DIR - variable points to the deploy directory, - while the - DEPLOY_DIR_IMAGE - variable points to the appropriate directory containing images - for the current configuration. - - - kernel-image: - A kernel binary file. - The - KERNEL_IMAGETYPE - variable setting determines the naming scheme for the - kernel image file. - Depending on that variable, the file could begin with - a variety of naming strings. - The - deploy/images/machine - directory can contain multiple image files for the - machine. - - - root-filesystem-image: - Root filesystems for the target device (e.g. - *.ext3 or - *.bz2 files). - The - IMAGE_FSTYPES - variable setting determines the root filesystem image - type. - The - deploy/images/machine - directory can contain multiple root filesystems for the - machine. - - - kernel-modules: - Tarballs that contain all the modules built for the - kernel. - Kernel module tarballs exist for legacy purposes and - can be suppressed by setting the - MODULE_TARBALL_DEPLOY - variable to "0". - The - deploy/images/machine - directory can contain multiple kernel module tarballs - for the machine. - - - bootloaders: - Bootloaders supporting the image, if applicable to the - target machine. - The deploy/images/machine - directory can contain multiple bootloaders for the - machine. - - - symlinks: - The - deploy/images/machine - folder contains a symbolic link that points to the - most recently built file for each machine. - These links might be useful for external scripts that - need to obtain the latest version of each file. - - - -
- -
- Application Development SDK - - - In the - general Yocto Project Development Environment figure, - the output labeled "Application Development SDK" represents an - SDK. - The SDK generation process differs depending on whether you - build a standard SDK (e.g. - bitbake -c populate_sdk imagename) - or an extensible SDK (e.g. - bitbake -c populate_sdk_ext imagename). - This section is going to take a closer look at this output: - - - - - The specific form of this output is a self-extracting - SDK installer (*.sh) that, when run, - installs the SDK, which consists of a cross-development - toolchain, a set of libraries and headers, and an SDK - environment setup script. - Running this installer essentially sets up your - cross-development environment. - You can think of the cross-toolchain as the "host" - part because it runs on the SDK machine. - You can think of the libraries and headers as the "target" - part because they are built for the target hardware. - The environment setup script is added so that you can - initialize the environment before using the tools. - - - Notes - - - The Yocto Project supports several methods by which - you can set up this cross-development environment. - These methods include downloading pre-built SDK - installers or building and installing your own SDK - installer. - - - For background information on cross-development - toolchains in the Yocto Project development - environment, see the - "Cross-Development Toolchain Generation" - section. - - - For information on setting up a cross-development - environment, see the - Yocto Project Application Development and the Extensible Software Development Kit (eSDK) - manual. - - - - - - Once built, the SDK installers are written out to the - deploy/sdk folder inside the - Build Directory - as shown in the figure at the beginning of this section. - Depending on the type of SDK, several variables exist that help - configure these files. - The following list shows the variables associated with - a standard SDK: - - - DEPLOY_DIR: - Points to the deploy - directory. - - - SDKMACHINE: - Specifies the architecture of the machine - on which the cross-development tools are run to - create packages for the target hardware. - - - SDKIMAGE_FEATURES: - Lists the features to include in the "target" part - of the SDK. - - - TOOLCHAIN_HOST_TASK: - Lists packages that make up the host - part of the SDK (i.e. the part that runs on - the SDKMACHINE). - When you use - bitbake -c populate_sdk imagename - to create the SDK, a set of default packages - apply. - This variable allows you to add more packages. - - - TOOLCHAIN_TARGET_TASK: - Lists packages that make up the target part - of the SDK (i.e. the part built for the - target hardware). - - - SDKPATH: - Defines the default SDK installation path offered - by the installation script. - - - This next list, shows the variables associated with an - extensible SDK: - - - DEPLOY_DIR: - Points to the deploy directory. - - - SDK_EXT_TYPE: - Controls whether or not shared state artifacts are - copied into the extensible SDK. - By default, all required shared state artifacts are - copied into the SDK. - - - SDK_INCLUDE_PKGDATA: - Specifies whether or not packagedata will be - included in the extensible SDK for all recipes in - the "world" target. - - - SDK_INCLUDE_TOOLCHAIN: - Specifies whether or not the toolchain will be included - when building the extensible SDK. - - - SDK_LOCAL_CONF_WHITELIST: - A list of variables allowed through from the build - system configuration into the extensible SDK - configuration. - - - SDK_LOCAL_CONF_BLACKLIST: - A list of variables not allowed through from the build - system configuration into the extensible SDK - configuration. - - - SDK_INHERIT_BLACKLIST: - A list of classes to remove from the - INHERIT - value globally within the extensible SDK configuration. - - - -
-
- -
- Cross-Development Toolchain Generation - - - The Yocto Project does most of the work for you when it comes to - creating - cross-development toolchains. - This section provides some technical background on how - cross-development toolchains are created and used. - For more information on toolchains, you can also see the - Yocto Project Application Development and the Extensible Software Development Kit (eSDK) - manual. - - - - In the Yocto Project development environment, cross-development - toolchains are used to build the image and applications that run - on the target hardware. - With just a few commands, the OpenEmbedded build system creates - these necessary toolchains for you. - - - - The following figure shows a high-level build environment regarding - toolchain construction and use. - - - - - - - - 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 - 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. - - The extensible SDK does not use - gcc-cross-canadian since this SDK - ships a copy of the OpenEmbedded build system and the sysroot - within it contains gcc-cross. - - - - - The chain of events that occurs when gcc-cross is - bootstrapped is as follows: - - gcc -> binutils-cross -> gcc-cross-initial -> linux-libc-headers -> glibc-initial -> glibc -> gcc-cross -> gcc-runtime - - - - gcc: - The build host's GNU Compiler Collection (GCC). - - - binutils-cross: - The bare minimum binary utilities needed in order to run - the gcc-cross-initial phase of the - bootstrap operation. - - - gcc-cross-initial: - An early stage of the bootstrap process for creating - the cross-compiler. - This stage builds enough of the gcc-cross, - the C library, and other pieces needed to finish building the - final cross-compiler in later stages. - This tool is a "native" package (i.e. it is designed to run on - the build host). - - - linux-libc-headers: - Headers needed for the cross-compiler. - - - glibc-initial: - An initial version of the Embedded GLIBC needed to bootstrap - glibc. - - - gcc-cross: - The final stage of the bootstrap process for the - cross-compiler. - This stage results in the actual cross-compiler that - BitBake uses when it builds an image for a targeted - device. - - If you are replacing this cross compiler toolchain - with a custom version, you must replace - gcc-cross. - - This tool is also a "native" package (i.e. it is - designed to run on the build host). - - - gcc-runtime: - Runtime libraries resulting from the toolchain bootstrapping - process. - This tool produces a binary that consists of the - runtime libraries need for the targeted device. - - - - - - 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., - gcc-cross-canadian, - binutils-cross-canadian, and other - nativesdk-* tools), - which are tools native to the SDK (i.e. native to - SDK_ARCH), - you need to cross-compile and test your software. - The figure shows the commands you use to easily build out this - toolchain. - This cross-development toolchain is built to execute on the - SDKMACHINE, - which might or might not be the same - machine as the Build Host. - - If your target architecture is supported by the Yocto Project, - you can take advantage of pre-built images that ship with the - Yocto Project and already contain cross-development toolchain - installers. - - - - - Here is the bootstrap process for the relocatable toolchain: - - gcc -> binutils-crosssdk -> gcc-crosssdk-initial -> linux-libc-headers -> - glibc-initial -> nativesdk-glibc -> gcc-crosssdk -> gcc-cross-canadian - - - - gcc: - The build host's GNU Compiler Collection (GCC). - - - binutils-crosssdk: - The bare minimum binary utilities needed in order to run - the gcc-crosssdk-initial phase of the - bootstrap operation. - - - gcc-crosssdk-initial: - An early stage of the bootstrap process for creating - the cross-compiler. - This stage builds enough of the - gcc-crosssdk and supporting pieces so that - the final stage of the bootstrap process can produce the - finished cross-compiler. - This tool is a "native" binary that runs on the build host. - - - linux-libc-headers: - Headers needed for the cross-compiler. - - - glibc-initial: - An initial version of the Embedded GLIBC needed to bootstrap - nativesdk-glibc. - - - nativesdk-glibc: - The Embedded GLIBC needed to bootstrap the - gcc-crosssdk. - - - gcc-crosssdk: - The final stage of the bootstrap process for the - relocatable cross-compiler. - The gcc-crosssdk is a transitory compiler - and never leaves the build host. - Its purpose is to help in the bootstrap process to create the - eventual relocatable gcc-cross-canadian - compiler, which is relocatable. - This tool is also a "native" package (i.e. it is - designed to run on the build host). - - - gcc-cross-canadian: - The final relocatable cross-compiler. - When run on the - SDKMACHINE, - this tool - produces executable code that runs on the target device. - Only one cross-canadian compiler is produced per architecture - since they can be targeted at different processor optimizations - using configurations passed to the compiler through the - compile commands. - This circumvents the need for multiple compilers and thus - reduces the size of the toolchains. - - - - - - For information on advantages gained when building a - cross-development toolchain installer, see the - "Building an SDK Installer" - section in the Yocto Project Application Development and the - Extensible Software Development Kit (eSDK) manual. - -
- -
- Shared State Cache - - - By design, the OpenEmbedded build system builds everything from - 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. - When developers hit problems, they typically default back to - building from scratch so they know the state of things from the - start. - - - - Building an image from scratch is both an advantage and a - disadvantage to the process. - As mentioned in the previous paragraph, building from scratch - ensures that everything is current and starts from a known state. - However, building from scratch also takes much longer as it - generally means rebuilding things that do not necessarily need - to be rebuilt. - - - - The Yocto Project implements shared state code that supports - incremental builds. - The implementation of the shared state code answers the following - questions that were fundamental roadblocks within the OpenEmbedded - incremental build support system: - - - What pieces of the system have changed and what pieces have - not changed? - - - How are changed pieces of software removed and replaced? - - - How are pre-built components that do not need to be rebuilt - from scratch used when they are available? - - - - - - 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 - which tasks add which output to the build process. - This means the output from a given task can be removed, upgraded - or otherwise manipulated. - The third question is partly addressed by the solution for the - second question assuming the build system can fetch the sstate - objects from remote locations and install them if they are deemed - to be valid. - - The OpenEmbedded build system does not maintain - PR - information as part of the shared state packages. - Consequently, considerations exist that affect maintaining - shared state feeds. - For information on how the OpenEmbedded build system - works with packages and can track incrementing - PR information, see the - "Automatically Incrementing a Binary Package Revision Number" - section in the Yocto Project Development Tasks Manual. - - - - - The rest of this section goes into detail about the overall - incremental build architecture, the checksums (signatures), shared - state, and some tips and tricks. - - -
- Overall Architecture - - - When determining what parts of the system need to be built, - BitBake works on a per-task basis rather than a per-recipe - basis. - You might wonder why using a per-task basis is preferred over - a per-recipe basis. - To help explain, consider having the IPK packaging backend - enabled and then switching to DEB. - In this case, the - do_install - and - do_package - task outputs are still valid. - However, with a per-recipe approach, the build would not - include the .deb files. - Consequently, you would have to invalidate the whole build and - rerun it. - Rerunning everything is not the best solution. - Also, in this case, the core must be "taught" much about - specific tasks. - This methodology does not scale well and does not allow users - to easily add new tasks in layers or as external recipes - without touching the packaged-staging core. - -
- -
- Checksums (Signatures) - - - The shared state code uses a checksum, which is a unique - signature of a task's inputs, to determine if a task needs to - be run again. - Because it is a change in a task's inputs that triggers a - rerun, the process needs to detect all the inputs to a given - task. - For shell tasks, this turns out to be fairly easy because - the build process generates a "run" shell script for each task - and it is possible to create a checksum that gives you a good - idea of when the task's data changes. - - - - To complicate the problem, there are things that should not be - included in the checksum. - First, there is the actual specific build path of a given - task - the - WORKDIR. - It does not matter if the work directory changes because it - should not affect the output for target packages. - Also, the build process has the objective of making native - or cross packages relocatable. - - Both native and cross packages run on the - build host. - However, cross packages generate output for the target - architecture. - - The checksum therefore needs to exclude - WORKDIR. - The simplistic approach for excluding the work directory is to - set WORKDIR to some fixed value and - create the checksum for the "run" script. - - - - Another problem results from the "run" scripts containing - functions that might or might not get called. - The incremental build solution contains code that figures out - dependencies between shell functions. - This code is used to prune the "run" scripts down to the - minimum set, thereby alleviating this problem and making the - "run" scripts much more readable as a bonus. - - - - So far, solutions for shell scripts exist. - What about Python tasks? - The same approach applies even though these tasks are more - difficult. - The process needs to figure out what variables a Python - function accesses and what functions it calls. - Again, the incremental build solution contains code that first - figures out the variable and function dependencies, and then - creates a checksum for the data used as the input to the task. - - - - Like the WORKDIR case, situations exist - where dependencies should be ignored. - For these situations, you can instruct the build process to - ignore a dependency by using a line like the following: - - PACKAGE_ARCHS[vardepsexclude] = "MACHINE" - - This example ensures that the - PACKAGE_ARCHS - variable does not depend on the value of - MACHINE, - even if it does reference it. - - - - 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: - - PACKAGE_ARCHS[vardeps] = "MACHINE" - - This example explicitly adds the MACHINE - variable as a dependency for - PACKAGE_ARCHS. - - - - 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 - discovers something for which it cannot figure out dependencies. - The Yocto Project team has currently not managed to cover - those dependencies in detail and is aware of the need to fix - this situation. - - - - Thus far, this section has limited discussion to the direct - inputs into a task. - 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. - 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. - However, the effect is to generate a master checksum that - combines the basehash and the hashes of the task's - dependencies. - - - - 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, 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 - included in any checksum: - - BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH DL_DIR \ - SSTATE_DIR THISDIR FILESEXTRAPATHS FILE_DIRNAME HOME LOGNAME SHELL TERM \ - USER FILESPATH STAGING_DIR_HOST STAGING_DIR_TARGET COREBASE PRSERV_HOST \ - PRSERV_DUMPDIR PRSERV_DUMPFILE PRSERV_LOCKDOWN PARALLEL_MAKE \ - CCACHE_DIR EXTERNAL_TOOLCHAIN CCACHE CCACHE_DISABLE LICENSE_PATH SDKPKGSUFFIX" - - The previous example excludes - WORKDIR - since that variable is actually constructed as a path within - TMPDIR, - which is on the whitelist. - - - - The rules for deciding which hashes of dependent tasks to - include through dependency chains are more complex and are - generally accomplished with a Python function. - The code in meta/lib/oe/sstatesig.py shows - two examples of this and also illustrates how you can insert - your own policy into the system if so desired. - This file defines the two basic signature generators - OE-Core - uses: "OEBasic" and "OEBasicHash". - By default, there is a dummy "noop" signature handler enabled - in BitBake. - This means that behavior is unchanged from previous versions. - OE-Core uses the "OEBasicHash" signature handler by default - through this setting in the bitbake.conf - file: - - BB_SIGNATURE_HANDLER ?= "OEBasicHash" - - The "OEBasicHash" BB_SIGNATURE_HANDLER - is the same as the "OEBasic" version but adds the task hash to - the stamp files. - This results in any - Metadata - change that changes the task hash, automatically - causing the task to be run again. - This removes the need to bump - PR - values, and changes to Metadata automatically ripple across - the build. - - - - It is also worth noting that the end result of these - signature generators is to make some dependency and hash - information available to the build. - This information includes: - - - BB_BASEHASH_task-taskname: - The base hashes for each task in the recipe. - - - BB_BASEHASH_filename:taskname: - The base hashes for each dependent task. - - - BBHASHDEPS_filename:taskname: - The task dependencies for each task. - - - BB_TASKHASH: - The hash of the currently running task. - - - -
- -
- Shared State - - - Checksums and dependencies, as discussed in the previous - section, solve half the problem of supporting a shared state. - The other part of the problem is being able to use checksum - information during the build and being able to reuse or rebuild - specific components. - - - - The - sstate - class is a relatively generic implementation of how to - "capture" a snapshot of a given task. - The idea is that the build process does not care about the - source of a task's output. - Output could be freshly built or it could be downloaded and - unpacked from somewhere - the build process does not need to - worry about its origin. - - - - 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 - or - do_package. - The other type of output occurs when a set of data is merged - into a shared directory tree such as the sysroot. - - - - The Yocto Project team has tried to keep the details of the - implementation hidden in sstate class. - From a user's perspective, adding shared state wrapping to a task - is as simple as this - do_deploy - example taken from the - deploy - class: - - DEPLOYDIR = "${WORKDIR}/deploy-${PN}" - SSTATETASKS += "do_deploy" - do_deploy[sstate-inputdirs] = "${DEPLOYDIR}" - do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}" - - python do_deploy_setscene () { - sstate_setscene(d) - } - addtask do_deploy_setscene - do_deploy[dirs] = "${DEPLOYDIR} ${B}" - - The following list explains the previous example: - - - Adding "do_deploy" to SSTATETASKS - adds some required sstate-related processing, which is - implemented in the - sstate - class, to before and after the - do_deploy - task. - - - The - do_deploy[sstate-inputdirs] = "${DEPLOYDIR}" - declares that do_deploy places its - output in ${DEPLOYDIR} when run - normally (i.e. when not using the sstate cache). - This output becomes the input to the shared state cache. - - - The - do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}" - line causes the contents of the shared state cache to be - copied to ${DEPLOY_DIR_IMAGE}. - - If do_deploy is not already in - the shared state cache or if its input checksum - (signature) has changed from when the output was - cached, the task will be run to populate the shared - state cache, after which the contents of the shared - state cache is copied to - ${DEPLOY_DIR_IMAGE}. - If do_deploy is in the shared - state cache and its signature indicates that the - cached output is still valid (i.e. if no - relevant task inputs have changed), then the - contents of the shared state cache will be copied - directly to - ${DEPLOY_DIR_IMAGE} by the - do_deploy_setscene task - instead, skipping the - do_deploy task. - - - - The following task definition is glue logic needed to - make the previous settings effective: - - python do_deploy_setscene () { - sstate_setscene(d) - } - addtask do_deploy_setscene - - sstate_setscene() takes the flags - above as input and accelerates the - do_deploy task through the - shared state cache if possible. - If the task was accelerated, - sstate_setscene() returns True. - Otherwise, it returns False, and the normal - do_deploy task runs. - For more information, see the - "setscene" - section in the BitBake User Manual. - - - The do_deploy[dirs] = "${DEPLOYDIR} ${B}" - line creates ${DEPLOYDIR} and - ${B} before the - do_deploy task runs, and also sets - the current working directory of - do_deploy to - ${B}. - For more information, see the - "Variable Flags" - section in the BitBake User Manual. - - In cases where - sstate-inputdirs and - sstate-outputdirs would be the - same, you can use - sstate-plaindirs. - For example, to preserve the - ${PKGD} and - ${PKGDEST} output from the - do_package - task, use the following: - - do_package[sstate-plaindirs] = "${PKGD} ${PKGDEST}" - - - - - sstate-inputdirs and - sstate-outputdirs can also be used - with multiple directories. - For example, the following declares - PKGDESTWORK and - SHLIBWORK as shared state - input directories, which populates the shared state - cache, and PKGDATA_DIR and - SHLIBSDIR as the corresponding - shared state output directories: - - do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}" - do_package[sstate-outputdirs] = "${PKGDATA_DIR} ${SHLIBSDIR}" - - - - These methods also include the ability to take a - lockfile when manipulating shared state directory - structures, for cases where file additions or removals - are sensitive: - - do_package[sstate-lockfile] = "${PACKAGELOCK}" - - - - - - - Behind the scenes, the shared state code works by looking in - SSTATE_DIR - and - SSTATE_MIRRORS - for shared state files. - Here is an example: - - SSTATE_MIRRORS ?= "\ - file://.* http://someserver.tld/share/sstate/PATH;downloadfilename=PATH \n \ - file://.* file:///some/local/dir/sstate/PATH" - - - The shared state directory - (SSTATE_DIR) is organized into - two-character subdirectories, where the subdirectory - names are based on the first two characters of the hash. - If the shared state directory structure for a mirror has the - same structure as SSTATE_DIR, you must - specify "PATH" as part of the URI to enable the build system - to map to the appropriate subdirectory. - - - - - The shared state package validity can be detected just by - looking at the filename since the filename contains the task - checksum (or signature) as described earlier in this section. - If a valid shared state package is found, the build process - downloads it and uses it to accelerate the task. - - - - The build processes use the *_setscene - tasks for the task acceleration phase. - BitBake goes through this phase before the main execution - code and tries to accelerate any tasks for which it can find - shared state packages. - If a shared state package for a task is available, the - shared state package is used. - This means the task and any tasks on which it is dependent - are not executed. - - - - As a real world example, the aim is when building an IPK-based - image, only the - do_package_write_ipk - tasks would have their shared state packages fetched and - extracted. - Since the sysroot is not used, it would never get extracted. - This is another reason why a task-based approach is preferred - over a recipe-based approach, which would have to install the - output from every task.n - -
- -
- Tips and Tricks - - - The code in the build system that supports incremental builds - is not simple code. - This section presents some tips and tricks that help you work - around issues related to shared state code. - - -
- Debugging - - - Seeing what metadata went into creating the input signature - of a shared state (sstate) task can be a useful debugging - aid. - This information is available in signature information - (siginfo) files in - SSTATE_DIR. - For information on how to view and interpret information in - siginfo files, see the - "Viewing Task Variable Dependencies" - section in the Yocto Project Development Tasks Manual. - -
- -
- Invalidating Shared State - - - The OpenEmbedded build system uses checksums and shared - state cache to avoid unnecessarily rebuilding tasks. - Collectively, this scheme is known as "shared state code." - - - - As with all schemes, this one has some drawbacks. - It is possible that you could make implicit changes to your - code that the checksum calculations do not take into - account. - These implicit changes affect a task's output but do not - trigger the shared state code into rebuilding a recipe. - Consider an example during which a tool changes its output. - Assume that the output of rpmdeps - changes. - The result of the change should be that all the - package and - package_write_rpm shared state cache - items become invalid. - However, because the change to the output is - external to the code and therefore implicit, - the associated shared state cache items do not become - invalidated. - In this case, the build process uses the cached items - rather than running the task again. - Obviously, these types of implicit changes can cause - problems. - - - - To avoid these problems during the build, you need to - understand the effects of any changes you make. - Realize that changes you make directly to a function - are automatically factored into the checksum calculation. - Thus, these explicit changes invalidate the associated - area of shared state cache. - However, you need to be aware of any implicit changes that - are not obvious changes to the code and could affect - the output of a given task. - - - - When you identify an implicit change, you can easily - take steps to invalidate the cache and force the tasks - to run. - The steps you can take are as simple as changing a - function's comments in the source code. - For example, to invalidate package shared state files, - change the comment statements of - do_package - or the comments of one of the functions it calls. - Even though the change is purely cosmetic, it causes the - checksum to be recalculated and forces the OpenEmbedded - build system to run the task again. - - For an example of a commit that makes a cosmetic - change to invalidate shared state, see this - commit. - - -
-
-
- -
- Automatically Added Runtime Dependencies - - - The OpenEmbedded build system automatically adds common types of - runtime dependencies between packages, which means that you do not - need to explicitly declare the packages using - RDEPENDS. - Three automatic mechanisms exist (shlibdeps, - pcdeps, and depchains) - that handle shared libraries, package configuration (pkg-config) - modules, and -dev and - -dbg packages, respectively. - For other types of runtime dependencies, you must manually declare - the dependencies. - - - shlibdeps: - During the - do_package - task of each recipe, all shared libraries installed by the - recipe are located. - For each shared library, the package that contains the - shared library is registered as providing the shared - library. - More specifically, the package is registered as providing - the - soname - of the library. - The resulting shared-library-to-package mapping - is saved globally in - PKGDATA_DIR - by the - do_packagedata - task. - - Simultaneously, all executables and shared libraries - installed by the recipe are inspected to see what shared - libraries they link against. - For each shared library dependency that is found, - PKGDATA_DIR is queried to - see if some package (likely from a different recipe) - contains the shared library. - If such a package is found, a runtime dependency is added - from the package that depends on the shared library to the - package that contains the library. - - The automatically added runtime dependency also - includes a version restriction. - This version restriction specifies that at least the - current version of the package that provides the shared - library must be used, as if - "package (>= version)" - 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. - - If you want to avoid a package being registered as - providing a particular shared library (e.g. because the library - is for internal use only), then add the library to - PRIVATE_LIBS - inside the package's recipe. - - - pcdeps: - 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. - - Simultaneously, all pkg-config modules installed by - the recipe are inspected to see what other pkg-config - modules they depend on. - A module is seen as depending on another module if it - contains a "Requires:" line that specifies the other module. - For each module dependency, - PKGDATA_DIR is queried to see if some - package contains the module. - If such a package is found, a runtime dependency is added - from the package that depends on the module to the package - that contains the module. - - The pcdeps mechanism most often - infers dependencies between -dev - packages. - - - - depchains: - If a package foo depends on a package - bar, then foo-dev - and foo-dbg are also made to depend on - bar-dev and - bar-dbg, respectively. - Taking the -dev packages as an - example, the bar-dev package might - provide headers and shared library symlinks needed by - foo-dev, which shows the need - for a dependency between the packages. - - The dependencies added by - depchains are in the form of - RRECOMMENDS. - - By default, foo-dev also has an - RDEPENDS-style dependency on - foo, because the default value of - RDEPENDS_${PN}-dev (set in - bitbake.conf) includes - "${PN}". - - - To ensure that the dependency chain is never broken, - -dev and -dbg - packages are always generated by default, even if the - packages turn out to be empty. - See the - ALLOW_EMPTY - variable for more information. - - - - - - The do_package task depends on the - do_packagedata task of each recipe in - DEPENDS - through use of a - [deptask] - declaration, which guarantees that the required - shared-library/module-to-package mapping information will be available - when needed as long as DEPENDS has been - correctly set. - -
- -
- Fakeroot and Pseudo - - - Some tasks are easier to implement when allowed to perform certain - operations that are normally reserved for the root user (e.g. - do_install, - do_package_write*, - do_rootfs, - and - do_image*). - For example, the do_install task benefits - from being able to set the UID and GID of installed files to - arbitrary values. - - - - One approach to allowing tasks to perform root-only operations - 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. - Within this environment, the task and its child processes believe - that they are running as the root user, and see an internally - consistent view of the filesystem. - As long as generating the final output (e.g. a package or an image) - does not require root privileges, the fact that some earlier - steps ran in a fake root environment does not cause problems. - - - - The capability to run tasks in a fake root environment is known as - "fakeroot", - which is derived from the BitBake keyword/variable - flag that requests a fake root environment for a task. - - - - 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. - To keep track of "fake" file ownership and permissions resulting - from operations that require root permissions, Pseudo uses - an SQLite 3 database. - This database is stored in - ${WORKDIR}/pseudo/files.db - for individual recipes. - Storing the database in a file as opposed to in memory - gives persistence between tasks and builds, which is not - accomplished using fakeroot. - Caution - If you add your own task that manipulates the same files or - directories as a fakeroot task, then that task also needs to - run under fakeroot. - Otherwise, the task cannot run root-only operations, and - cannot see the fake file ownership and permissions set by the - other task. - You need to also add a dependency on - virtual/fakeroot-native:do_populate_sysroot, - giving the following: - - fakeroot do_mytask () { - ... - } - do_mytask[depends] += "virtual/fakeroot-native:do_populate_sysroot" - - - For more information, see the - FAKEROOT* - variables in the BitBake User Manual. - You can also reference the - "Pseudo" - and - "Why Not Fakeroot?" - articles for background information on Pseudo. - -
- -
- Wayland - - - Wayland - is a computer display server protocol that - provides a method for compositing window managers to communicate - directly with applications and video hardware and expects them to - communicate with input hardware using other libraries. - Using Wayland with supporting targets can result in better control - over graphics frame rendering than an application might otherwise - achieve. - - - - The Yocto Project provides the Wayland protocol libraries and the - reference - Weston - compositor as part of its release. - This section describes what you need to do to implement Wayland and - use the compositor when building an image for a supporting target. - - -
- Support - - - The Wayland protocol libraries and the reference Weston - compositor ship as integrated packages in the - meta layer of the - Source Directory. - Specifically, you can find the recipes that build both Wayland - and Weston at - meta/recipes-graphics/wayland. - - - - You can build both the Wayland and Weston packages for use only - with targets that accept the - Mesa 3D and Direct Rendering Infrastructure, - which is also known as Mesa DRI. - This implies that you cannot build and use the packages if your - target uses, for example, the - Intel Embedded Media - and Graphics Driver - (Intel EMGD) that - overrides Mesa DRI. - - Due to lack of EGL support, Weston 1.0.3 will not run - directly on the emulated QEMU hardware. - However, this version of Weston will run under X emulation - without issues. - - -
- -
- Enabling Wayland in an Image - - - To enable Wayland, you need to enable it to be built and enable - it to be included in the image. - - -
- Building - - - To cause Mesa to build the wayland-egl - platform and Weston to build Wayland with Kernel Mode - Setting - (KMS) - support, include the "wayland" flag in the - DISTRO_FEATURES - statement in your local.conf file: - - DISTRO_FEATURES_append = " wayland" - - - If X11 has been enabled elsewhere, Weston will build - Wayland with X11 support - - -
- -
- Installing - - - To install the Wayland feature into an image, you must - include the following - CORE_IMAGE_EXTRA_INSTALL - statement in your local.conf file: - - CORE_IMAGE_EXTRA_INSTALL += "wayland weston" - - -
-
- -
- Running Weston - - - To run Weston inside X11, enabling it as described earlier and - building a Sato image is sufficient. - If you are running your image under Sato, a Weston Launcher - appears in the "Utility" category. - - - - Alternatively, you can run Weston through the command-line - interpretor (CLI), which is better suited for development work. - To run Weston under the CLI, you need to do the following after - your image is built: - - - Run these commands to export - XDG_RUNTIME_DIR: - - mkdir -p /tmp/$USER-weston - chmod 0700 /tmp/$USER-weston - export XDG_RUNTIME_DIR=/tmp/$USER-weston - - - - Launch Weston in the shell: - - weston - - - -
-
- -
- Licenses - - - 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. - - - - 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 Tasks Manual. - - -
- Tracking License Changes - - - The license of an upstream project might change in the future. - In order to prevent these changes going unnoticed, the - LIC_FILES_CHKSUM - variable tracks changes to the license text. The checksums are - validated at the end of the configure step, and if the - checksums do not match, the build will fail. - - -
- Specifying the <filename>LIC_FILES_CHKSUM</filename> Variable - - - The LIC_FILES_CHKSUM - variable contains checksums of the license text in the - source code for the recipe. - Following is an example of how to specify - LIC_FILES_CHKSUM: - - LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \ - file://licfile1.txt;beginline=5;endline=29;md5=yyyy \ - file://licfile2.txt;endline=50;md5=zzzz \ - ..." - - Notes - - - When using "beginline" and "endline", realize - that line numbering begins with one and not - zero. - Also, the included lines are inclusive (i.e. - lines five through and including 29 in the - previous example for - licfile1.txt). - - - When a license check fails, the selected license - text is included as part of the QA message. - Using this output, you can determine the exact - start and finish for the needed license text. - - - - - - - The build system uses the - S - variable as the default directory when searching files - listed in LIC_FILES_CHKSUM. - The previous example employs the default directory. - - - - Consider this next example: - - LIC_FILES_CHKSUM = "file://src/ls.c;beginline=5;endline=16;\ - md5=bb14ed3c4cda583abc85401304b5cd4e" - LIC_FILES_CHKSUM = "file://${WORKDIR}/license.html;md5=5c94767cedb5d6987c902ac850ded2c6" - - - - - The first line locates a file in - ${S}/src/ls.c and isolates lines five - through 16 as license text. - The second line refers to a file in - WORKDIR. - - - - Note that LIC_FILES_CHKSUM variable is - mandatory for all recipes, unless the - LICENSE variable is set to "CLOSED". - -
- -
- Explanation of Syntax - - - As mentioned in the previous section, the - LIC_FILES_CHKSUM variable lists all - the important files that contain the license text for the - source code. - It is possible to specify a checksum for an entire file, - or a specific section of a file (specified by beginning and - ending line numbers with the "beginline" and "endline" - parameters, respectively). - The latter is useful for source files with a license - notice header, README documents, and so forth. - If you do not use the "beginline" parameter, then it is - assumed that the text begins on the first line of the file. - Similarly, if you do not use the "endline" parameter, - it is assumed that the license text ends with the last - line of the file. - - - - The "md5" parameter stores the md5 checksum of the license - text. - If the license text changes in any way as compared to - this parameter then a mismatch occurs. - This mismatch triggers a build failure and notifies - the developer. - Notification allows the developer to review and address - the license text changes. - Also note that if a mismatch occurs during the build, - the correct md5 checksum is placed in the build log and - can be easily copied to the recipe. - - - - There is no limit to how many files you can specify using - the LIC_FILES_CHKSUM variable. - Generally, however, every project requires a few - specifications for license tracking. - Many projects have a "COPYING" file that stores the - license information for all the source code files. - This practice allows you to just track the "COPYING" - file as long as it is kept up to date. - Tips - - - If you specify an empty or invalid "md5" - 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 - the build log. - - - If the whole file contains only license text, - you do not need to use the "beginline" and - "endline" parameters. - - - - -
-
- -
- Enabling Commercially Licensed Recipes - - - By default, the OpenEmbedded build system disables - components that have commercial or other special licensing - requirements. - Such requirements are defined on a - recipe-by-recipe basis through the - LICENSE_FLAGS - variable definition in the affected recipe. - For instance, the - poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly - recipe contains the following statement: - - LICENSE_FLAGS = "commercial" - - Here is a slightly more complicated example that contains both - an explicit recipe name and version (after variable expansion): - - LICENSE_FLAGS = "license_${PN}_${PV}" - - In order for a component restricted by a - LICENSE_FLAGS definition to be enabled and - included in an image, it needs to have a matching entry in the - global - LICENSE_FLAGS_WHITELIST - variable, which is a variable typically defined in your - local.conf file. - For example, to enable the - poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly - package, you could add either the string - "commercial_gst-plugins-ugly" or the more general string - "commercial" to LICENSE_FLAGS_WHITELIST. - See the - "License Flag Matching" - section for a full - explanation of how LICENSE_FLAGS matching - works. - Here is the example: - - LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly" - - Likewise, to additionally enable the package built from the - recipe containing - LICENSE_FLAGS = "license_${PN}_${PV}", - and assuming that the actual recipe name was - emgd_1.10.bb, the following string would - enable that package as well as the original - gst-plugins-ugly package: - - LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly license_emgd_1.10" - - As a convenience, you do not need to specify the complete - license string in the whitelist for every package. - You can use an abbreviated form, which consists - of just the first portion or portions of the license - string before the initial underscore character or characters. - A partial string will match any license that contains the - given string as the first portion of its license. - For example, the following whitelist string will also match - both of the packages previously mentioned as well as any other - packages that have licenses starting with "commercial" or - "license". - - LICENSE_FLAGS_WHITELIST = "commercial license" - - - -
- License Flag Matching - - - 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 - 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 - system to exclude a recipe. - - - - In general, license flag matching is simple. - However, understanding some concepts will help you - correctly and effectively use matching. - - - - Before a flag - defined by a particular recipe is tested against the - contents of the whitelist, the expanded string - _${PN} is appended to the flag. - This expansion makes each - LICENSE_FLAGS value recipe-specific. - After expansion, the string is then matched against the - whitelist. - Thus, specifying - LICENSE_FLAGS = "commercial" - in recipe "foo", for example, results in the string - "commercial_foo". - And, to create a match, that string must appear in the - whitelist. - - - - Judicious use of the LICENSE_FLAGS - strings and the contents of the - LICENSE_FLAGS_WHITELIST variable - allows you a lot of flexibility for including or excluding - recipes based on licensing. - For example, you can broaden the matching capabilities by - using license flags string subsets in the whitelist. - - When using a string subset, be sure to use the part of - the expanded string that precedes the appended - underscore character (e.g. - usethispart_1.3, - usethispart_1.4, and so forth). - - For example, simply specifying the string "commercial" in - the whitelist matches any expanded - LICENSE_FLAGS definition that starts - with the string "commercial" such as "commercial_foo" and - "commercial_bar", which are the strings the build system - automatically generates for hypothetical recipes named - "foo" and "bar" assuming those recipes simply specify the - following: - - LICENSE_FLAGS = "commercial" - - Thus, you can choose to exhaustively - enumerate each license flag in the whitelist and - allow only specific recipes into the image, or - you can use a string subset that causes a broader range of - matches to allow a range of recipes into the image. - - - - This scheme works even if the - LICENSE_FLAGS string already - has _${PN} appended. - For example, the build system turns the license flag - "commercial_1.2_foo" into "commercial_1.2_foo_foo" and - would match both the general "commercial" and the specific - "commercial_1.2_foo" strings found in the whitelist, as - expected. - - - - Here are some other scenarios: - - - You can specify a versioned string in the recipe - such as "commercial_foo_1.2" in a "foo" recipe. - The build system expands this string to - "commercial_foo_1.2_foo". - Combine this license flag with a whitelist that has - the string "commercial" and you match the flag - along with any other flag that starts with the - string "commercial". - - - Under the same circumstances, you can use - "commercial_foo" in the whitelist and the build - system not only matches "commercial_foo_1.2" but - also matches any license flag with the string - "commercial_foo", regardless of the version. - - - You can be very specific and use both the - package and version parts in the whitelist (e.g. - "commercial_foo_1.2") to specifically match a - versioned recipe. - - - -
- - -
-
- - diff --git a/documentation/getting-started/getting-started-customization.xsl b/documentation/getting-started/getting-started-customization.xsl deleted file mode 100644 index 9733bf87b2..0000000000 --- a/documentation/getting-started/getting-started-customization.xsl +++ /dev/null @@ -1,27 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - diff --git a/documentation/getting-started/getting-started-development-environment.xml b/documentation/getting-started/getting-started-development-environment.xml deleted file mode 100644 index 7bcf87ffd9..0000000000 --- a/documentation/getting-started/getting-started-development-environment.xml +++ /dev/null @@ -1,972 +0,0 @@ - %poky; ] > - - -The Yocto Project Development Environment - - - This chapter takes a look at the Yocto Project development - environment. - The chapter provides Yocto Project Development environment concepts that - help you understand how work is accomplished in an open source environment, - which is very different as compared to work accomplished in a closed, - proprietary environment. - - - - Specifically, this chapter addresses open source philosophy, source - repositories, workflows, Git, and licensing. - - -
- Open Source Philosophy - - - Open source philosophy is characterized by software development - directed by peer production and collaboration through an active - community of developers. - Contrast this to the more standard centralized development models - used by commercial software companies where a finite set of developers - produces a product for sale using a defined set of procedures that - ultimately result in an end product whose architecture and source - material are closed to the public. - - - - Open source projects conceptually have differing concurrent agendas, - approaches, and production. - These facets of the development process can come from anyone in the - public (community) who has a stake in the software project. - The open source environment contains new copyright, licensing, domain, - and consumer issues that differ from the more traditional development - environment. - In an open source environment, the end product, source material, - and documentation are all available to the public at no cost. - - - - A benchmark example of an open source project is the Linux kernel, - which was initially conceived and created by Finnish computer science - student Linus Torvalds in 1991. - Conversely, a good example of a non-open source project is the - Windows family of operating - systems developed by - Microsoft Corporation. - - - - Wikipedia has a good historical description of the Open Source - Philosophy - here. - You can also find helpful information on how to participate in the - Linux Community - here. - -
- -
- The Development Host - - - A development host or build host is key to using the Yocto Project. - Because the goal of the Yocto Project is to develop images or - applications that run on embedded hardware, development of those - images and applications generally takes place on a system not - intended to run the software - the development host. - - - - You need to set up a development host in order to use it with the - Yocto Project. - Most find that it is best to have a native Linux machine function as - the development host. - However, it is possible to use a system that does not run Linux - as its operating system as your development host. - When you have a Mac or Windows-based system, you can set it up - as the development host by using - CROPS, - which leverages - Docker Containers. - Once you take the steps to set up a CROPS machine, you effectively - have access to a shell environment that is similar to what you see - when using a Linux-based development host. - For the steps needed to set up a system using CROPS, see the - "Setting Up to Use CROss PlatformS (CROPS)" - section in the Yocto Project Development Tasks Manual. - - - - If your development host is going to be a system that runs a Linux - distribution, steps still exist that you must take to prepare the - system for use with the Yocto Project. - You need to be sure that the Linux distribution on the system is - one that supports the Yocto Project. - You also need to be sure that the correct set of host packages are - installed that allow development using the Yocto Project. - For the steps needed to set up a development host that runs Linux, - see the - "Setting Up a Native Linux Host" - section in the Yocto Project Development Tasks Manual. - - - - Once your development host is set up to use the Yocto Project, - several methods exist for you to do work in the Yocto Project - environment: - - - Command Lines, BitBake, and Shells: - Traditional development in the Yocto Project involves using - OpenEmbedded build system, which uses BitBake, in a - command-line environment from a shell on your development - host. - You can accomplish this from a host that is a native Linux - machine or from a host that has been set up with CROPS. - Either way, you create, modify, and build images and - applications all within a shell-based environment using - components and tools available through your Linux distribution - and the Yocto Project. - - For a general flow of the build procedures, see the - "Building an Image" - section in the Yocto Project Development Tasks Manual. - - - Board Support Package (BSP) Development: - Development of BSPs involves using the Yocto Project to - create and test layers that allow easy development of - images and applications targeted for specific hardware. - To development BSPs, you need to take some additional steps - beyond what was described in setting up a development host. - - - The - Yocto Project Board Support Package (BSP) Developer's Guide' - provides BSP-related development information. - For specifics on development host preparation, see the - "Preparing Your Build Host to Work With BSP Layers" - section in the Yocto Project Board Support Package (BSP) - Developer's Guide. - - - Kernel Development: - If you are going to be developing kernels using the Yocto - Project you likely will be using devtool. - A workflow using devtool makes kernel - development quicker by reducing iteration cycle times. - - The - Yocto Project Linux Kernel Development Manual - provides kernel-related development information. - For specifics on development host preparation, see the - "Preparing the Build Host to Work on the Kernel" - section in the Yocto Project Linux Kernel Development Manual. - - - Using the Eclipse IDE: - One of two Yocto Project development methods that involves an - interface that effectively puts the Yocto Project into the - background is the popular Eclipse IDE. - This method of development is advantageous if you are already - familiar with working within Eclipse. - Development is supported through a plugin that you install - onto your development host. - - For steps that show you how to set up your development - host to use the Eclipse Yocto Project plugin, see the - "Developing Applications Using Eclipse" - Chapter in the Yocto Project Application Development and the - Extensible Software Development Kit (eSDK) manual. - - - Using the Toaster: - The other Yocto Project development method that involves an - interface that effectively puts the Yocto Project into the - background is Toaster. - Toaster provides an interface to the OpenEmbedded build system. - The interface enables you to configure and run your builds. - Information about builds is collected and stored in a database. - You can use Toaster to configure and start builds on multiple - remote build servers. - - For steps that show you how to set up your development - host to use Toaster and on how to use Toaster in general, - see the - Toaster User Manual. - - - -
- -
- Yocto Project Source Repositories - - - The Yocto Project team maintains complete source repositories for all - Yocto Project files at - . - This web-based source code browser is organized into categories by - function such as IDE Plugins, Matchbox, Poky, Yocto Linux Kernel, and - so forth. - From the interface, you can click on any particular item in the "Name" - column and see the URL at the bottom of the page that you need to clone - a Git repository for that particular item. - Having a local Git repository of the - Source Directory, - which is usually named "poky", allows - you to make changes, contribute to the history, and ultimately enhance - the Yocto Project's tools, Board Support Packages, and so forth. - - - - For any supported release of Yocto Project, you can also go to the - Yocto Project Website and - select the "Downloads" tab and get a released tarball of the - poky repository or any supported BSP tarballs. - Unpacking these tarballs gives you a snapshot of the released - files. - Notes - - - The recommended method for setting up the Yocto Project - Source Directory - and the files for supported BSPs - (e.g., meta-intel) is to use - Git to create a local copy of - the upstream repositories. - - - Be sure to always work in matching branches for both - the selected BSP repository and the - Source Directory - (i.e. poky) repository. - For example, if you have checked out the "master" branch - of poky and you are going to use - meta-intel, be sure to checkout the - "master" branch of meta-intel. - - - - - - - In summary, here is where you can get the project files needed for - development: - - - - Source Repositories: - - This area contains IDE Plugins, Matchbox, Poky, Poky Support, - Tools, Yocto Linux Kernel, and Yocto Metadata Layers. - You can create local copies of Git repositories for each of - these areas. - - - - For steps on how to view and access these upstream Git - repositories, see the - "Accessing Source Repositories" - Section in the Yocto Project Development Tasks Manual. - - - - Index of /releases: - - This is an index of releases such as - the Eclipse - Yocto Plug-in, miscellaneous support, Poky, Pseudo, installers - for cross-development toolchains, and all released versions of - Yocto Project in the form of images or tarballs. - Downloading and extracting these files does not produce a local - copy of the Git repository but rather a snapshot of a - particular release or image. - - - - For steps on how to view and access these files, see the - "Accessing Index of Releases" - section in the Yocto Project Development Tasks Manual. - - - "Downloads" page for the - Yocto Project Website: - - - The Yocto Project website includes a "DOWNLOADS" page - accessible through the "SOFTWARE" tab - that allows you to download any Yocto Project - release, tool, and Board Support Package (BSP) in tarball form. - The tarballs are similar to those found in the - Index of /releases: area. - - - - For steps on how to use the "DOWNLOADS" page, see the - "Using the Downloads Page" - section in the Yocto Project Development Tasks Manual. - - - -
- -
- Git Workflows and the Yocto Project - - - Developing using the Yocto Project likely requires the use of - Git. - Git is a free, open source distributed version control system - used as part of many collaborative design environments. - This section provides workflow concepts using the Yocto Project and - Git. - In particular, the information covers basic practices that describe - roles and actions in a collaborative development environment. - - If you are familiar with this type of development environment, you - might not want to read this section. - - - - - The Yocto Project files are maintained using Git in "branches" - whose Git histories track every change and whose structures - provide branches for all diverging functionality. - Although there is no need to use Git, many open source projects do so. - - - - For the Yocto Project, a key individual called the "maintainer" is - responsible for the integrity of the "master" branch of a given Git - repository. - The "master" branch is the “upstream” repository from which final or - most recent builds of a project occur. - The maintainer is responsible for accepting changes from other - developers and for organizing the underlying branch structure to - reflect release strategies and so forth. - - For information on finding out who is responsible for (maintains) - a particular area of code in the Yocto Project, see the - "Submitting a Change to the Yocto Project" - section of the Yocto Project Development Tasks Manual. - - - - - The Yocto Project poky Git repository also has an - upstream contribution Git repository named - poky-contrib. - You can see all the branches in this repository using the web interface - of the - Source Repositories organized - within the "Poky Support" area. - These branches hold changes (commits) to the project that have been - submitted or committed by the Yocto Project development team and by - community members who contribute to the project. - The maintainer determines if the changes are qualified to be moved - from the "contrib" branches into the "master" branch of the Git - repository. - - - - Developers (including contributing community members) create and - maintain cloned repositories of upstream branches. - The cloned repositories are local to their development platforms and - are used to develop changes. - When a developer is satisfied with a particular feature or change, - they "push" the change to the appropriate "contrib" repository. - - - - Developers are responsible for keeping their local repository - up-to-date with whatever upstream branch they are working against. - They are also responsible for straightening out any conflicts that - might arise within files that are being worked on simultaneously by - more than one person. - All this work is done locally on the development host before - anything is pushed to a "contrib" area and examined at the maintainer’s - level. - - - - A somewhat formal method exists by which developers commit changes - and push them into the "contrib" area and subsequently request that - the maintainer include them into an upstream branch. - This process is called “submitting a patch” or "submitting a change." - For information on submitting patches and changes, see the - "Submitting a Change to the Yocto Project" - section in the Yocto Project Development Tasks Manual. - - - - To summarize the development workflow: a single point of entry - exists for changes into a "master" or development branch of the - Git repository, which is controlled by the project’s maintainer. - And, a set of developers exist who independently develop, test, and - submit changes to "contrib" areas for the maintainer to examine. - The maintainer then chooses which changes are going to become a - permanent part of the project. - - - - - - - - While each development environment is unique, there are some best - practices or methods that help development run smoothly. - The following list describes some of these practices. - For more information about Git workflows, see the workflow topics in - the - Git Community Book. - - - Make Small Changes: - It is best to keep the changes you commit small as compared to - bundling many disparate changes into a single commit. - This practice not only keeps things manageable but also allows - the maintainer to more easily include or refuse changes. - - - Make Complete Changes: - It is also good practice to leave the repository in a - state that allows you to still successfully build your project. - In other words, do not commit half of a feature, - then add the other half as a separate, later commit. - Each commit should take you from one buildable project state - to another buildable state. - - - Use Branches Liberally: - It is very easy to create, use, and delete local branches in - your working Git repository on the development host. - You can name these branches anything you like. - It is helpful to give them names associated with the particular - feature or change on which you are working. - Once you are done with a feature or change and have merged it - into your local master branch, simply discard the temporary - branch. - - - Merge Changes: - The git merge command allows you to take - the changes from one branch and fold them into another branch. - This process is especially helpful when more than a single - developer might be working on different parts of the same - feature. - Merging changes also automatically identifies any collisions - or "conflicts" that might happen as a result of the same lines - of code being altered by two different developers. - - - Manage Branches: - Because branches are easy to use, you should use a system - where branches indicate varying levels of code readiness. - For example, you can have a "work" branch to develop in, a - "test" branch where the code or change is tested, a "stage" - branch where changes are ready to be committed, and so forth. - As your project develops, you can merge code across the - branches to reflect ever-increasing stable states of the - development. - - - Use Push and Pull: - The push-pull workflow is based on the concept of developers - "pushing" local commits to a remote repository, which is - usually a contribution repository. - This workflow is also based on developers "pulling" known - states of the project down into their local development - repositories. - The workflow easily allows you to pull changes submitted by - other developers from the upstream repository into your - work area ensuring that you have the most recent software - on which to develop. - The Yocto Project has two scripts named - create-pull-request and - send-pull-request that ship with the - release to facilitate this workflow. - You can find these scripts in the scripts - folder of the - Source Directory. - For information on how to use these scripts, see the - "Using Scripts to Push a Change Upstream and Request a Pull" - section in the Yocto Project Development Tasks Manual. - - - Patch Workflow: - This workflow allows you to notify the maintainer through an - email that you have a change (or patch) you would like - considered for the "master" branch of the Git repository. - To send this type of change, you format the patch and then - send the email using the Git commands - git format-patch and - git send-email. - For information on how to use these scripts, see the - "Submitting a Change to the Yocto Project" - section in the Yocto Project Development Tasks Manual. - - - -
- -
- Git - - - The Yocto Project makes extensive use of Git, which is a - free, open source distributed version control system. - Git supports distributed development, non-linear development, - and can handle large projects. - It is best that you have some fundamental understanding - of how Git tracks projects and how to work with Git if - you are going to use the Yocto Project for development. - This section provides a quick overview of how Git works and - provides you with a summary of some essential Git commands. - Notes - - - For more information on Git, see - . - - - If you need to download Git, it is recommended that you add - Git to your system through your distribution's "software - store" (e.g. for Ubuntu, use the Ubuntu Software feature). - For the Git download page, see - . - - - For information beyond the introductory nature in this - section, see the - "Working With Yocto Project Source Files" - section in the Yocto Project Development Tasks Manual. - - - - - -
- Repositories, Tags, and Branches - - - As mentioned briefly in the previous section and also in the - "Git Workflows and the Yocto Project" - section, the Yocto Project maintains source repositories at - . - If you look at this web-interface of the repositories, each item - is a separate Git repository. - - - - Git repositories use branching techniques that track content - change (not files) within a project (e.g. a new feature or updated - documentation). - Creating a tree-like structure based on project divergence allows - for excellent historical information over the life of a project. - This methodology also allows for an environment from which you can - do lots of local experimentation on projects as you develop - changes or new features. - - - - A Git repository represents all development efforts for a given - project. - For example, the Git repository poky contains - all changes and developments for that repository over the course - of its entire life. - That means that all changes that make up all releases are captured. - The repository maintains a complete history of changes. - - - - You can create a local copy of any repository by "cloning" it - with the git clone command. - When you clone a Git repository, you end up with an identical - copy of the repository on your development system. - Once you have a local copy of a repository, you can take steps to - develop locally. - For examples on how to clone Git repositories, see the - "Working With Yocto Project Source Files" - section in the Yocto Project Development Tasks Manual. - - - - It is important to understand that Git tracks content change and - not files. - Git uses "branches" to organize different development efforts. - For example, the poky repository has - several branches that include the current "&DISTRO_NAME_NO_CAP;" - branch, the "master" branch, and many branches for past - Yocto Project releases. - You can see all the branches by going to - and - clicking on the - [...] - link beneath the "Branch" heading. - - - - Each of these branches represents a specific area of development. - The "master" branch represents the current or most recent - development. - All other branches represent offshoots of the "master" branch. - - - - When you create a local copy of a Git repository, the copy has - the same set of branches as the original. - This means you can use Git to create a local working area - (also called a branch) that tracks a specific development branch - from the upstream source Git repository. - in other words, you can define your local Git environment to - work on any development branch in the repository. - To help illustrate, consider the following example Git commands: - - $ cd ~ - $ git clone git://git.yoctoproject.org/poky - $ cd poky - $ git checkout -b &DISTRO_NAME_NO_CAP; origin/&DISTRO_NAME_NO_CAP; - - In the previous example after moving to the home directory, the - git clone command creates a - local copy of the upstream poky Git repository. - By default, Git checks out the "master" branch for your work. - After changing the working directory to the new local repository - (i.e. poky), the - git checkout command creates - and checks out a local branch named "&DISTRO_NAME_NO_CAP;", which - tracks the upstream "origin/&DISTRO_NAME_NO_CAP;" branch. - Changes you make while in this branch would ultimately affect - the upstream "&DISTRO_NAME_NO_CAP;" branch of the - poky repository. - - - - It is important to understand that when you create and checkout a - local working branch based on a branch name, - your local environment matches the "tip" of that particular - development branch at the time you created your local branch, - which could be different from the files in the "master" branch - of the upstream repository. - In other words, creating and checking out a local branch based on - the "&DISTRO_NAME_NO_CAP;" branch name is not the same as - checking out the "master" branch in the repository. - Keep reading to see how you create a local snapshot of a Yocto - Project Release. - - - - Git uses "tags" to mark specific changes in a repository branch - structure. - Typically, a tag is used to mark a special point such as the final - change (or commit) before a project is released. - You can see the tags used with the poky Git - repository by going to - and - clicking on the - [...] - link beneath the "Tag" heading. - - - - Some key tags for the poky repository are - jethro-14.0.3, - morty-16.0.1, - pyro-17.0.0, and - &DISTRO_NAME_NO_CAP;-&POKYVERSION;. - These tags represent Yocto Project releases. - - - - When you create a local copy of the Git repository, you also - have access to all the tags in the upstream repository. - Similar to branches, you can create and checkout a local working - Git branch based on a tag name. - When you do this, you get a snapshot of the Git repository that - reflects the state of the files when the change was made associated - with that tag. - The most common use is to checkout a working branch that matches - a specific Yocto Project release. - Here is an example: - - $ cd ~ - $ git clone git://git.yoctoproject.org/poky - $ cd poky - $ git fetch --all --tags --prune - $ git checkout tags/pyro-17.0.0 -b my-pyro-17.0.0 - - In this example, the name of the top-level directory of your - local Yocto Project repository is poky. - After moving to the poky directory, the - git fetch command makes all the upstream - tags available locally in your repository. - Finally, the git checkout command - creates and checks out a branch named "my-pyro-17.0.0" that is - based on the upstream branch whose "HEAD" matches the - commit in the repository associated with the "pyro-17.0.0" tag. - The files in your repository now exactly match that particular - Yocto Project release as it is tagged in the upstream Git - repository. - It is important to understand that when you create and - checkout a local working branch based on a tag, your environment - matches a specific point in time and not the entire development - branch (i.e. from the "tip" of the branch backwards). - -
- -
- Basic Commands - - - Git has an extensive set of commands that lets you manage changes - and perform collaboration over the life of a project. - Conveniently though, you can manage with a small set of basic - operations and workflows once you understand the basic - philosophy behind Git. - You do not have to be an expert in Git to be functional. - A good place to look for instruction on a minimal set of Git - commands is - here. - - - - If you do not know much about Git, you should educate - yourself by visiting the links previously mentioned. - - - - The following list of Git commands briefly describes some basic - Git operations as a way to get started. - As with any set of commands, this list (in most cases) simply shows - the base command and omits the many arguments it supports. - See the Git documentation for complete descriptions and strategies - on how to use these commands: - - - git init: - Initializes an empty Git repository. - You cannot use Git commands unless you have a - .git repository. - - - git clone: - Creates a local clone of a Git repository that is on - equal footing with a fellow developer’s Git repository - or an upstream repository. - - - git add: - Locally stages updated file contents to the index that - Git uses to track changes. - You must stage all files that have changed before you - can commit them. - - - git commit: - Creates a local "commit" that documents the changes you - made. - Only changes that have been staged can be committed. - Commits are used for historical purposes, for determining - if a maintainer of a project will allow the change, - and for ultimately pushing the change from your local - Git repository into the project’s upstream repository. - - - git status: - Reports any modified files that possibly need to be - staged and gives you a status of where you stand regarding - local commits as compared to the upstream repository. - - - git checkout branch-name: - Changes your local working branch and in this form - assumes the local branch already exists. - This command is analogous to "cd". - - - git checkout –b working-branch upstream-branch: - Creates and checks out a working branch on your local - machine. - The local branch tracks the upstream branch. - You can use your local branch to isolate your work. - It is a good idea to use local branches when adding - specific features or changes. - Using isolated branches facilitates easy removal of - changes if they do not work out. - - git branch: - Displays the existing local branches associated with your - local repository. - The branch that you have currently checked out is noted - with an asterisk character. - - - git branch -D branch-name: - Deletes an existing local branch. - You need to be in a local branch other than the one you - are deleting in order to delete - branch-name. - - - git pull --rebase: - Retrieves information from an upstream Git repository - and places it in your local Git repository. - You use this command to make sure you are synchronized with - the repository from which you are basing changes - (.e.g. the "master" branch). - The "--rebase" option ensures that any local commits you - have in your branch are preserved at the top of your - local branch. - - - git push repo-name local-branch:upstream-branch: - Sends all your committed local changes to the upstream Git - repository that your local repository is tracking - (e.g. a contribution repository). - The maintainer of the project draws from these repositories - to merge changes (commits) into the appropriate branch - of project's upstream repository. - - - git merge: - Combines or adds changes from one - local branch of your repository with another branch. - When you create a local Git repository, the default branch - is named "master". - A typical workflow is to create a temporary branch that is - based off "master" that you would use for isolated work. - You would make your changes in that isolated branch, - stage and commit them locally, switch to the "master" - branch, and then use the git merge - command to apply the changes from your isolated branch - into the currently checked out branch (e.g. "master"). - After the merge is complete and if you are done with - working in that isolated branch, you can safely delete - the isolated branch. - - - git cherry-pick commits: - Choose and apply specific commits from one branch - into another branch. - There are times when you might not be able to merge - all the changes in one branch with - another but need to pick out certain ones. - - - gitk: - Provides a GUI view of the branches and changes in your - local Git repository. - This command is a good way to graphically see where things - have diverged in your local repository. - - You need to install the gitk - package on your development system to use this - command. - - - - git log: - Reports a history of your commits to the repository. - This report lists all commits regardless of whether you - have pushed them upstream or not. - - - git diff: - Displays line-by-line differences between a local - working file and the same file as understood by Git. - This command is useful to see what you have changed - in any given file. - - - -
-
- -
- Licensing - - - Because open source projects are open to the public, they have - different licensing structures in place. - License evolution for both Open Source and Free Software has an - interesting history. - If you are interested in this history, you can find basic information - here: - - - Open source license history - - - Free software license history - - - - - - In general, the Yocto Project is broadly licensed under the - Massachusetts Institute of Technology (MIT) License. - MIT licensing permits the reuse of software within proprietary - software as long as the license is distributed with that software. - MIT is also compatible with the GNU General Public License (GPL). - Patches to the Yocto Project follow the upstream licensing scheme. - You can find information on the MIT license - here. - You can find information on the GNU GPL - here. - - - - When you build an image using the Yocto Project, the build process - uses a known list of licenses to ensure compliance. - You can find this list in the - Source Directory - at meta/files/common-licenses. - Once the build completes, the list of all licenses found and used - during that build are kept in the - Build Directory - at tmp/deploy/licenses. - - - - If a module requires a license that is not in the base list, the - build process generates a warning during the build. - These tools make it easier for a developer to be certain of the - licenses with which their shipped products must comply. - However, even with these tools it is still up to the developer to - resolve potential licensing issues. - - - - The base list of licenses used by the build process is a combination - of the Software Package Data Exchange (SPDX) list and the Open - Source Initiative (OSI) projects. - SPDX Group is a working group of - the Linux Foundation that maintains a specification for a standard - format for communicating the components, licenses, and copyrights - associated with a software package. - OSI is a corporation - dedicated to the Open Source Definition and the effort for reviewing - and approving licenses that conform to the Open Source Definition - (OSD). - - - - You can find a list of the combined SPDX and OSI licenses that the - Yocto Project uses in the - meta/files/common-licenses directory in your - Source Directory. - - - - For information that can help you maintain compliance with various - open source licensing during the lifecycle of a product created using - the Yocto Project, see the - "Maintaining Open Source License Compliance During Your Product's Lifecycle" - section in the Yocto Project Development Tasks Manual. - -
- - diff --git a/documentation/getting-started/getting-started-eclipse-customization.xsl b/documentation/getting-started/getting-started-eclipse-customization.xsl deleted file mode 100644 index 17fff727f9..0000000000 --- a/documentation/getting-started/getting-started-eclipse-customization.xsl +++ /dev/null @@ -1,35 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/documentation/getting-started/getting-started-intro.xml b/documentation/getting-started/getting-started-intro.xml deleted file mode 100644 index dcda2ab6db..0000000000 --- a/documentation/getting-started/getting-started-intro.xml +++ /dev/null @@ -1,111 +0,0 @@ - %poky; ] > - - - -The Yocto Project Overview and Concepts Manual -
- Welcome - - - Welcome to the Yocto Project Overview and Concepts Manual! - This manual introduces the Yocto Project by providing concepts, - software overviews, best-known-methods (BKMs), and any other - high-level introductory information suitable for a new Yocto - Project user. - - - - The following list describes what you can get from this manual: - - - Introducing the Yocto Project: - This chapter provides an introduction to the Yocto - Project. - You will learn about features and challenges of the - Yocto Project, the layer model, components and tools, - development methods, the Poky reference distribution, - the OpenEmbedded build system workflow, and some basic - Yocto terms. - - - The Yocto Project Development Environment: - This chapter helps you get started understanding the - Yocto Project development environment. - You will learn about open source, development hosts, - Yocto Project source repositories, workflows using Git - and the Yocto Project, a Git primer, and information - about licensing. - - - - - - This manual does not give you the following: - - - Step-by-step Instructions for Development Tasks: - Instructional procedures reside in other manuals within - the Yocto Project documentation set. - For example, the - Yocto Project Development Tasks Manual - provides examples on how to perform various development - tasks. - As another example, the - Yocto Project Application Development and the Extensible Software Development Kit (eSDK) - manual contains detailed instructions on how to install an - SDK, which is used to develop applications for target - hardware. - - - Reference Material: - This type of material resides in an appropriate reference - manual. - For example, system variables are documented in the - Yocto Project Reference Manual. - As another example, the - Yocto Project Board Support Package (BSP) Developer's Guide - contains reference information on BSPs. - - - Detailed Public Information Not Specific to the - Yocto Project: - For example, exhaustive information on how to use the - Source Control Manager Git is better covered with Internet - searches and official Git Documentation than through the - Yocto Project documentation. - - - -
- -
- Other Information - - - Because this manual presents information for many different - topics, supplemental information is recommended for full - comprehension. - For additional introductory information on the Yocto Project, see - the Yocto Project Website. - If you want to build an image with no knowledge of Yocto Project - as a way of quickly testing it out, see the - Yocto Project Quick Build - document. - - - - For a comprehensive list of links and other documentation, see the - "Links and Related Documentation" - section in the Yocto Project Reference Manual. - For a paper showing how to set up and run a quick build using the - Yocto Project, see the - "My First Yocto Project Build" - paper. - -
- - diff --git a/documentation/getting-started/getting-started-style.css b/documentation/getting-started/getting-started-style.css deleted file mode 100644 index a03f7dc0c1..0000000000 --- a/documentation/getting-started/getting-started-style.css +++ /dev/null @@ -1,988 +0,0 @@ -/* - Generic XHTML / DocBook XHTML CSS Stylesheet. - - Browser wrangling and typographic design by - Oyvind Kolas / pippin@gimp.org - - Customised for Poky by - Matthew Allum / mallum@o-hand.com - - Thanks to: - Liam R. E. Quin - William Skaggs - Jakub Steiner - - Structure - --------- - - The stylesheet is divided into the following sections: - - Positioning - Margins, paddings, width, font-size, clearing. - Decorations - Borders, style - Colors - Colors - Graphics - Graphical backgrounds - Nasty IE tweaks - Workarounds needed to make it work in internet explorer, - currently makes the stylesheet non validating, but up until - this point it is validating. - Mozilla extensions - Transparency for footer - Rounded corners on boxes - -*/ - - - /*************** / - / Positioning / -/ ***************/ - -body { - font-family: Verdana, Sans, sans-serif; - - min-width: 640px; - width: 80%; - margin: 0em auto; - padding: 2em 5em 5em 5em; - color: #333; -} - -h1,h2,h3,h4,h5,h6,h7 { - font-family: Arial, Sans; - color: #00557D; - clear: both; -} - -h1 { - font-size: 2em; - text-align: left; - padding: 0em 0em 0em 0em; - margin: 2em 0em 0em 0em; -} - -h2.subtitle { - margin: 0.10em 0em 3.0em 0em; - padding: 0em 0em 0em 0em; - font-size: 1.8em; - padding-left: 20%; - font-weight: normal; - font-style: italic; -} - -h2 { - margin: 2em 0em 0.66em 0em; - padding: 0.5em 0em 0em 0em; - font-size: 1.5em; - font-weight: bold; -} - -h3.subtitle { - margin: 0em 0em 1em 0em; - padding: 0em 0em 0em 0em; - font-size: 142.14%; - text-align: right; -} - -h3 { - margin: 1em 0em 0.5em 0em; - padding: 1em 0em 0em 0em; - font-size: 140%; - font-weight: bold; -} - -h4 { - margin: 1em 0em 0.5em 0em; - padding: 1em 0em 0em 0em; - font-size: 120%; - font-weight: bold; -} - -h5 { - margin: 1em 0em 0.5em 0em; - padding: 1em 0em 0em 0em; - font-size: 110%; - font-weight: bold; -} - -h6 { - margin: 1em 0em 0em 0em; - padding: 1em 0em 0em 0em; - font-size: 110%; - font-weight: bold; -} - -.authorgroup { - background-color: transparent; - background-repeat: no-repeat; - padding-top: 256px; - background-image: url("figures/getting-started-title.png"); - background-position: left top; - margin-top: -256px; - padding-right: 50px; - margin-left: 0px; - text-align: right; - width: 740px; -} - -h3.author { - margin: 0em 0me 0em 0em; - padding: 0em 0em 0em 0em; - font-weight: normal; - font-size: 100%; - color: #333; - clear: both; -} - -.author tt.email { - font-size: 66%; -} - -.titlepage hr { - width: 0em; - clear: both; -} - -.revhistory { - padding-top: 2em; - clear: both; -} - -.toc, -.list-of-tables, -.list-of-examples, -.list-of-figures { - padding: 1.33em 0em 2.5em 0em; - color: #00557D; -} - -.toc p, -.list-of-tables p, -.list-of-figures p, -.list-of-examples p { - padding: 0em 0em 0em 0em; - padding: 0em 0em 0.3em; - margin: 1.5em 0em 0em 0em; -} - -.toc p b, -.list-of-tables p b, -.list-of-figures p b, -.list-of-examples p b{ - font-size: 100.0%; - font-weight: bold; -} - -.toc dl, -.list-of-tables dl, -.list-of-figures dl, -.list-of-examples dl { - margin: 0em 0em 0.5em 0em; - padding: 0em 0em 0em 0em; -} - -.toc dt { - margin: 0em 0em 0em 0em; - padding: 0em 0em 0em 0em; -} - -.toc dd { - margin: 0em 0em 0em 2.6em; - padding: 0em 0em 0em 0em; -} - -div.glossary dl, -div.variablelist dl { -} - -.glossary dl dt, -.variablelist dl dt, -.variablelist dl dt span.term { - font-weight: normal; - width: 20em; - text-align: right; -} - -.variablelist dl dt { - margin-top: 0.5em; -} - -.glossary dl dd, -.variablelist dl dd { - margin-top: -1em; - margin-left: 25.5em; -} - -.glossary dd p, -.variablelist dd p { - margin-top: 0em; - margin-bottom: 1em; -} - - -div.calloutlist table td { - padding: 0em 0em 0em 0em; - margin: 0em 0em 0em 0em; -} - -div.calloutlist table td p { - margin-top: 0em; - margin-bottom: 1em; -} - -div p.copyright { - text-align: left; -} - -div.legalnotice p.legalnotice-title { - margin-bottom: 0em; -} - -p { - line-height: 1.5em; - margin-top: 0em; - -} - -dl { - padding-top: 0em; -} - -hr { - border: solid 1px; -} - - -.mediaobject, -.mediaobjectco { - text-align: center; -} - -img { - border: none; -} - -ul { - padding: 0em 0em 0em 1.5em; -} - -ul li { - padding: 0em 0em 0em 0em; -} - -ul li p { - text-align: left; -} - -table { - width :100%; -} - -th { - padding: 0.25em; - text-align: left; - font-weight: normal; - vertical-align: top; -} - -td { - padding: 0.25em; - vertical-align: top; -} - -p a[id] { - margin: 0px; - padding: 0px; - display: inline; - background-image: none; -} - -a { - text-decoration: underline; - color: #444; -} - -pre { - overflow: auto; -} - -a:hover { - text-decoration: underline; - /*font-weight: bold;*/ -} - -/* This style defines how the permalink character - appears by itself and when hovered over with - the mouse. */ - -[alt='Permalink'] { color: #eee; } -[alt='Permalink']:hover { color: black; } - - -div.informalfigure, -div.informalexample, -div.informaltable, -div.figure, -div.table, -div.example { - margin: 1em 0em; - padding: 1em; - page-break-inside: avoid; -} - - -div.informalfigure p.title b, -div.informalexample p.title b, -div.informaltable p.title b, -div.figure p.title b, -div.example p.title b, -div.table p.title b{ - padding-top: 0em; - margin-top: 0em; - font-size: 100%; - font-weight: normal; -} - -.mediaobject .caption, -.mediaobject .caption p { - text-align: center; - font-size: 80%; - padding-top: 0.5em; - padding-bottom: 0.5em; -} - -.epigraph { - padding-left: 55%; - margin-bottom: 1em; -} - -.epigraph p { - text-align: left; -} - -.epigraph .quote { - font-style: italic; -} -.epigraph .attribution { - font-style: normal; - text-align: right; -} - -span.application { - font-style: italic; -} - -.programlisting { - font-family: monospace; - font-size: 80%; - white-space: pre; - margin: 1.33em 0em; - padding: 1.33em; -} - -.tip, -.warning, -.caution, -.note { - margin-top: 1em; - margin-bottom: 1em; - -} - -/* force full width of table within div */ -.tip table, -.warning table, -.caution table, -.note table { - border: none; - width: 100%; -} - - -.tip table th, -.warning table th, -.caution table th, -.note table th { - padding: 0.8em 0.0em 0.0em 0.0em; - margin : 0em 0em 0em 0em; -} - -.tip p, -.warning p, -.caution p, -.note p { - margin-top: 0.5em; - margin-bottom: 0.5em; - padding-right: 1em; - text-align: left; -} - -.acronym { - text-transform: uppercase; -} - -b.keycap, -.keycap { - padding: 0.09em 0.3em; - margin: 0em; -} - -.itemizedlist li { - clear: none; -} - -.filename { - font-size: medium; - font-family: Courier, monospace; -} - - -div.navheader, div.heading{ - position: absolute; - left: 0em; - top: 0em; - width: 100%; - background-color: #cdf; - width: 100%; -} - -div.navfooter, div.footing{ - position: fixed; - left: 0em; - bottom: 0em; - background-color: #eee; - width: 100%; -} - - -div.navheader td, -div.navfooter td { - font-size: 66%; -} - -div.navheader table th { - /*font-family: Georgia, Times, serif;*/ - /*font-size: x-large;*/ - font-size: 80%; -} - -div.navheader table { - border-left: 0em; - border-right: 0em; - border-top: 0em; - width: 100%; -} - -div.navfooter table { - border-left: 0em; - border-right: 0em; - border-bottom: 0em; - width: 100%; -} - -div.navheader table td a, -div.navfooter table td a { - color: #777; - text-decoration: none; -} - -/* normal text in the footer */ -div.navfooter table td { - color: black; -} - -div.navheader table td a:visited, -div.navfooter table td a:visited { - color: #444; -} - - -/* links in header and footer */ -div.navheader table td a:hover, -div.navfooter table td a:hover { - text-decoration: underline; - background-color: transparent; - color: #33a; -} - -div.navheader hr, -div.navfooter hr { - display: none; -} - - -.qandaset tr.question td p { - margin: 0em 0em 1em 0em; - padding: 0em 0em 0em 0em; -} - -.qandaset tr.answer td p { - margin: 0em 0em 1em 0em; - padding: 0em 0em 0em 0em; -} -.answer td { - padding-bottom: 1.5em; -} - -.emphasis { - font-weight: bold; -} - - - /************* / - / decorations / -/ *************/ - -.titlepage { -} - -.part .title { -} - -.subtitle { - border: none; -} - -/* -h1 { - border: none; -} - -h2 { - border-top: solid 0.2em; - border-bottom: solid 0.06em; -} - -h3 { - border-top: 0em; - border-bottom: solid 0.06em; -} - -h4 { - border: 0em; - border-bottom: solid 0.06em; -} - -h5 { - border: 0em; -} -*/ - -.programlisting { - border: solid 1px; -} - -div.figure, -div.table, -div.informalfigure, -div.informaltable, -div.informalexample, -div.example { - border: 1px solid; -} - - - -.tip, -.warning, -.caution, -.note { - border: 1px solid; -} - -.tip table th, -.warning table th, -.caution table th, -.note table th { - border-bottom: 1px solid; -} - -.question td { - border-top: 1px solid black; -} - -.answer { -} - - -b.keycap, -.keycap { - border: 1px solid; -} - - -div.navheader, div.heading{ - border-bottom: 1px solid; -} - - -div.navfooter, div.footing{ - border-top: 1px solid; -} - - /********* / - / colors / -/ *********/ - -body { - color: #333; - background: white; -} - -a { - background: transparent; -} - -a:hover { - background-color: #dedede; -} - - -h1, -h2, -h3, -h4, -h5, -h6, -h7, -h8 { - background-color: transparent; -} - -hr { - border-color: #aaa; -} - - -.tip, .warning, .caution, .note { - border-color: #fff; -} - - -.tip table th, -.warning table th, -.caution table th, -.note table th { - border-bottom-color: #fff; -} - - -.warning { - background-color: #f0f0f2; -} - -.caution { - background-color: #f0f0f2; -} - -.tip { - background-color: #f0f0f2; -} - -.note { - background-color: #f0f0f2; -} - -.glossary dl dt, -.variablelist dl dt, -.variablelist dl dt span.term { - color: #044; -} - -div.figure, -div.table, -div.example, -div.informalfigure, -div.informaltable, -div.informalexample { - border-color: #aaa; -} - -pre.programlisting { - color: black; - background-color: #fff; - border-color: #aaa; - border-width: 2px; -} - -.guimenu, -.guilabel, -.guimenuitem { - background-color: #eee; -} - - -b.keycap, -.keycap { - background-color: #eee; - border-color: #999; -} - - -div.navheader { - border-color: black; -} - - -div.navfooter { - border-color: black; -} - -.writernotes { - color: red; -} - - - /*********** / - / graphics / -/ ***********/ - -/* -body { - background-image: url("images/body_bg.jpg"); - background-attachment: fixed; -} - -.navheader, -.note, -.tip { - background-image: url("images/note_bg.jpg"); - background-attachment: fixed; -} - -.warning, -.caution { - background-image: url("images/warning_bg.jpg"); - background-attachment: fixed; -} - -.figure, -.informalfigure, -.example, -.informalexample, -.table, -.informaltable { - background-image: url("images/figure_bg.jpg"); - background-attachment: fixed; -} - -*/ -h1, -h2, -h3, -h4, -h5, -h6, -h7{ -} - -/* -Example of how to stick an image as part of the title. - -div.article .titlepage .title -{ - background-image: url("figures/white-on-black.png"); - background-position: center; - background-repeat: repeat-x; -} -*/ - -div.preface .titlepage .title, -div.colophon .title, -div.chapter .titlepage .title, -div.article .titlepage .title -{ -} - -div.section div.section .titlepage .title, -div.sect2 .titlepage .title { - background: none; -} - - -h1.title { - background-color: transparent; - background-repeat: no-repeat; - height: 256px; - text-indent: -9000px; - overflow:hidden; -} - -h2.subtitle { - background-color: transparent; - text-indent: -9000px; - overflow:hidden; - width: 0px; - display: none; -} - - /*************************************** / - / pippin.gimp.org specific alterations / -/ ***************************************/ - -/* -div.heading, div.navheader { - color: #777; - font-size: 80%; - padding: 0; - margin: 0; - text-align: left; - position: absolute; - top: 0px; - left: 0px; - width: 100%; - height: 50px; - background: url('/gfx/heading_bg.png') transparent; - background-repeat: repeat-x; - background-attachment: fixed; - border: none; -} - -div.heading a { - color: #444; -} - -div.footing, div.navfooter { - border: none; - color: #ddd; - font-size: 80%; - text-align:right; - - width: 100%; - padding-top: 10px; - position: absolute; - bottom: 0px; - left: 0px; - - background: url('/gfx/footing_bg.png') transparent; -} -*/ - - - - /****************** / - / nasty ie tweaks / -/ ******************/ - -/* -div.heading, div.navheader { - width:expression(document.body.clientWidth + "px"); -} - -div.footing, div.navfooter { - width:expression(document.body.clientWidth + "px"); - margin-left:expression("-5em"); -} -body { - padding:expression("4em 5em 0em 5em"); -} -*/ - - /**************************************** / - / mozilla vendor specific css extensions / -/ ****************************************/ -/* -div.navfooter, div.footing{ - -moz-opacity: 0.8em; -} - -div.figure, -div.table, -div.informalfigure, -div.informaltable, -div.informalexample, -div.example, -.tip, -.warning, -.caution, -.note { - -moz-border-radius: 0.5em; -} - -b.keycap, -.keycap { - -moz-border-radius: 0.3em; -} -*/ - -table tr td table tr td { - display: none; -} - - -hr { - display: none; -} - -table { - border: 0em; -} - - .photo { - float: right; - margin-left: 1.5em; - margin-bottom: 1.5em; - margin-top: 0em; - max-width: 17em; - border: 1px solid gray; - padding: 3px; - background: white; -} - .seperator { - padding-top: 2em; - clear: both; - } - - #validators { - margin-top: 5em; - text-align: right; - color: #777; - } - @media print { - body { - font-size: 8pt; - } - .noprint { - display: none; - } - } - - -.tip, -.note { - background: #f0f0f2; - color: #333; - padding: 20px; - margin: 20px; -} - -.tip h3, -.note h3 { - padding: 0em; - margin: 0em; - font-size: 2em; - font-weight: bold; - color: #333; -} - -.tip a, -.note a { - color: #333; - text-decoration: underline; -} - -.footnote { - font-size: small; - color: #333; -} - -/* Changes the announcement text */ -.tip h3, -.warning h3, -.caution h3, -.note h3 { - font-size:large; - color: #00557D; -} diff --git a/documentation/getting-started/getting-started-yp-intro.xml b/documentation/getting-started/getting-started-yp-intro.xml deleted file mode 100644 index 437635842a..0000000000 --- a/documentation/getting-started/getting-started-yp-intro.xml +++ /dev/null @@ -1,1335 +0,0 @@ - %poky; ] > - - - Introducing the Yocto Project - -
- What is the Yocto Project? - - - The Yocto Project is an open source collaboration project - that helps developers create custom Linux-based systems that are - designed for embedded products regardless of the product's hardware - architecture. - Yocto Project provides a flexible toolset and a development - environment that allows embedded device developers across the - world to collaborate through shared technologies, software stacks, - configurations, and best practices used to create these tailored - Linux images. - - - - Thousands of developers worldwide have discovered that Yocto - Project provides advantages in both systems and applications - development, archival and management benefits, and customizations - used for speed, footprint, and memory utilization. - The project is a standard when it comes to delivering hardware - support and software stacks, allowing software configuration - and build interchange, and build and support customizations for - multiple hardware platforms and software stacks that can be - maintained and scaled. - - - - - - - - For further introductory information on the Yocto Project, you - might be interested in this - article - by Drew Moseley and in this short introductory - video. - - - - The remainder of this section overviews advantages and challenges - tied to the Yocto Project. - - -
- Features - - - The following list describes features and advantages of the - Yocto Project: - - - Widely Adopted Across the Industry: - Semiconductor, operating system, software, and - service vendors exist whose products and services - adopt and support the Yocto Project. - For a look at the companies involved with the Yocto - Project, see the membership, associate, and - participant pages on the Yocto Project home page. - - - Architecture Agnostic: - Yocto Project supports Intel, ARM, MIPS, AMD, PPC - and other architectures. - Most ODMs, OSVs, and chip vendors create and supply - BSPs that support their hardware. - If you have custom silicon, you can create a BSP - that supports that architecture. - - Aside from lots of architecture support, the - Yocto Project fully supports a wide range of device - emulation through the Quick EMUlator (QEMU). - - - Images and Code Transfer Easily: - Yocto Project output can easily move between - architectures without moving to new development - environments. - Additionally, if you have used the Yocto Project to - create an image or application and you find yourself - not able to support it, commercial Linux vendors such - as Wind River, Mentor Graphics, Timesys, and ENEA could - take it and provide ongoing support. - These vendors have offerings that are built using - the Yocto Project. - - - Flexibility: - Corporations use the Yocto Project many different ways. - One example is to create an internal Linux distribution - as a code base the corporation can use across multiple - product groups. - Through customization and layering, a project group - can leverage the base Linux distribution to create - a distribution that works for their product needs. - - - Ideal for Constrained Embedded and IoT devices: - Unlike a full Linux distribution, you can use the - Yocto Project to create exactly what you need for - embedded devices. - You only add the feature support or packages that you - absolutely need for the device. - For devices that have display hardware, you can use - available system components such as X11, GTK+, Qt, - Clutter, and SDL (among others) to create a rich user - experience. - For devices that do not have a display or where you - want to use alternative UI frameworks, you can choose - to not install these components. - - - Comprehensive Toolchain Capabilities: - Toolchains for supported architectures satisfy most - use cases. - However, if your hardware supports features that are - not part of a standard toolchain, you can easily - customize that toolchain through specification of - platform-specific tuning parameters. - And, should you need to use a third-party toolchain, - mechanisms built into the Yocto Project allow for that. - - - Mechanism Rules Over Policy: - Focusing on mechanism rather than policy ensures that - you are free to set policies based on the needs of your - design instead of adopting decisions enforced by some - system software provider. - - - Uses a Layer Model: - The Yocto Project layer infrastructure groups related - functionality into separate bundles. - You can incrementally add these grouped functionalities - to your project as needed. - Using layers to isolate and group functionality - reduces project complexity and redundancy, allows you - to easily extend the system, make customizations, - and keep functionality organized. - - - Supports Partial Builds: - You can build and rebuild individual packages as - needed. - Yocto Project accomplishes this through its - shared-state cache (sstate) scheme. - Being able to build and debug components individually - eases project development. - - - Releases According to a Strict Schedule: - Major releases occur on a six-month cycle predictably - in October and April. - The most recent two releases support point releases - to address common vulnerabilities and exposures. - This predictability is crucial for projects based on - the Yocto Project and allows development teams to - plan activities. - - - Rich Ecosystem of Individuals and Organizations: - For open source projects, the value of community is - very important. - Support forums, expertise, and active developers who - continue to push the Yocto Project forward are readily - available. - - - Binary Reproducibility: - The Yocto Project allows you to be very specific about - dependencies and achieves very high percentages of - binary reproducibility (e.g. 99.8% for - core-image-minimal). - When distributions are not specific about which - packages are pulled in and in what order to support - dependencies, other build systems can arbitrarily - include packages. - - - License Manifest: - The Yocto Project provides a license manifest for - review by people who need to track the use of open - source licenses (e.g.legal teams). - - - -
- -
- Challenges - - - The following list presents challenges you might encounter - when developing using the Yocto Project: - - - Steep Learning Curve: - The Yocto Project has a steep learning curve and has - many different ways to accomplish similar tasks. - It can be difficult to choose how to proceed when - varying methods exist by which to accomplish a given - task. - - - Understanding What Changes You Need to Make - For Your Design Requires Some Research: - Beyond the simple tutorial stage, understanding what - changes need to be made for your particular design - can require a significant amount of research and - investigation. - For information that helps you transition from - trying out the Yocto Project to using it for your - project, see the "What I wish I'd Known" and - "Transitioning to a Custom Environment for Systems - Development" documents on the Yocto Project website. - - - Project Workflow Could Be Confusing: - The Yocto Project workflow could be confusing if you - are used to traditional desktop and server software - development. - In a desktop development environment, mechanisms exist - to easily pull and install new packages, which are - typically pre-compiled binaries from servers accessible - over the Internet. - Using the Yocto Project, you must modify your - configuration and rebuild to add additional packages. - - - Working in a Cross-Build Environment Can - Feel Unfamiliar: - When developing code to run on a target, compilation, - execution, and testing done on the actual target - can be faster than running a BitBake build on a - development host and then deploying binaries to the - target for test. - While the Yocto Project does support development tools - on the target, the additional step of integrating your - changes back into the Yocto Project build environment - would be required. - Yocto Project supports an intermediate approach that - involves making changes on the development system - within the BitBake environment and then deploying only - the updated packages to the target. - - The Yocto Project OpenEmbedded build system - produces packages in standard formats (i.e. RPM, - DEB, IPK, and TAR). - You can deploy these packages into the running system - on the target by using utilities on the target such - as rpm or - ipk. - - - Initial Build Times Can be Significant: - Long initial build times are unfortunately unavoidable - due to the large number of packages initially built - from scratch for a fully functioning Linux system. - Once that initial build is completed, however, the - shared-state (sstate) cache mechanism Yocto Project - uses keeps the system from rebuilding packages that - have not been "touched" since the last build. - The sstate mechanism significantly reduces times - for successive builds. - - - -
-
- -
- The Yocto Project Layer Model - - - The Yocto Project's "Layer Model" is a development model for - embedded and IoT Linux creation that distinguishes the - Yocto Project from other simple build systems. - The Layer Model simultaneously supports collaboration and - customization. - Layers are repositories that contain related sets of instructions - that tell the OpenEmbedded build system what to do. - You can collaborate, share, and reuse layers. - - - - Layers can contain changes to previous instructions or settings - at any time. - This powerful override capability is what allows you to customize - previously supplied collaborative or community layers to suit your - product requirements. - - - - You use different layers to logically separate information in your - build. - As an example, you could have BSP, GUI, distro configuration, - middleware, or application layers. - Putting your entire build into one layer limits and complicates - future customization and reuse. - Isolating information into layers, on the other hand, helps - simplify future customizations and reuse. - You might find it tempting to keep everything in one layer when - working on a single project. - However, the more modular your Metadata, the easier - it is to cope with future changes. - Notes - - - Use Board Support Package (BSP) layers from silicon - vendors when possible. - - - Familiarize yourself with the - Yocto Project curated layer index - or the - OpenEmbedded layer index. - The latter contains more layers but they are less - universally validated. - - - Layers support the inclusion of technologies, hardware - components, and software components. - The Yocto Project Compatible designation provides a - minimum level of standardization that contributes to a - strong ecosystem. - "YP Compatible" is applied to appropriate products and - software components such as BSPs, other OE-compatible - layers, and related open-source projects, allowing the - producer to use Yocto Project badges and branding - assets. - - - - - - - To illustrate how layers are used to keep things modular, consider - machine customizations. - These types of customizations typically reside in a special layer, - rather than a general layer, called a BSP Layer. - Furthermore, the machine customizations should be isolated from - recipes and Metadata that support a new GUI environment, - for example. - This situation gives you a couple of layers: one for the machine - configurations, and one for the GUI environment. - It is important to understand, however, that the BSP layer can - still make machine-specific additions to recipes within the GUI - environment layer without polluting the GUI layer itself - with those machine-specific changes. - You can accomplish this through a recipe that is a BitBake append - (.bbappend) file, which is described later - in this section. - - For general information on BSP layer structure, see the - Board Support Packages (BSP) - Developer's Guide. - - - - - The - Source Directory - contains both general layers and BSP layers right out of the box. - You can easily identify layers that ship with a Yocto Project - release in the Source Directory by their names. - Layers typically have names that begin with the string - meta-. - - It is not a requirement that a layer name begin with the - prefix meta-, but it is a commonly - accepted standard in the Yocto Project community. - - For example, if you were to examine the - tree view - of the poky repository, you will see several - layers: meta, - meta-skeleton, - meta-selftest, - meta-poky, and - meta-yocto-bsp. - Each of these repositories represents a distinct layer. - - - - For procedures on how to create layers, see the - "Understanding and Creating Layers" - section in the Yocto Project Development Tasks Manual. - -
- -
- Components and Tools - - - The Yocto Project employs a collection of components and - tools used by the project itself, by project developers, - and by those using the Yocto Project. - These components and tools are open source projects and - metadata that are separate from the reference distribution - (Poky) and the OpenEmbedded build system. - Most of the components and tools are downloaded separately. - - - - This section provides brief overviews of the components and - tools associated with the Yocto Project. - - -
- Development Tools - - - The following list consists of tools that help you develop - images and applications using the Yocto Project: - - - CROPS: - CROPS - is an open source, cross-platform development framework - that leverages - Docker Containers. - CROPS provides an easily managed, extensible environment - that allows you to build binaries for a variety of - architectures on Windows, Linux and Mac OS X hosts. - - - devtool: - This command-line tool is available as part of the - extensible SDK (eSDK) and is its cornerstone. - You can use devtool to help build, - test, and package software within the eSDK. - You can use the tool to optionally integrate what you - build into an image built by the OpenEmbedded build - system. - - The devtool command employs - a number of sub-commands that allow you to add, modify, - and upgrade recipes. - As with the OpenEmbedded build system, “recipes” - represent software packages within - devtool. - When you use devtool add, a recipe - is automatically created. - When you use devtool modify, the - specified existing recipe is used in order to determine - where to get the source code and how to patch it. - In both cases, an environment is set up so that when - you build the recipe a source tree that is under your - control is used in order to allow you to make changes - to the source as desired. - By default, both new recipes and the source go into - a “workspace” directory under the eSDK. - The devtool upgrade command - updates an existing recipe so that you can build it - for an updated set of source files. - - You can read about the - devtool workflow in the Yocto - Project Application Development and Extensible - Software Development Kit (eSDK) Manual in the - "Using devtool in Your SDK Workflow'" - section. - - - Extensible Software Development Kit (eSDK): - The eSDK provides a cross-development toolchain and - libraries tailored to the contents of a specific image. - The eSDK makes it easy to add new applications and - libraries to an image, modify the source for an - existing component, test changes on the target - hardware, and integrate into the rest of the - OpenEmbedded build system. - The eSDK gives you a toolchain experience supplemented - with the powerful set of devtool - commands tailored for the Yocto Project environment. - - - For information on the eSDK, see the - Yocto Project Application Development and Extensible Software Development Kit (eSDK) Manual. - - - Eclipse IDE Plug-in: - This plug-in enables you to use the popular Eclipse - Integrated Development Environment (IDE), which allows - for development using the Yocto Project all within the - Eclipse IDE. - You can work within Eclipse to cross-compile, deploy, - and execute your output into a QEMU emulation session - as well as onto actual target hardware. - - The environment also supports performance - enhancing tools that allow you to perform remote - profiling, tracing, collection of power data, - collection of latency data, and collection of - performance data. - - Once you enable the plug-in, standard Eclipse - functions automatically use the cross-toolchain - and target system libraries. - You can build applications using any of these - libraries. - - For more information on the Eclipse plug-in, - see the - "Working Within Eclipse" - section in the Yocto Project Application Development - and the Extensible Software Development Kit (eSDK) - manual. - - - Toaster: - Toaster is a web interface to the Yocto Project - OpenEmbedded build system. - Toaster allows you to configure, run, and view - information about builds. - - - -
- -
- Production Tools - - - The following list consists of tools that help production - related activities using the Yocto Project: - - - Auto Upgrade Helper: - This utility when used in conjunction with the - OpenEmbedded build system (BitBake and OE-Core) - automatically generates upgrades for recipes that - are based on new versions of the recipes published - upstream. - - - Recipe Reporting System: - The Recipe Reporting System tracks recipe versions - available for Yocto Project. - The main purpose of the system is to help you - manage the recipes you maintain and to offer a dynamic - overview of the project. - The Recipe Reporting System is built on top - the of OpenEmbedded Metadata Index, which is a website - that indexes layers for the OpenEmbedded build system. - - - Patchwork: - Patchwork - is a fork of a project originally started by - OzLabs. - The project is a web-based tracking system designed - to streamline the process of bringing contributions - into a project. - The Yocto Project uses Patchwork as an organizational - tool to handle patches, which number in the thousands - for every release. - - - AutoBuilder: - AutoBuilder is a project that automates build tests - and quality assurance (QA). - By using the public AutoBuilder, anyone can determine - the status of the current "master" branch of Poky. - - - A goal of the Yocto Project is to lead the - open source industry with a project that automates - testing and QA procedures. - In doing so, the project encourages a development - community that publishes QA and test plans, publicly - demonstrates QA and test plans, and encourages - development of tools that automate and test and QA - procedures for the benefit of the development - community. - - You can learn more about the AutoBuilder used - by the Yocto Project - here. - - - Cross-Prelink: - Prelinking is the process of pre-computing the load - addresses and link tables generated by the dynamic - linker as compared to doing this at runtime. - Doing this ahead of time results in performance - improvements when the application is launched and - reduced memory usage for libraries shared by many - applications. - - Historically, cross-prelink is a variant of - prelink, which was conceived by - Jakub Jelínek - a number of years ago. - Both prelink and cross-prelink are maintained in the - same repository albeit on separate branches. - By providing an emulated runtime dynamic linker - (i.e. glibc-derived - ld.so emulation), the - cross-prelink project extends the prelink software’s - ability to prelink a sysroot environment. - Additionally, the cross-prelink software enables the - ability to work in sysroot style environments. - - The dynamic linker determines standard load - address calculations based on a variety of factors - such as mapping addresses, library usage, and library - function conflicts. - The prelink tool uses this information, from the - dynamic linker, to determine unique load addresses - for executable and linkable format (ELF) binaries - that are shared libraries and dynamically linked. - The prelink tool modifies these ELF binaries with the - pre-computed information. - The result is faster loading and often lower memory - consumption because more of the library code can - be re-used from shared Copy-On-Write (COW) pages. - - - The original upstream prelink project only - supports running prelink on the end target device - due to the reliance on the target device’s dynamic - linker. - This restriction causes issues when developing a - cross-compiled system. - The cross-prelink adds a synthesized dynamic loader - that runs on the host, thus permitting cross-prelinking - without ever having to run on a read-write target - filesystem. - - - Pseudo: - Pseudo is the Yocto Project implementation of - fakeroot, - which is used to run commands in an environment - that seemingly has root privileges. - - During a build, it can be necessary to perform - operations that require system administrator - privileges. - For example, file ownership or permissions might need - definition. - Pseudo is a tool that you can either use directly or - through the environment variable - LD_PRELOAD. - Either method allows these operations to succeed as - if system administrator privileges exist even - when they do not. - - You can read more about Pseudo in the - "Fakeroot and Pseudo" - section of the Yocto Project Overview and Concepts - Manual. - - - -
- -
- Open-Embedded Build System Components - - - The following list consists of components associated with the - Open-Embedded build system: - - - BitBake: - BitBake is a core component of the Yocto Project and is - used by the OpenEmbedded build system to build images. - While BitBake is key to the build system, BitBake - is maintained separately from the Yocto Project. - - BitBake is a generic task execution engine that - allows shell and Python tasks to be run efficiently - and in parallel while working within complex inter-task - dependency constraints. - In short, BitBake is a build engine that works - through recipes written in a specific format in order - to perform sets of tasks. - - You can learn more about BitBake in the - BitBake User Manual. - - - OpenEmbedded-Core: - OpenEmbedded-Core (OE-Core) is a common layer of - metadata (i.e. recipes, classes, and associated files) - used by OpenEmbedded-derived systems, which includes - the Yocto Project. - The Yocto Project and the OpenEmbedded Project both - maintain the OpenEmbedded-Core. - You can find the OE-Core metadata in the Yocto - Project - Source Repositories - here. - - - Historically, the Yocto Project integrated the - OE-Core metadata throughout the Yocto Project - source repository reference system (Poky). - After Yocto Project Version 1.0, the Yocto Project - and OpenEmbedded agreed to work together and share a - common core set of metadata (OE-Core), which contained - much of the functionality previously found in Poky. - This collaboration achieved a long-standing - OpenEmbedded objective for having a more tightly - controlled and quality-assured core. - The results also fit well with the Yocto Project - objective of achieving a smaller number of fully - featured tools as compared to many different ones. - - - Sharing a core set of metadata results in Poky - as an integration layer on top of OE-Core. - You can see that in this - figure. - The Yocto Project combines various components such as - BitBake, OE-Core, script “glue”, and documentation - for its build system. - - - -
- -
- Reference Distribution (Poky) - - - Poky is the Yocto Project reference distribution. - It contains the OpenEmbedded build system (BitBake and OE-Core) - as well as a set of metadata to get you started building your - own distribution. - See the - figure in - "What is the Yocto Project?" section for an illustration - that shows Poky and its relationship with other parts of the - Yocto Project. - - To use the Yocto Project tools and components, you - can download (clone) Poky and use it - to bootstrap your own distribution. - - Poky does not contain binary files. - It is a working example of how to build your own custom - Linux distribution from source. - - You can read more about Poky in the - "Reference Embedded Distribution (Poky)" - section. - -
- -
- Packages for Finished Targets - - - The following lists components associated with packages - for finished targets: - - - Matchbox: - Matchbox is an Open Source, base environment for the - X Window System running on non-desktop, embedded - platforms such as handhelds, set-top boxes, kiosks, - and anything else for which screen space, input - mechanisms, or system resources are limited. - - Matchbox consists of a number of interchangeable - and optional applications that you can tailor to a - specific, non-desktop platform to enhance usability - in constrained environments. - - You can find the Matchbox source in its - repository - listed in the Yocto Project - Source Repositories. - - - Opkg - Open PacKaGe management (opkg) is a lightweight - package management system based on the itsy package - (ipkg) management system. - Opkg is written in C and resembles Advanced Package - Tool (APT) and Debian Package (dpkg) in operation. - - - Opkg is intended for use on embedded Linux - devices and is used in this capacity in the - OpenEmbedded - and - OpenWrt - projects, as well as the Yocto Project. - - As best it can, opkg maintains backwards - compatibility with ipkg and conforms to a subset - of Debian’s policy manual regarding control files. - - - - -
- -
- Archived Components - - - The Build Appliance is a virtual machine image that enables - you to build and boot a custom embedded Linux image with - the Yocto Project using a non-Linux development system. - - - - Historically, the Build Appliance was the second of three - methods by which you could use the Yocto Project on a system - that was not native to Linux. - - - Hob: - Hob, which is now deprecated and is no longer available - since the 2.1 release of the Yocto Project provided - a rudimentary, GUI-based interface to the Yocto - Project. - Toaster has fully replaced Hob. - - - Build Appliance: - Post Hob, the Build Appliance became available. - It was never recommended that you use the Build - Appliance as a day-to-day production development - environment with the Yocto Project. - Build Appliance was useful as a way to try out - development in the Yocto Project environment. - - - CROPS: - The final and best solution available now for - developing using the Yocto Project on a system - not native to Linux is with - CROPS. - - - -
-
- -
- Development Methods - - - The Yocto Project development environment usually involves a - Build Host - and target hardware. - You use the Build Host to build images and develop applications, - while you use the target hardware to test deployed software. - - - - This section provides an introduction to the choices or - development methods you have when setting up your Build Host. - Depending on the your particular workflow preference and the - type of operating system your Build Host runs, several choices - exist that allow you to use the Yocto Project. - - For additional detail about the Yocto Project development - environment, see the - "The Yocto Project Development Environment" - chapter. - - - - Native Linux Host: - By far the best option for a Build Host. - A system running Linux as its native operating system - allows you to develop software by directly using the - BitBake - tool. - You can accomplish all aspects of development from a - familiar shell of a supported Linux distribution. - - For information on how to set up a Build Host on - a system running Linux as its native operating system, - see the - "Setting Up a Native Linux Host" - section in the Yocto Project Development Tasks Manual. - - - CROss PlatformS (CROPS): - Typically, you use - CROPS, - which leverages - Docker Containers, - to set up a Build Host that is not running Linux (e.g. - Microsoft - Windows - or - macOS). - - You can, however, use CROPS on a Linux-based system. - - CROPS is an open source, cross-platform development - framework that provides an easily managed, extensible - environment for building binaries targeted for a variety - of architectures on Windows, macOS, or Linux hosts. - Once the Build Host is set up using CROPS, you can prepare - a shell environment to mimic that of a shell being used - on a system natively running Linux. - - For information on how to set up a Build Host with - CROPS, see the - "Setting Up to Use CROss PlatformS (CROPS)" - section in the Yocto Project Development Tasks Manual. - - - Toaster: - Regardless of what your Build Host is running, you can - use Toaster to develop software using the Yocto Project. - Toaster is a web interface to the Yocto Project's - OpenEmbedded build system. - The interface enables you to configure and run your - builds. - Information about builds is collected and stored in a - database. - You can use Toaster to configure and start builds on - multiple remote build servers. - - For information about and how to use Toaster, - see the - Toaster User Manual. - - - Eclipse IDE: - If your Build Host supports and runs the popular - Eclipse IDE, you can install the Yocto Project Eclipse - plug-in and use the Yocto Project to develop software. - The plug-in integrates the Yocto Project functionality - into Eclipse development practices. - - For information about how to install and use the - Yocto Project Eclipse plug-in, see the - "Developing Applications Using Eclipse" - section in the Yocto Project Application Development and - the Extensible Software Development Kit (eSDK) Manual. - - - -
- -
- Reference Embedded Distribution (Poky) - - - "Poky", which is pronounced Pock-ee, is the - name of the Yocto Project's reference distribution or Reference OS - Kit. - Poky contains the - OpenEmbedded Build System - build system - (BitBake and - OpenEmbedded-Core) - as well as a set of - metadata to get - you started building your own distro. - In other words, Poky is a base specification of the functionality - needed for a typical embedded system as well as the components - from the Yocto Project that allow you to build a distribution into - a usable binary image. - - - - Poky is a combined repository of BitBake, OpenEmbedded-Core - (which is found in meta), - meta-poky, - meta-yocto-bsp, and documentation provided - all together and known to work well together. - You can view these items that make up the Poky repository in the - Source Repositories. - - If you are interested in all the contents of the - poky Git repository, see the - "Top-Level Core Components" - section in the Yocto Project Reference Manual. - - - - - The following figure illustrates what generally comprises Poky: - - - - BitBake is a task executor and scheduler that is the heart of - the OpenEmbedded build system. - - - meta-poky, which is Poky-specific - metadata. - - - meta-yocto-bsp, which is Yocto - Project-specific Board Support Packages (BSPs). - - - OpenEmbedded-Core (OE-Core) metadata, which includes - shared configurations, global variable definitions, - shared classes, packaging, and recipes. - Classes define the encapsulation and inheritance of build - logic. - Recipes are the logical units of software and images - to be built. - - - Documentation, which contains the Yocto Project source - files used to make the set of user manuals. - - - - While Poky is a "complete" distribution specification and is - tested and put through QA, you cannot use it as a product - "out of the box" in its current form. - - - - - To use the Yocto Project tools, you can use Git to clone (download) - the Poky repository then use your local copy of the reference - distribution to bootstrap your own distribution. - - Poky does not contain binary files. - It is a working example of how to build your own custom Linux distribution - from source. - - - - - Poky has a regular, well established, six-month release cycle - under its own version. - Major releases occur at the same time major releases (point - releases) occur for the Yocto Project, which are typically in the - Spring and Fall. - For more information on the Yocto Project release schedule and - cadence, see the - "Yocto Project Releases and the Stable Release Process" - chapter in the Yocto Project Reference Manual. - - - - Much has been said about Poky being a "default configuration." - A default configuration provides a starting image footprint. - You can use Poky out of the box to create an image ranging from a - shell-accessible minimal image all the way up to a Linux - Standard Base-compliant image that uses a GNOME Mobile and - Embedded (GMAE) based reference user interface called Sato. - - - - One of the most powerful properties of Poky is that every aspect - of a build is controlled by the metadata. - You can use metadata to augment these base image types by - adding metadata layers that extend functionality. - These layers can provide, for example, an additional software - stack for an image type, add a board support package (BSP) for - additional hardware, or even create a new image type. - - - - Metadata is loosely grouped into configuration files or package - recipes. - A recipe is a collection of non-executable metadata used by - BitBake to set variables or define additional build-time tasks. - A recipe contains fields such as the recipe description, the recipe - version, the license of the package and the upstream source - repository. - A recipe might also indicate that the build process uses autotools, - make, distutils or any other build process, in which case the basic - functionality can be defined by the classes it inherits from - the OE-Core layer's class definitions in - ./meta/classes. - Within a recipe you can also define additional tasks as well as - task prerequisites. - Recipe syntax through BitBake also supports both - _prepend and _append - operators as a method of extending task functionality. - These operators inject code into the beginning or end of a task. - For information on these BitBake operators, see the - "Appending and Prepending (Override Style Syntax)" - section in the BitBake User's Manual. - -
- -
- The OpenEmbedded Build System Workflow - - - The OpenEmbedded build system uses a "workflow" to accomplish - image and SDK generation. - The following figure overviews that workflow: - - Following is a brief summary of the "workflow": - - - Developers specify architecture, policies, patches and - configuration details. - - - The build system fetches and downloads the source code - from the specified location. - The build system supports standard methods such as tarballs - or source code repositories systems such as Git. - - - Once downloaded, the build system extracts the sources - into a local work area where patches are applied and - common steps for configuring and compiling the software - are run. - - - The build system then installs the software into a - temporary staging area where the binary package format you - select (DEB, RPM, or IPK) is used to roll up the software. - - - Different QA and sanity checks run throughout entire - build process. - - - After the binaries are created, the build system - generates a binary package feed that is used to create - the final root file image. - - - The build system generates the file system image and a - customized Extensible SDK (eSDSK) for application - development in parallel. - - - - - - For a very detailed look at this workflow, see the - "Development Concepts" - section in the Yocto Project Overview and Concepts Manual. - -
- - -
- Some Basic Terms - - - It helps to understand some basic fundamental terms when - learning the Yocto Project. - Although a list of terms exists in the - "Yocto Project Terms" - section of the Yocto Project Reference Manual, this section - provides the definitions of some terms helpful for getting started: - - - Configuration Files: - Files that hold global definitions of variables, - user-defined variables, and hardware configuration - information. - These files tell the OpenEmbedded build system what to - build and what to put into the image to support a - particular platform. - - - Extensible Software Development Kit (eSDK): - A custom SDK for application developers. - This eSDK allows developers to incorporate their library - and programming changes back into the image to make - their code available to other application developers. - For information on the eSDK, see the - Yocto Project Application Development and Extensible Software Development Kit (eSDK) - manual. - - - Layer: - A collection of related recipes. - Layers allow you to consolidate related metadata to - customize your build. - Layers also isolate information used when building - for multiple architectures. - Layers are hierarchical in their ability to override - previous specifications. - You can include any number of available layers from the - Yocto Project and customize the build by adding your - layers after them. - You can search the Layer Index for layers used within - Yocto Project. - - For more detailed information on layers, see the - "Understanding and Creating Layers" - section in the Yocto Project Development Tasks Manual. - For a discussion specifically on BSP Layers, see the - "BSP Layers" - section in the Yocto Project Board Support Packages (BSP) - Developer's Guide. - - - Metadata: - A key element of the Yocto Project is the Metadata that - is used to construct a Linux distribution and is contained - in the files that the - OpenEmbedded build system parses - when building an image. - In general, Metadata includes recipes, configuration - files, and other information that refers to the build - instructions themselves, as well as the data used to - control what things get built and the effects of the - build. - Metadata also includes commands and data used to - indicate what versions of software are used, from - where they are obtained, and changes or additions to the - software itself (patches or auxiliary files) that - are used to fix bugs or customize the software for use - in a particular situation. - OpenEmbedded-Core is an important set of validated - metadata. - - - OpenEmbedded Build System: - The terms "BitBake" and "build system" are sometimes - used for the OpenEmbedded Build System. - - BitBake is a task scheduler and execution engine - that parses instructions (i.e. recipes) and configuration - data. - After a parsing phase, BitBake creates a dependency tree - to order the compilation, schedules the compilation of - the included code, and finally executes the building - of the specified custom Linux image (distribution). - BitBake is similar to the make - tool. - - During a build process, the build system tracks - dependencies and performs a native or cross-compilation - of the package. - As a first step in a cross-build setup, the framework - attempts to create a cross-compiler toolchain - (i.e. Extensible SDK) suited for the target platform. - - - OpenEmbedded-Core (OE-Core): - OE-Core is metadata comprised of foundation recipes, - classes, and associated files that are meant to be - common among many different OpenEmbedded-derived systems, - including the Yocto Project. - OE-Core is a curated subset of an original repository - developed by the OpenEmbedded community that has been - pared down into a smaller, core set of continuously - validated recipes. - The result is a tightly controlled and quality-assured - core set of recipes. - - You can see the Metadata in the - meta directory of the Yocto Project - Source Repositories. - - - Packages: - In the context of the Yocto Project, this term refers to a - recipe's packaged output produced by BitBake (i.e. a - "baked recipe"). - A package is generally the compiled binaries produced from the - recipe's sources. - You "bake" something by running it through BitBake. - - It is worth noting that the term "package" can, - in general, have subtle meanings. - For example, the packages referred to in the - "Required Packages for the Host Development System" - section in the Yocto Project Reference Manual are compiled - binaries that, when installed, add functionality to your - Linux distribution. - - Another point worth noting is that historically within - the Yocto Project, recipes were referred to as packages - thus, - the existence of several BitBake variables that are seemingly - mis-named, - (e.g. PR, - PV, - and - PE). - - - Poky: - Poky is a reference embedded distribution and a reference - test configuration. - Poky provides the following: - - - A base-level functional distro used to illustrate - how to customize a distribution. - - - A means by which to test the Yocto Project - components (i.e. Poky is used to validate - the Yocto Project). - - - A vehicle through which you can download - the Yocto Project. - - - Poky is not a product level distro. - Rather, it is a good starting point for customization. - - Poky is an integration layer on top of OE-Core. - - - - Recipe: - The most common form of metadata. - A recipe contains a list of settings and tasks - (i.e. instructions) for building packages that are then - used to build the binary image. - A recipe describes where you get source code and which - patches to apply. - Recipes describe dependencies for libraries or for other - recipes as well as configuration and compilation options. - Related recipes are consolidated into a layer. - - - -
- - diff --git a/documentation/getting-started/getting-started.xml b/documentation/getting-started/getting-started.xml deleted file mode 100644 index cb5d0f5662..0000000000 --- a/documentation/getting-started/getting-started.xml +++ /dev/null @@ -1,108 +0,0 @@ - %poky; ] > - - - - - - - - - - - - Yocto Project Overview and Concepts Manual - - - - - Scott Rifenbark - - Scotty's Documentation Services, INC - - srifenbark@gmail.com - - - - - - 2.5 - April 2018 - The initial document released with the Yocto Project 2.5 Release. - - - - - ©RIGHT_YEAR; - Linux Foundation - - - - - Permission is granted to copy, distribute and/or modify this document under - the terms of the - Creative Commons Attribution-Share Alike 2.0 UK: England & Wales as published by - Creative Commons. - - Manual Notes - - - This version of the - Yocto Project Overview and Concepts Manual - is for the &YOCTO_DOC_VERSION; release of the - Yocto Project. - To be sure you have the latest version of the manual - for this release, go to the - Yocto Project documentation page - and select the manual from that site. - Manuals from the site are more up-to-date than manuals - derived from the Yocto Project released TAR files. - - - If you located this manual through a web search, the - version of the manual might not be the one you want - (e.g. the search might have returned a manual much - older than the Yocto Project version with which you - are working). - You can see all Yocto Project major releases by - visiting the - Releases - page. - If you need a version of this manual for a different - Yocto Project release, visit the - Yocto Project documentation page - and select the manual set by using the - "ACTIVE RELEASES DOCUMENTATION" or "DOCUMENTS ARCHIVE" - pull-down menus. - - - To report any inaccuracies or problems with this - manual, send an email to the Yocto Project - discussion group at - yocto@yoctoproject.com or log into - the freenode #yocto channel. - - - - - - - - - - - - - - - - - diff --git a/documentation/mega-manual/figures/getting-started-title.png b/documentation/mega-manual/figures/getting-started-title.png deleted file mode 100644 index f38b078ab7..0000000000 Binary files a/documentation/mega-manual/figures/getting-started-title.png and /dev/null differ diff --git a/documentation/mega-manual/figures/overview-manual-title.png b/documentation/mega-manual/figures/overview-manual-title.png new file mode 100644 index 0000000000..698f0f3d11 Binary files /dev/null and b/documentation/mega-manual/figures/overview-manual-title.png differ diff --git a/documentation/mega-manual/mega-manual.xml b/documentation/mega-manual/mega-manual.xml index fae6af6ab5..21e773072d 100644 --- a/documentation/mega-manual/mega-manual.xml +++ b/documentation/mega-manual/mega-manual.xml @@ -141,23 +141,23 @@ - + - + + xmlns:xi="http://www.w3.org/2003/XInclude" href="../overview-manual/overview-manual-intro.xml"/> + xmlns:xi="http://www.w3.org/2003/XInclude" href="../overview-manual/overview-manual-yp-intro.xml"/> + xmlns:xi="http://www.w3.org/2003/XInclude" href="../overview-manual/overview-manual-development-environment.xml"/> + xmlns:xi="http://www.w3.org/2003/XInclude" href="../overview-manual/overview-manual-concepts.xml"/> diff --git a/documentation/overview-manual/figures/YP-flow-diagram.png b/documentation/overview-manual/figures/YP-flow-diagram.png new file mode 100644 index 0000000000..8264410504 Binary files /dev/null and b/documentation/overview-manual/figures/YP-flow-diagram.png differ diff --git a/documentation/overview-manual/figures/analysis-for-package-splitting.png b/documentation/overview-manual/figures/analysis-for-package-splitting.png new file mode 100644 index 0000000000..04f2794ea9 Binary files /dev/null and b/documentation/overview-manual/figures/analysis-for-package-splitting.png differ diff --git a/documentation/overview-manual/figures/configuration-compile-autoreconf.png b/documentation/overview-manual/figures/configuration-compile-autoreconf.png new file mode 100644 index 0000000000..a07464f04c Binary files /dev/null and b/documentation/overview-manual/figures/configuration-compile-autoreconf.png differ diff --git a/documentation/overview-manual/figures/cross-development-toolchains.png b/documentation/overview-manual/figures/cross-development-toolchains.png new file mode 100644 index 0000000000..cbe8371c05 Binary files /dev/null and b/documentation/overview-manual/figures/cross-development-toolchains.png differ diff --git a/documentation/overview-manual/figures/git-workflow.png b/documentation/overview-manual/figures/git-workflow.png new file mode 100644 index 0000000000..e401330a12 Binary files /dev/null and b/documentation/overview-manual/figures/git-workflow.png differ diff --git a/documentation/overview-manual/figures/image-generation.png b/documentation/overview-manual/figures/image-generation.png new file mode 100644 index 0000000000..71a48dc6f4 Binary files /dev/null and b/documentation/overview-manual/figures/image-generation.png differ diff --git a/documentation/overview-manual/figures/images.png b/documentation/overview-manual/figures/images.png new file mode 100644 index 0000000000..d99eac1fbf Binary files /dev/null and b/documentation/overview-manual/figures/images.png differ diff --git a/documentation/overview-manual/figures/index-downloads.png b/documentation/overview-manual/figures/index-downloads.png new file mode 100644 index 0000000000..96303b8781 Binary files /dev/null and b/documentation/overview-manual/figures/index-downloads.png differ diff --git a/documentation/overview-manual/figures/key-dev-elements.png b/documentation/overview-manual/figures/key-dev-elements.png new file mode 100644 index 0000000000..76c44050fd Binary files /dev/null and b/documentation/overview-manual/figures/key-dev-elements.png differ diff --git a/documentation/overview-manual/figures/layer-input.png b/documentation/overview-manual/figures/layer-input.png new file mode 100644 index 0000000000..0a4f2e74f3 Binary files /dev/null and b/documentation/overview-manual/figures/layer-input.png differ diff --git a/documentation/overview-manual/figures/overview-manual-title.png b/documentation/overview-manual/figures/overview-manual-title.png new file mode 100644 index 0000000000..698f0f3d11 Binary files /dev/null and b/documentation/overview-manual/figures/overview-manual-title.png differ diff --git a/documentation/overview-manual/figures/package-feeds.png b/documentation/overview-manual/figures/package-feeds.png new file mode 100644 index 0000000000..37c9c32506 Binary files /dev/null and b/documentation/overview-manual/figures/package-feeds.png differ diff --git a/documentation/overview-manual/figures/patching.png b/documentation/overview-manual/figures/patching.png new file mode 100644 index 0000000000..8ecd018502 Binary files /dev/null and b/documentation/overview-manual/figures/patching.png differ diff --git a/documentation/overview-manual/figures/poky-reference-distribution.png b/documentation/overview-manual/figures/poky-reference-distribution.png new file mode 100644 index 0000000000..1be89ae68e Binary files /dev/null and b/documentation/overview-manual/figures/poky-reference-distribution.png differ diff --git a/documentation/overview-manual/figures/sdk-generation.png b/documentation/overview-manual/figures/sdk-generation.png new file mode 100755 index 0000000000..adbe1f4acf Binary files /dev/null and b/documentation/overview-manual/figures/sdk-generation.png differ diff --git a/documentation/overview-manual/figures/sdk.png b/documentation/overview-manual/figures/sdk.png new file mode 100644 index 0000000000..5c36b7548b Binary files /dev/null and b/documentation/overview-manual/figures/sdk.png differ diff --git a/documentation/overview-manual/figures/source-fetching.png b/documentation/overview-manual/figures/source-fetching.png new file mode 100644 index 0000000000..26aefb50c2 Binary files /dev/null and b/documentation/overview-manual/figures/source-fetching.png differ diff --git a/documentation/overview-manual/figures/source-input.png b/documentation/overview-manual/figures/source-input.png new file mode 100644 index 0000000000..f7515058ef Binary files /dev/null and b/documentation/overview-manual/figures/source-input.png differ diff --git a/documentation/overview-manual/figures/source-repos.png b/documentation/overview-manual/figures/source-repos.png new file mode 100644 index 0000000000..603300b6d2 Binary files /dev/null and b/documentation/overview-manual/figures/source-repos.png differ diff --git a/documentation/overview-manual/figures/user-configuration.png b/documentation/overview-manual/figures/user-configuration.png new file mode 100644 index 0000000000..c298401fc3 Binary files /dev/null and b/documentation/overview-manual/figures/user-configuration.png differ diff --git a/documentation/overview-manual/figures/yocto-environment-ref.png b/documentation/overview-manual/figures/yocto-environment-ref.png new file mode 100644 index 0000000000..650c6c8030 Binary files /dev/null and b/documentation/overview-manual/figures/yocto-environment-ref.png differ diff --git a/documentation/overview-manual/figures/yp-download.png b/documentation/overview-manual/figures/yp-download.png new file mode 100644 index 0000000000..bfd12b678a Binary files /dev/null and b/documentation/overview-manual/figures/yp-download.png differ diff --git a/documentation/overview-manual/overview-manual-concepts.xml b/documentation/overview-manual/overview-manual-concepts.xml new file mode 100644 index 0000000000..123cf15d19 --- /dev/null +++ b/documentation/overview-manual/overview-manual-concepts.xml @@ -0,0 +1,3612 @@ + %poky; ] > + + +Yocto Project Concepts + +
+ Yocto Project Components + + + 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. + + + + 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. + + + + + + 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. + + + + 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"). + 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. + +
+ +
+ 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. + +
+
+ +
+ Layers + + + Layers are repositories that contain related sets of instructions + that tell the OpenEmbedded build system what to do. + You use different layers to logically separate information in your + build. + You can collaborate, share, and reuse layers. + The Layer Model simultaneously supports collaboration and + customization. + + + + For more introductory information on the Yocto Project's layer + model, see the + "The Yocto Project Layer Model" + section in the Yocto Project Overview and Concepts Manual. + For procedures on how to create layers, see the + "Understanding and Creating Layers" + section in the Yocto Project Development Tasks Manual. + +
+ +
+ Development Concepts + + + This section takes a more detailed look inside the build + process used by the OpenEmbedded build system. + The following diagram represents the build at a high level. + The remainder of this section expands on the fundamental input, + output, process, and + Metadata + blocks that make up the build process. + + + + + + + + In general, the build process consists of several functional areas: + + + User Configuration: + Metadata you can use to control the build process. + + + Metadata Layers: + Various layers that provide software, machine, and + distro Metadata. + + + Source Files: + Upstream releases, local projects, and SCMs. + + + Build System: + Processes under the control of + BitBake. + This block expands on how BitBake fetches source, applies + patches, completes compilation, analyzes output for package + generation, creates and tests packages, generates images, + and generates cross-development tools. + + + Package Feeds: + Directories containing output packages (RPM, DEB or IPK), + which are subsequently used in the construction of an + image or SDK, produced by the build system. + These feeds can also be copied and shared using a web + server or other means to facilitate extending or updating + existing images on devices at runtime if runtime package + management is enabled. + + + Images: + Images produced by the development process. + + + Application Development SDK: + Cross-development tools that are produced along with + an image or separately with BitBake. + + + + +
+ User Configuration + + + User configuration helps define the build. + Through user configuration, you can tell BitBake the + target architecture for which you are building the image, + where to store downloaded source, and other build properties. + + + + The following figure shows an expanded representation of the + "User Configuration" box of the + general Build Process figure: + + + + + + + + BitBake needs some basic configuration files in order to + complete a build. + These files are *.conf files. + The minimally necessary ones reside as example files in the + Source Directory. + For simplicity, this section refers to the Source Directory as + the "Poky Directory." + + + + When you clone the poky Git repository + or you download and unpack a Yocto Project release, you + can set up the Source Directory to be named anything you want. + For this discussion, the cloned repository uses the default + name poky. + + The + Poky + repository is primarily an aggregation of existing + repositories. + It is not a canonical upstream source. + + + + + The meta-poky layer inside Poky contains + a conf directory that has example + configuration files. + These example files are used as a basis for creating actual + configuration files when you source the build environment + script + (i.e. + &OE_INIT_FILE;). + + + + Sourcing the build environment script creates a + Build Directory + if one does not already exist. + BitBake uses the Build Directory for all its work during + builds. + The Build Directory has a conf directory + that contains default versions of your + local.conf and + bblayers.conf configuration files. + These default configuration files are created only if versions + do not already exist in the Build Directory at the time you + source the build environment setup script. + + + + Because the Poky repository is fundamentally an aggregation of + existing repositories, some users might be familiar with + running the &OE_INIT_FILE; script + in the context of separate + OpenEmbedded-Core + and BitBake repositories rather than a single Poky repository. + This discussion assumes the script is executed from + within a cloned or unpacked version of Poky. + + + + Depending on where the script is sourced, different + sub-scripts are called to set up the Build Directory + (Yocto or OpenEmbedded). + Specifically, the script + scripts/oe-setup-builddir inside the + poky directory sets up the Build Directory and seeds the + directory (if necessary) with configuration files appropriate + for the Yocto Project development environment. + + The scripts/oe-setup-builddir script + uses the $TEMPLATECONF variable to + determine which sample configuration files to locate. + + + + + The local.conf file provides many + basic variables that define a build environment. + Here is a list of a few. + To see the default configurations in a + local.conf file created by the build + environment script, see the + local.conf.sample in the + meta-poky layer: + + + Parallelism Options: + Controlled by the + BB_NUMBER_THREADS, + PARALLEL_MAKE, + and + BB_NUMBER_PARSE_THREADS + variables. + + + Target Machine Selection: + Controlled by the + MACHINE + variable. + + + Download Directory: + Controlled by the + DL_DIR + variable. + + + Shared State Directory: + Controlled by the + SSTATE_DIR + variable. + + + Build Output: + Controlled by the + TMPDIR + variable. + + + + Configurations set in the + conf/local.conf file can also be set + in the conf/site.conf and + conf/auto.conf configuration files. + + + + + The bblayers.conf file tells BitBake what + layers you want considered during the build. + By default, the layers listed in this file include layers + minimally needed by the build system. + However, you must manually add any custom layers you have + created. + You can find more information on working with the + bblayers.conf file in the + "Enabling Your Layer" + section in the Yocto Project Development Tasks Manual. + + + + The files site.conf and + auto.conf are not created by the + environment initialization script. + If you want the site.conf file, you + need to create that yourself. + The auto.conf file is typically created by + an autobuilder: + + + site.conf: + You can use the conf/site.conf + configuration file to configure multiple + build directories. + For example, suppose you had several build environments + and they shared some common features. + You can set these default build properties here. + A good example is perhaps the packaging format to use + through the + PACKAGE_CLASSES + variable. + + One useful scenario for using the + conf/site.conf file is to extend + your + BBPATH + variable to include the path to a + conf/site.conf. + Then, when BitBake looks for Metadata using + BBPATH, it finds the + conf/site.conf file and applies + your common configurations found in the file. + To override configurations in a particular build + directory, alter the similar configurations within + that build directory's + conf/local.conf file. + + + auto.conf: + The file is usually created and written to by + an autobuilder. + The settings put into the file are typically the + same as you would find in the + conf/local.conf or the + conf/site.conf files. + + + + + + You can edit all configuration files to further define + any particular build environment. + This process is represented by the "User Configuration Edits" + box in the figure. + + + + When you launch your build with the + bitbake target + command, BitBake sorts out the configurations to ultimately + define your build environment. + It is important to understand that the + OpenEmbedded build system + reads the configuration files in a specific order: + site.conf, auto.conf, + and local.conf. + And, the build system applies the normal assignment statement + rules. + Because the files are parsed in a specific order, variable + assignments for the same variable could be affected. + For example, if the auto.conf file and + the local.conf set + variable1 to different values, + because the build system parses local.conf + after auto.conf, + variable1 is assigned the value from + the local.conf file. + +
+ +
+ Metadata, Machine Configuration, and Policy Configuration + + + The previous section described the user configurations that + define BitBake's global behavior. + This section takes a closer look at the layers the build system + uses to further control the build. + These layers provide Metadata for the software, machine, and + policy. + + + + In general, three types of layer input exist: + + + Policy Configuration: + Distribution Layers provide top-level or general + policies for the image or SDK being built. + For example, this layer would dictate whether BitBake + produces RPM or IPK packages. + + + Machine Configuration: + Board Support Package (BSP) layers provide machine + configurations. + This type of information is specific to a particular + target architecture. + + + Metadata: + Software layers contain user-supplied recipe files, + patches, and append files. + + + + + + The following figure shows an expanded representation of the + Metadata, Machine Configuration, and Policy Configuration input + (layers) boxes of the + general Build Process figure: + + + + + + + + In general, all layers have a similar structure. + They all contain a licensing file + (e.g. COPYING) if the layer is to be + distributed, a README file as good + practice and especially if the layer is to be distributed, a + configuration directory, and recipe directories. + + + + The Yocto Project has many layers that can be used. + You can see a web-interface listing of them on the + Source Repositories + page. + The layers appear at the bottom categorized under + "Yocto Metadata Layers." + These layers are fundamentally a subset of the + OpenEmbedded Metadata Index, + which lists all layers provided by the OpenEmbedded community. + + Layers exist in the Yocto Project Source Repositories that + cannot be found in the OpenEmbedded Metadata Index. + These layers are either deprecated or experimental + in nature. + + + + + BitBake uses the conf/bblayers.conf file, + which is part of the user configuration, to find what layers it + should be using as part of the build. + + + + For more information on layers, see the + "Understanding and Creating Layers" + section in the Yocto Project Development Tasks Manual. + + +
+ Distro Layer + + + The distribution layer provides policy configurations for + your distribution. + Best practices dictate that you isolate these types of + configurations into their own layer. + Settings you provide in + conf/distro/distro.conf override + similar settings that BitBake finds in your + conf/local.conf file in the Build + Directory. + + + + The following list provides some explanation and references + for what you typically find in the distribution layer: + + + classes: + Class files (.bbclass) hold + common functionality that can be shared among + recipes in the distribution. + When your recipes inherit a class, they take on the + settings and functions for that class. + You can read more about class files in the + "Classes" + chapter of the Yocto Reference Manual. + + + conf: + This area holds configuration files for the + layer (conf/layer.conf), + the distribution + (conf/distro/distro.conf), + and any distribution-wide include files. + + + recipes-*: + Recipes and append files that affect common + functionality across the distribution. + This area could include recipes and append files + to add distribution-specific configuration, + initialization scripts, custom image recipes, + and so forth. + + + +
+ +
+ BSP Layer + + + The BSP Layer provides machine configurations. + Everything in this layer is specific to the machine for + which you are building the image or the SDK. + A common structure or form is defined for BSP layers. + You can learn more about this structure in the + Yocto Project Board Support Package (BSP) Developer's Guide. + + In order for a BSP layer to be considered compliant + with the Yocto Project, it must meet some structural + requirements. + + + + + The BSP Layer's configuration directory contains + configuration files for the machine + (conf/machine/machine.conf) + and, of course, the layer + (conf/layer.conf). + + + + The remainder of the layer is dedicated to specific recipes + by function: recipes-bsp, + recipes-core, + recipes-graphics, and + recipes-kernel. + Metadata can exist for multiple formfactors, graphics + support systems, and so forth. + + While the figure shows several + recipes-* directories, not all + these directories appear in all BSP layers. + + +
+ +
+ Software Layer + + + The software layer provides the Metadata for additional + software packages used during the build. + This layer does not include Metadata that is specific to + the distribution or the machine, which are found in their + respective layers. + + + + This layer contains any new recipes that your project + needs in the form of recipe files. + +
+
+ +
+ Sources + + + In order for the OpenEmbedded build system to create an + image or any target, it must be able to access source files. + The + general Build Process figure + represents source files using the "Upstream Project Releases", + "Local Projects", and "SCMs (optional)" boxes. + The figure represents mirrors, which also play a role in + locating source files, with the "Source Mirror(s)" box. + + + + The method by which source files are ultimately organized is + a function of the project. + For example, for released software, projects tend to use + tarballs or other archived files that can capture the + state of a release guaranteeing that it is statically + represented. + On the other hand, for a project that is more dynamic or + experimental in nature, a project might keep source files in a + repository controlled by a Source Control Manager (SCM) such as + Git. + Pulling source from a repository allows you to control + the point in the repository (the revision) from which you + want to build software. + Finally, a combination of the two might exist, which would + give the consumer a choice when deciding where to get + source files. + + + + BitBake uses the + SRC_URI + variable to point to source files regardless of their location. + Each recipe must have a SRC_URI variable + that points to the source. + + + + Another area that plays a significant role in where source + files come from is pointed to by the + DL_DIR + variable. + This area is a cache that can hold previously downloaded + source. + You can also instruct the OpenEmbedded build system to create + tarballs from Git repositories, which is not the default + behavior, and store them in the DL_DIR + by using the + BB_GENERATE_MIRROR_TARBALLS + variable. + + + + Judicious use of a DL_DIR directory can + save the build system a trip across the Internet when looking + for files. + A good method for using a download directory is to have + DL_DIR point to an area outside of your + Build Directory. + Doing so allows you to safely delete the Build Directory + if needed without fear of removing any downloaded source file. + + + + The remainder of this section provides a deeper look into the + source files and the mirrors. + Here is a more detailed look at the source file area of the + general Build Process figure: + + + +
+ Upstream Project Releases + + + Upstream project releases exist anywhere in the form of an + archived file (e.g. tarball or zip file). + These files correspond to individual recipes. + For example, the figure uses specific releases each for + BusyBox, Qt, and Dbus. + An archive file can be for any released product that can be + built using a recipe. + +
+ +
+ Local Projects + + + Local projects are custom bits of software the user + provides. + These bits reside somewhere local to a project - perhaps + a directory into which the user checks in items (e.g. + a local directory containing a development source tree + used by the group). + + + + The canonical method through which to include a local + project is to use the + externalsrc + class to include that local project. + You use either the local.conf or a + recipe's append file to override or set the + recipe to point to the local directory on your disk to pull + in the whole source tree. + + + + For information on how to use the + externalsrc class, see the + "externalsrc.bbclass" + section. + +
+ +
+ Source Control Managers (Optional) + + + Another place the build system can get source files from is + through an SCM such as Git or Subversion. + In this case, a repository is cloned or checked out. + The + do_fetch + task inside BitBake uses + the SRC_URI + variable and the argument's prefix to determine the correct + fetcher module. + + For information on how to have the OpenEmbedded build + system generate tarballs for Git repositories and place + them in the + DL_DIR + directory, see the + BB_GENERATE_MIRROR_TARBALLS + variable. + + + + + When fetching a repository, BitBake uses the + SRCREV + variable to determine the specific revision from which to + build. + +
+ +
+ Source Mirror(s) + + + Two kinds of mirrors exist: pre-mirrors and regular + mirrors. + The + PREMIRRORS + and + MIRRORS + variables point to these, respectively. + BitBake checks pre-mirrors before looking upstream for any + source files. + Pre-mirrors are appropriate when you have a shared + directory that is not a directory defined by the + DL_DIR + variable. + A Pre-mirror typically points to a shared directory that is + local to your organization. + + + + Regular mirrors can be any site across the Internet + that is used as an alternative location for source + code should the primary site not be functioning for + some reason or another. + +
+
+ +
+ Package Feeds + + + When the OpenEmbedded build system generates an image or an + SDK, it gets the packages from a package feed area located + in the + Build Directory. + The + general Build Process figure + shows this package feeds area in the upper-right corner. + + + + This section looks a little closer into the package feeds + area used by the build system. + Here is a more detailed look at the area: + + + + + Package feeds are an intermediary step in the build process. + The OpenEmbedded build system provides classes to generate + different package types, and you specify which classes to + enable through the + PACKAGE_CLASSES + variable. + Before placing the packages into package feeds, + the build process validates them with generated output quality + assurance checks through the + insane + class. + + + + The package feed area resides in the Build Directory. + The directory the build system uses to temporarily store + packages is determined by a combination of variables and the + particular package manager in use. + See the "Package Feeds" box in the illustration and note the + information to the right of that area. + In particular, the following defines where package files are + kept: + + + DEPLOY_DIR: + Defined as tmp/deploy in the Build + Directory. + + + DEPLOY_DIR_*: + Depending on the package manager used, the package type + sub-folder. + Given RPM, IPK, or DEB packaging and tarball creation, + the + DEPLOY_DIR_RPM, + DEPLOY_DIR_IPK, + DEPLOY_DIR_DEB, + or + DEPLOY_DIR_TAR, + variables are used, respectively. + + + PACKAGE_ARCH: + Defines architecture-specific sub-folders. + For example, packages could exist for the i586 or + qemux86 architectures. + + + + + + BitBake uses the + do_package_write_* + tasks to generate packages and place them into the package + holding area (e.g. do_package_write_ipk + for IPK packages). + See the + "do_package_write_deb", + "do_package_write_ipk", + "do_package_write_rpm", + and + "do_package_write_tar" + sections in the Yocto Project Reference Manual + for additional information. + As an example, consider a scenario where an IPK packaging + manager is being used and package architecture support for + both i586 and qemux86 exist. + Packages for the i586 architecture are placed in + build/tmp/deploy/ipk/i586, while packages + for the qemux86 architecture are placed in + build/tmp/deploy/ipk/qemux86. + +
+ +
+ BitBake + + + The OpenEmbedded build system uses + BitBake + to produce images. + You can see from the + general Build Process figure, + the BitBake area consists of several functional areas. + This section takes a closer look at each of those areas. + + + + Separate documentation exists for the BitBake tool. + See the + BitBake User Manual + for reference material on BitBake. + + +
+ Source Fetching + + + The first stages of building a recipe are to fetch and + unpack the source code: + + + + + The + do_fetch + and + do_unpack + tasks fetch the source files and unpack them into the work + directory. + + For every local file (e.g. file://) + that is part of a recipe's + SRC_URI + statement, the OpenEmbedded build system takes a + checksum of the file for the recipe and inserts the + checksum into the signature for the + do_fetch. + If any local file has been modified, the + do_fetch task and all tasks that + depend on it are re-executed. + + By default, everything is accomplished in the + Build Directory, + which has a defined structure. + For additional general information on the Build Directory, + see the + "build/" + section in the Yocto Project Reference Manual. + + + + Unpacked source files are pointed to by the + S + variable. + Each recipe has an area in the Build Directory where the + unpacked source code resides. + The name of that directory for any given recipe is defined + from several different variables. + You can see the variables that define these directories + by looking at the figure: + + + TMPDIR: + The base directory where the OpenEmbedded build + system performs all its work during the build. + + + PACKAGE_ARCH: + The architecture of the built package or packages. + + + TARGET_OS: + The operating system of the target device. + + + PN: + The name of the built package. + + + PV: + The version of the recipe used to build the + package. + + + PR: + The revision of the recipe used to build the + package. + + + WORKDIR: + The location within TMPDIR + where a specific package is built. + + + S: + Contains the unpacked source files for a given + recipe. + + + +
+ +
+ Patching + + + Once source code is fetched and unpacked, BitBake locates + patch files and applies them to the source files: + + + + + The + do_patch + task processes recipes by using the + SRC_URI + variable to locate applicable patch files, which by default + are *.patch or + *.diff files, or any file if + "apply=yes" is specified for the file in + SRC_URI. + + + + BitBake finds and applies multiple patches for a single + recipe in the order in which it finds the patches. + Patches are applied to the recipe's source files located + in the + S + directory. + + + + For more information on how the source directories are + created, see the + "Source Fetching" + section. + +
+ +
+ Configuration and Compilation + + + After source code is patched, BitBake executes tasks that + configure and compile the source code: + + + + + This step in the build process consists of three tasks: + + + do_prepare_recipe_sysroot: + This task sets up the two sysroots in + ${WORKDIR} + (i.e. recipe-sysroot and + recipe-sysroot-native) so that + the sysroots contain the contents of the + do_populate_sysroot + tasks of the recipes on which the recipe + containing the tasks depends. + A sysroot exists for both the target and for the + native binaries, which run on the host system. + + + do_configure: + This task configures the source by enabling and + disabling any build-time and configuration options + for the software being built. + Configurations can come from the recipe itself as + well as from an inherited class. + Additionally, the software itself might configure + itself depending on the target for which it is + being built. + + The configurations handled by the + do_configure + task are specific to source code configuration for + the source code being built by the recipe. + + If you are using the + autotools + class, you can add additional configuration options + by using the + EXTRA_OECONF + or + PACKAGECONFIG_CONFARGS + variables. + For information on how this variable works within + that class, see the + meta/classes/autotools.bbclass + file. + + + do_compile: + Once a configuration task has been satisfied, BitBake + compiles the source using the + do_compile + task. + Compilation occurs in the directory pointed to by + the + B + variable. + Realize that the B directory + is, by default, the same as the + S + directory. + + + do_install: + Once compilation is done, BitBake executes the + do_install + task. + This task copies files from the + B directory and places them + in a holding area pointed to by the + D + variable. + + + +
+ +
+ Package Splitting + + + After source code is configured and compiled, the + OpenEmbedded build system analyzes + the results and splits the output into packages: + + + + + The + do_package + and + do_packagedata + tasks combine to analyze the files found in the + D + directory and split them into subsets based on available + packages and files. + The analyzing process involves the following as well as + other items: splitting out debugging symbols, looking at + shared library dependencies between packages, and looking + at package relationships. + The do_packagedata task creates + package metadata based on the analysis such that the + OpenEmbedded build system can generate the final packages. + Working, staged, and intermediate results of the analysis + and package splitting process use these areas: + + + PKGD: + The destination directory for packages before they + are split. + + + PKGDATA_DIR: + A shared, global-state directory that holds data + generated during the packaging process. + + + PKGDESTWORK: + A temporary work area used by the + do_package task. + + + PKGDEST: + The parent directory for packages after they have + been split. + + + The + FILES + variable defines the files that go into each package in + PACKAGES. + If you want details on how this is accomplished, you can + look at the + package + class. + + + + Depending on the type of packages being created (RPM, DEB, + or IPK), the + do_package_write_* + task creates the actual packages and places them in the + Package Feed area, which is + ${TMPDIR}/deploy. + You can see the + "Package Feeds" + section for more detail on that part of the build process. + + Support for creating feeds directly from the + deploy/* directories does not + exist. + Creating such feeds usually requires some kind of feed + maintenance mechanism that would upload the new + packages into an official package feed (e.g. the + Ångström distribution). + This functionality is highly distribution-specific + and thus is not provided out of the box. + + +
+ +
+ Image Generation + + + Once packages are split and stored in the Package Feeds + area, the OpenEmbedded build system uses BitBake to + generate the root filesystem image: + + + + + The image generation process consists of several stages and + depends on several tasks and variables. + The + do_rootfs + task creates the root filesystem (file and directory + structure) for an image. + This task uses several key variables to help create the + list of packages to actually install: + + + IMAGE_INSTALL: + Lists out the base set of packages to install from + the Package Feeds area. + + + PACKAGE_EXCLUDE: + Specifies packages that should not be installed. + + + IMAGE_FEATURES: + Specifies features to include in the image. + Most of these features map to additional packages + for installation. + + + PACKAGE_CLASSES: + Specifies the package backend to use and + consequently helps determine where to locate + packages within the Package Feeds area. + + + IMAGE_LINGUAS: + Determines the language(s) for which additional + language support packages are installed. + + + PACKAGE_INSTALL: + The final list of packages passed to the package manager + for installation into the image. + + + + + + With + IMAGE_ROOTFS + pointing to the location of the filesystem under + construction and the PACKAGE_INSTALL + variable providing the final list of packages to install, + the root file system is created. + + + + Package installation is under control of the package + manager (e.g. dnf/rpm, opkg, or apt/dpkg) regardless of + whether or not package management is enabled for the + target. + At the end of the process, if package management is not + enabled for the target, the package manager's data files + are deleted from the root filesystem. + As part of the final stage of package installation, + postinstall scripts that are part of the packages are run. + Any scripts that fail to run + on the build host are run on the target when the target + system is first booted. + If you are using a + read-only root filesystem, + all the post installation scripts must succeed during the + package installation phase since the root filesystem is + read-only. + + + + The final stages of the do_rootfs task + handle post processing. + Post processing includes creation of a manifest file and + optimizations. + + + + The manifest file (.manifest) resides + in the same directory as the root filesystem image. + This file lists out, line-by-line, the installed packages. + The manifest file is useful for the + testimage + class, for example, to determine whether or not to run + specific tests. + See the + IMAGE_MANIFEST + variable for additional information. + + + + Optimizing processes run across the image include + mklibs, prelink, + and any other post-processing commands as defined by the + ROOTFS_POSTPROCESS_COMMAND + variable. + The mklibs process optimizes the size + of the libraries, while the prelink + process optimizes the dynamic linking of shared libraries + to reduce start up time of executables. + + + + After the root filesystem is built, processing begins on + the image through the + do_image + task. + The build system runs any pre-processing commands as + defined by the + IMAGE_PREPROCESS_COMMAND + variable. + This variable specifies a list of functions to call before + the OpenEmbedded build system creates the final image + output files. + + + + The OpenEmbedded build system dynamically creates + do_image_* tasks as needed, based + on the image types specified in the + IMAGE_FSTYPES + variable. + The process turns everything into an image file or a set of + image files and can compress the root filesystem image to + reduce the overall size of the image. + The formats used for the root filesystem depend on the + IMAGE_FSTYPES variable. + Compression depends on whether the formats support + compression. + + + + As an example, a dynamically created task when creating a + particular image type would + take the following form: + + do_image_type + + So, if the type as specified by + the IMAGE_FSTYPES were + ext4, the dynamically generated task + would be as follows: + + do_image_ext4 + + + + + The final task involved in image creation is the + do_image_complete + task. + This task completes the image by applying any image + post processing as defined through the + IMAGE_POSTPROCESS_COMMAND + variable. + The variable specifies a list of functions to call once the + OpenEmbedded build system has created the final image + output files. + + The entire image generation process is run under + Pseudo. + Running under Pseudo ensures that the files in the + root filesystem have correct ownership. + + +
+ +
+ SDK Generation + + + The OpenEmbedded build system uses BitBake to generate the + Software Development Kit (SDK) installer script for both + the standard and extensible SDKs: + + + For more information on the cross-development toolchain + generation, see the + "Cross-Development Toolchain Generation" + section. + For information on advantages gained when building a + cross-development toolchain using the + do_populate_sdk + task, see the + "Building an SDK Installer" + section in the Yocto Project Application Development + and the Extensible Software Development Kit (SDK) + manual. + + + + + Like image generation, the SDK script process consists of + several stages and depends on many variables. + The do_populate_sdk and + do_populate_sdk_ext tasks use these + key variables to help create the list of packages to + actually install. + For information on the variables listed in the figure, + see the + "Application Development SDK" + section. + + + + The do_populate_sdk task helps create + the standard SDK and handles two parts: a target part and a + host part. + The target part is the part built for the target hardware + and includes libraries and headers. + The host part is the part of the SDK that runs on the + SDKMACHINE. + + + + The do_populate_sdk_ext task helps + create the extensible SDK and handles host and target parts + differently than its counter part does for the standard SDK. + For the extensible SDK, the task encapsulates the build + system, which includes everything needed (host and target) + for the SDK. + + + + Regardless of the type of SDK being constructed, the + tasks perform some cleanup after which a cross-development + environment setup script and any needed configuration files + are created. + The final output is the Cross-development + toolchain installation script (.sh + file), which includes the environment setup script. + +
+ +
+ Stamp Files and the Rerunning of Tasks + + + For each task that completes successfully, BitBake writes a + stamp file into the + STAMPS_DIR + directory. + The beginning of the stamp file's filename is determined + by the + STAMP + variable, and the end of the name consists of the task's + name and current + input checksum. + + This naming scheme assumes that + BB_SIGNATURE_HANDLER + is "OEBasicHash", which is almost always the case in + current OpenEmbedded. + + To determine if a task needs to be rerun, BitBake checks + if a stamp file with a matching input checksum exists + for the task. + If such a stamp file exists, the task's output is + assumed to exist and still be valid. + If the file does not exist, the task is rerun. + + The stamp mechanism is more general than the + shared state (sstate) cache mechanism described in the + "Setscene Tasks and Shared State" + section. + BitBake avoids rerunning any task that has a valid + stamp file, not just tasks that can be accelerated + through the sstate cache. + + However, you should realize that stamp files only + serve as a marker that some work has been done and that + these files do not record task output. + The actual task output would usually be somewhere in + TMPDIR + (e.g. in some recipe's + WORKDIR.) + What the sstate cache mechanism adds is a way to cache + task output that can then be shared between build + machines. + + Since STAMPS_DIR is usually a + subdirectory of TMPDIR, removing + TMPDIR will also remove + STAMPS_DIR, which means tasks will + properly be rerun to repopulate + TMPDIR. + + + + If you want some task to always be considered "out of + date", you can mark it with the + nostamp + varflag. + If some other task depends on such a task, then that + task will also always be considered out of date, which + might not be what you want. + + + + For details on how to view information about a task's + signature, see the + "Viewing Task Variable Dependencies" + section in the Yocto Project Development Tasks Manual. + +
+ +
+ Setscene Tasks and Shared State + + + The description of tasks so far assumes that BitBake needs + to build everything and there are no prebuilt objects + available. + BitBake does support skipping tasks if prebuilt objects are + available. + These objects are usually made available in the form of a + shared state (sstate) cache. + + For information on variables affecting sstate, see the + SSTATE_DIR + and + SSTATE_MIRRORS + variables. + + + + + The idea of a setscene task (i.e + do_taskname_setscene) + is a version of the task where + instead of building something, BitBake can skip to the end + result and simply place a set of files into specific + locations as needed. + In some cases, it makes sense to have a setscene task + variant (e.g. generating package files in the + do_package_write_* + task). + In other cases, it does not make sense, (e.g. a + do_patch + task or + do_unpack + task) since the work involved would be equal to or greater + than the underlying task. + + + + In the OpenEmbedded build system, the common tasks that + have setscene variants are + do_package, + do_package_write_*, + do_deploy, + do_packagedata, + and + do_populate_sysroot. + Notice that these are most of the tasks whose output is an + end result. + + + + The OpenEmbedded build system has knowledge of the + relationship between these tasks and other tasks that + precede them. + For example, if BitBake runs + do_populate_sysroot_setscene for + something, there is little point in running any of the + do_fetch, + do_unpack, + do_patch, + do_configure, + do_compile, and + do_install tasks. + However, if do_package needs to be + run, BitBake would need to run those other tasks. + + + + It becomes more complicated if everything can come + from an sstate cache because some objects are simply + not required at all. + For example, you do not need a compiler or native tools, + such as quilt, if there is nothing to compile or patch. + If the do_package_write_* packages + are available from sstate, BitBake does not need the + do_package task data. + + + + To handle all these complexities, BitBake runs in two + phases. + The first is the "setscene" stage. + During this stage, BitBake first checks the sstate cache + for any targets it is planning to build. + BitBake does a fast check to see if the object exists + rather than a complete download. + If nothing exists, the second phase, which is the setscene + stage, completes and the main build proceeds. + + + + If objects are found in the sstate cache, the OpenEmbedded + build system works backwards from the end targets specified + by the user. + For example, if an image is being built, the OpenEmbedded + build system first looks for the packages needed for + that image and the tools needed to construct an image. + If those are available, the compiler is not needed. + Thus, the compiler is not even downloaded. + If something was found to be unavailable, or the + download or setscene task fails, the OpenEmbedded build + system then tries to install dependencies, such as the + compiler, from the cache. + + + + The availability of objects in the sstate cache is + handled by the function specified by the + BB_HASHCHECK_FUNCTION + variable and returns a list of the objects that are + available. + The function specified by the + BB_SETSCENE_DEPVALID + variable is the function that determines whether a given + dependency needs to be followed, and whether for any given + relationship the function needs to be passed. + The function returns a True or False value. + +
+
+ +
+ Images + + + The images produced by the OpenEmbedded build system + are compressed forms of the + root filesystem that are ready to boot on a target device. + You can see from the + general Build Process figure + that BitBake output, in part, consists of images. + This section is going to look more closely at this output: + + + + + For a list of example images that the Yocto Project provides, + see the + "Images" + chapter in the Yocto Project Reference Manual. + + + + Images are written out to the + Build Directory + inside the + tmp/deploy/images/machine/ + folder as shown in the figure. + This folder contains any files expected to be loaded on the + target device. + The + DEPLOY_DIR + variable points to the deploy directory, + while the + DEPLOY_DIR_IMAGE + variable points to the appropriate directory containing images + for the current configuration. + + + kernel-image: + A kernel binary file. + The + KERNEL_IMAGETYPE + variable setting determines the naming scheme for the + kernel image file. + Depending on that variable, the file could begin with + a variety of naming strings. + The + deploy/images/machine + directory can contain multiple image files for the + machine. + + + root-filesystem-image: + Root filesystems for the target device (e.g. + *.ext3 or + *.bz2 files). + The + IMAGE_FSTYPES + variable setting determines the root filesystem image + type. + The + deploy/images/machine + directory can contain multiple root filesystems for the + machine. + + + kernel-modules: + Tarballs that contain all the modules built for the + kernel. + Kernel module tarballs exist for legacy purposes and + can be suppressed by setting the + MODULE_TARBALL_DEPLOY + variable to "0". + The + deploy/images/machine + directory can contain multiple kernel module tarballs + for the machine. + + + bootloaders: + Bootloaders supporting the image, if applicable to the + target machine. + The deploy/images/machine + directory can contain multiple bootloaders for the + machine. + + + symlinks: + The + deploy/images/machine + folder contains a symbolic link that points to the + most recently built file for each machine. + These links might be useful for external scripts that + need to obtain the latest version of each file. + + + +
+ +
+ Application Development SDK + + + In the + general Yocto Project Development Environment figure, + the output labeled "Application Development SDK" represents an + SDK. + The SDK generation process differs depending on whether you + build a standard SDK (e.g. + bitbake -c populate_sdk imagename) + or an extensible SDK (e.g. + bitbake -c populate_sdk_ext imagename). + This section is going to take a closer look at this output: + + + + + The specific form of this output is a self-extracting + SDK installer (*.sh) that, when run, + installs the SDK, which consists of a cross-development + toolchain, a set of libraries and headers, and an SDK + environment setup script. + Running this installer essentially sets up your + cross-development environment. + You can think of the cross-toolchain as the "host" + part because it runs on the SDK machine. + You can think of the libraries and headers as the "target" + part because they are built for the target hardware. + The environment setup script is added so that you can + initialize the environment before using the tools. + + + Notes + + + The Yocto Project supports several methods by which + you can set up this cross-development environment. + These methods include downloading pre-built SDK + installers or building and installing your own SDK + installer. + + + For background information on cross-development + toolchains in the Yocto Project development + environment, see the + "Cross-Development Toolchain Generation" + section. + + + For information on setting up a cross-development + environment, see the + Yocto Project Application Development and the Extensible Software Development Kit (eSDK) + manual. + + + + + + Once built, the SDK installers are written out to the + deploy/sdk folder inside the + Build Directory + as shown in the figure at the beginning of this section. + Depending on the type of SDK, several variables exist that help + configure these files. + The following list shows the variables associated with + a standard SDK: + + + DEPLOY_DIR: + Points to the deploy + directory. + + + SDKMACHINE: + Specifies the architecture of the machine + on which the cross-development tools are run to + create packages for the target hardware. + + + SDKIMAGE_FEATURES: + Lists the features to include in the "target" part + of the SDK. + + + TOOLCHAIN_HOST_TASK: + Lists packages that make up the host + part of the SDK (i.e. the part that runs on + the SDKMACHINE). + When you use + bitbake -c populate_sdk imagename + to create the SDK, a set of default packages + apply. + This variable allows you to add more packages. + + + TOOLCHAIN_TARGET_TASK: + Lists packages that make up the target part + of the SDK (i.e. the part built for the + target hardware). + + + SDKPATH: + Defines the default SDK installation path offered + by the installation script. + + + This next list, shows the variables associated with an + extensible SDK: + + + DEPLOY_DIR: + Points to the deploy directory. + + + SDK_EXT_TYPE: + Controls whether or not shared state artifacts are + copied into the extensible SDK. + By default, all required shared state artifacts are + copied into the SDK. + + + SDK_INCLUDE_PKGDATA: + Specifies whether or not packagedata will be + included in the extensible SDK for all recipes in + the "world" target. + + + SDK_INCLUDE_TOOLCHAIN: + Specifies whether or not the toolchain will be included + when building the extensible SDK. + + + SDK_LOCAL_CONF_WHITELIST: + A list of variables allowed through from the build + system configuration into the extensible SDK + configuration. + + + SDK_LOCAL_CONF_BLACKLIST: + A list of variables not allowed through from the build + system configuration into the extensible SDK + configuration. + + + SDK_INHERIT_BLACKLIST: + A list of classes to remove from the + INHERIT + value globally within the extensible SDK configuration. + + + +
+
+ +
+ Cross-Development Toolchain Generation + + + The Yocto Project does most of the work for you when it comes to + creating + cross-development toolchains. + This section provides some technical background on how + cross-development toolchains are created and used. + For more information on toolchains, you can also see the + Yocto Project Application Development and the Extensible Software Development Kit (eSDK) + manual. + + + + In the Yocto Project development environment, cross-development + toolchains are used to build the image and applications that run + on the target hardware. + With just a few commands, the OpenEmbedded build system creates + these necessary toolchains for you. + + + + The following figure shows a high-level build environment regarding + toolchain construction and use. + + + + + + + + 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 + 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. + + The extensible SDK does not use + gcc-cross-canadian since this SDK + ships a copy of the OpenEmbedded build system and the sysroot + within it contains gcc-cross. + + + + + The chain of events that occurs when gcc-cross is + bootstrapped is as follows: + + gcc -> binutils-cross -> gcc-cross-initial -> linux-libc-headers -> glibc-initial -> glibc -> gcc-cross -> gcc-runtime + + + + gcc: + The build host's GNU Compiler Collection (GCC). + + + binutils-cross: + The bare minimum binary utilities needed in order to run + the gcc-cross-initial phase of the + bootstrap operation. + + + gcc-cross-initial: + An early stage of the bootstrap process for creating + the cross-compiler. + This stage builds enough of the gcc-cross, + the C library, and other pieces needed to finish building the + final cross-compiler in later stages. + This tool is a "native" package (i.e. it is designed to run on + the build host). + + + linux-libc-headers: + Headers needed for the cross-compiler. + + + glibc-initial: + An initial version of the Embedded GLIBC needed to bootstrap + glibc. + + + gcc-cross: + The final stage of the bootstrap process for the + cross-compiler. + This stage results in the actual cross-compiler that + BitBake uses when it builds an image for a targeted + device. + + If you are replacing this cross compiler toolchain + with a custom version, you must replace + gcc-cross. + + This tool is also a "native" package (i.e. it is + designed to run on the build host). + + + gcc-runtime: + Runtime libraries resulting from the toolchain bootstrapping + process. + This tool produces a binary that consists of the + runtime libraries need for the targeted device. + + + + + + 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., + gcc-cross-canadian, + binutils-cross-canadian, and other + nativesdk-* tools), + which are tools native to the SDK (i.e. native to + SDK_ARCH), + you need to cross-compile and test your software. + The figure shows the commands you use to easily build out this + toolchain. + This cross-development toolchain is built to execute on the + SDKMACHINE, + which might or might not be the same + machine as the Build Host. + + If your target architecture is supported by the Yocto Project, + you can take advantage of pre-built images that ship with the + Yocto Project and already contain cross-development toolchain + installers. + + + + + Here is the bootstrap process for the relocatable toolchain: + + gcc -> binutils-crosssdk -> gcc-crosssdk-initial -> linux-libc-headers -> + glibc-initial -> nativesdk-glibc -> gcc-crosssdk -> gcc-cross-canadian + + + + gcc: + The build host's GNU Compiler Collection (GCC). + + + binutils-crosssdk: + The bare minimum binary utilities needed in order to run + the gcc-crosssdk-initial phase of the + bootstrap operation. + + + gcc-crosssdk-initial: + An early stage of the bootstrap process for creating + the cross-compiler. + This stage builds enough of the + gcc-crosssdk and supporting pieces so that + the final stage of the bootstrap process can produce the + finished cross-compiler. + This tool is a "native" binary that runs on the build host. + + + linux-libc-headers: + Headers needed for the cross-compiler. + + + glibc-initial: + An initial version of the Embedded GLIBC needed to bootstrap + nativesdk-glibc. + + + nativesdk-glibc: + The Embedded GLIBC needed to bootstrap the + gcc-crosssdk. + + + gcc-crosssdk: + The final stage of the bootstrap process for the + relocatable cross-compiler. + The gcc-crosssdk is a transitory compiler + and never leaves the build host. + Its purpose is to help in the bootstrap process to create the + eventual relocatable gcc-cross-canadian + compiler, which is relocatable. + This tool is also a "native" package (i.e. it is + designed to run on the build host). + + + gcc-cross-canadian: + The final relocatable cross-compiler. + When run on the + SDKMACHINE, + this tool + produces executable code that runs on the target device. + Only one cross-canadian compiler is produced per architecture + since they can be targeted at different processor optimizations + using configurations passed to the compiler through the + compile commands. + This circumvents the need for multiple compilers and thus + reduces the size of the toolchains. + + + + + + For information on advantages gained when building a + cross-development toolchain installer, see the + "Building an SDK Installer" + section in the Yocto Project Application Development and the + Extensible Software Development Kit (eSDK) manual. + +
+ +
+ Shared State Cache + + + By design, the OpenEmbedded build system builds everything from + 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. + When developers hit problems, they typically default back to + building from scratch so they know the state of things from the + start. + + + + Building an image from scratch is both an advantage and a + disadvantage to the process. + As mentioned in the previous paragraph, building from scratch + ensures that everything is current and starts from a known state. + However, building from scratch also takes much longer as it + generally means rebuilding things that do not necessarily need + to be rebuilt. + + + + The Yocto Project implements shared state code that supports + incremental builds. + The implementation of the shared state code answers the following + questions that were fundamental roadblocks within the OpenEmbedded + incremental build support system: + + + What pieces of the system have changed and what pieces have + not changed? + + + How are changed pieces of software removed and replaced? + + + How are pre-built components that do not need to be rebuilt + from scratch used when they are available? + + + + + + 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 + which tasks add which output to the build process. + This means the output from a given task can be removed, upgraded + or otherwise manipulated. + The third question is partly addressed by the solution for the + second question assuming the build system can fetch the sstate + objects from remote locations and install them if they are deemed + to be valid. + + The OpenEmbedded build system does not maintain + PR + information as part of the shared state packages. + Consequently, considerations exist that affect maintaining + shared state feeds. + For information on how the OpenEmbedded build system + works with packages and can track incrementing + PR information, see the + "Automatically Incrementing a Binary Package Revision Number" + section in the Yocto Project Development Tasks Manual. + + + + + The rest of this section goes into detail about the overall + incremental build architecture, the checksums (signatures), shared + state, and some tips and tricks. + + +
+ Overall Architecture + + + When determining what parts of the system need to be built, + BitBake works on a per-task basis rather than a per-recipe + basis. + You might wonder why using a per-task basis is preferred over + a per-recipe basis. + To help explain, consider having the IPK packaging backend + enabled and then switching to DEB. + In this case, the + do_install + and + do_package + task outputs are still valid. + However, with a per-recipe approach, the build would not + include the .deb files. + Consequently, you would have to invalidate the whole build and + rerun it. + Rerunning everything is not the best solution. + Also, in this case, the core must be "taught" much about + specific tasks. + This methodology does not scale well and does not allow users + to easily add new tasks in layers or as external recipes + without touching the packaged-staging core. + +
+ +
+ Checksums (Signatures) + + + The shared state code uses a checksum, which is a unique + signature of a task's inputs, to determine if a task needs to + be run again. + Because it is a change in a task's inputs that triggers a + rerun, the process needs to detect all the inputs to a given + task. + For shell tasks, this turns out to be fairly easy because + the build process generates a "run" shell script for each task + and it is possible to create a checksum that gives you a good + idea of when the task's data changes. + + + + To complicate the problem, there are things that should not be + included in the checksum. + First, there is the actual specific build path of a given + task - the + WORKDIR. + It does not matter if the work directory changes because it + should not affect the output for target packages. + Also, the build process has the objective of making native + or cross packages relocatable. + + Both native and cross packages run on the + build host. + However, cross packages generate output for the target + architecture. + + The checksum therefore needs to exclude + WORKDIR. + The simplistic approach for excluding the work directory is to + set WORKDIR to some fixed value and + create the checksum for the "run" script. + + + + Another problem results from the "run" scripts containing + functions that might or might not get called. + The incremental build solution contains code that figures out + dependencies between shell functions. + This code is used to prune the "run" scripts down to the + minimum set, thereby alleviating this problem and making the + "run" scripts much more readable as a bonus. + + + + So far, solutions for shell scripts exist. + What about Python tasks? + The same approach applies even though these tasks are more + difficult. + The process needs to figure out what variables a Python + function accesses and what functions it calls. + Again, the incremental build solution contains code that first + figures out the variable and function dependencies, and then + creates a checksum for the data used as the input to the task. + + + + Like the WORKDIR case, situations exist + where dependencies should be ignored. + For these situations, you can instruct the build process to + ignore a dependency by using a line like the following: + + PACKAGE_ARCHS[vardepsexclude] = "MACHINE" + + This example ensures that the + PACKAGE_ARCHS + variable does not depend on the value of + MACHINE, + even if it does reference it. + + + + 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: + + PACKAGE_ARCHS[vardeps] = "MACHINE" + + This example explicitly adds the MACHINE + variable as a dependency for + PACKAGE_ARCHS. + + + + 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 + discovers something for which it cannot figure out dependencies. + The Yocto Project team has currently not managed to cover + those dependencies in detail and is aware of the need to fix + this situation. + + + + Thus far, this section has limited discussion to the direct + inputs into a task. + 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. + 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. + However, the effect is to generate a master checksum that + combines the basehash and the hashes of the task's + dependencies. + + + + 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, 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 + included in any checksum: + + BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH DL_DIR \ + SSTATE_DIR THISDIR FILESEXTRAPATHS FILE_DIRNAME HOME LOGNAME SHELL TERM \ + USER FILESPATH STAGING_DIR_HOST STAGING_DIR_TARGET COREBASE PRSERV_HOST \ + PRSERV_DUMPDIR PRSERV_DUMPFILE PRSERV_LOCKDOWN PARALLEL_MAKE \ + CCACHE_DIR EXTERNAL_TOOLCHAIN CCACHE CCACHE_DISABLE LICENSE_PATH SDKPKGSUFFIX" + + The previous example excludes + WORKDIR + since that variable is actually constructed as a path within + TMPDIR, + which is on the whitelist. + + + + The rules for deciding which hashes of dependent tasks to + include through dependency chains are more complex and are + generally accomplished with a Python function. + The code in meta/lib/oe/sstatesig.py shows + two examples of this and also illustrates how you can insert + your own policy into the system if so desired. + This file defines the two basic signature generators + OE-Core + uses: "OEBasic" and "OEBasicHash". + By default, there is a dummy "noop" signature handler enabled + in BitBake. + This means that behavior is unchanged from previous versions. + OE-Core uses the "OEBasicHash" signature handler by default + through this setting in the bitbake.conf + file: + + BB_SIGNATURE_HANDLER ?= "OEBasicHash" + + The "OEBasicHash" BB_SIGNATURE_HANDLER + is the same as the "OEBasic" version but adds the task hash to + the stamp files. + This results in any + Metadata + change that changes the task hash, automatically + causing the task to be run again. + This removes the need to bump + PR + values, and changes to Metadata automatically ripple across + the build. + + + + It is also worth noting that the end result of these + signature generators is to make some dependency and hash + information available to the build. + This information includes: + + + BB_BASEHASH_task-taskname: + The base hashes for each task in the recipe. + + + BB_BASEHASH_filename:taskname: + The base hashes for each dependent task. + + + BBHASHDEPS_filename:taskname: + The task dependencies for each task. + + + BB_TASKHASH: + The hash of the currently running task. + + + +
+ +
+ Shared State + + + Checksums and dependencies, as discussed in the previous + section, solve half the problem of supporting a shared state. + The other part of the problem is being able to use checksum + information during the build and being able to reuse or rebuild + specific components. + + + + The + sstate + class is a relatively generic implementation of how to + "capture" a snapshot of a given task. + The idea is that the build process does not care about the + source of a task's output. + Output could be freshly built or it could be downloaded and + unpacked from somewhere - the build process does not need to + worry about its origin. + + + + 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 + or + do_package. + The other type of output occurs when a set of data is merged + into a shared directory tree such as the sysroot. + + + + The Yocto Project team has tried to keep the details of the + implementation hidden in sstate class. + From a user's perspective, adding shared state wrapping to a task + is as simple as this + do_deploy + example taken from the + deploy + class: + + DEPLOYDIR = "${WORKDIR}/deploy-${PN}" + SSTATETASKS += "do_deploy" + do_deploy[sstate-inputdirs] = "${DEPLOYDIR}" + do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}" + + python do_deploy_setscene () { + sstate_setscene(d) + } + addtask do_deploy_setscene + do_deploy[dirs] = "${DEPLOYDIR} ${B}" + + The following list explains the previous example: + + + Adding "do_deploy" to SSTATETASKS + adds some required sstate-related processing, which is + implemented in the + sstate + class, to before and after the + do_deploy + task. + + + The + do_deploy[sstate-inputdirs] = "${DEPLOYDIR}" + declares that do_deploy places its + output in ${DEPLOYDIR} when run + normally (i.e. when not using the sstate cache). + This output becomes the input to the shared state cache. + + + The + do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}" + line causes the contents of the shared state cache to be + copied to ${DEPLOY_DIR_IMAGE}. + + If do_deploy is not already in + the shared state cache or if its input checksum + (signature) has changed from when the output was + cached, the task will be run to populate the shared + state cache, after which the contents of the shared + state cache is copied to + ${DEPLOY_DIR_IMAGE}. + If do_deploy is in the shared + state cache and its signature indicates that the + cached output is still valid (i.e. if no + relevant task inputs have changed), then the + contents of the shared state cache will be copied + directly to + ${DEPLOY_DIR_IMAGE} by the + do_deploy_setscene task + instead, skipping the + do_deploy task. + + + + The following task definition is glue logic needed to + make the previous settings effective: + + python do_deploy_setscene () { + sstate_setscene(d) + } + addtask do_deploy_setscene + + sstate_setscene() takes the flags + above as input and accelerates the + do_deploy task through the + shared state cache if possible. + If the task was accelerated, + sstate_setscene() returns True. + Otherwise, it returns False, and the normal + do_deploy task runs. + For more information, see the + "setscene" + section in the BitBake User Manual. + + + The do_deploy[dirs] = "${DEPLOYDIR} ${B}" + line creates ${DEPLOYDIR} and + ${B} before the + do_deploy task runs, and also sets + the current working directory of + do_deploy to + ${B}. + For more information, see the + "Variable Flags" + section in the BitBake User Manual. + + In cases where + sstate-inputdirs and + sstate-outputdirs would be the + same, you can use + sstate-plaindirs. + For example, to preserve the + ${PKGD} and + ${PKGDEST} output from the + do_package + task, use the following: + + do_package[sstate-plaindirs] = "${PKGD} ${PKGDEST}" + + + + + sstate-inputdirs and + sstate-outputdirs can also be used + with multiple directories. + For example, the following declares + PKGDESTWORK and + SHLIBWORK as shared state + input directories, which populates the shared state + cache, and PKGDATA_DIR and + SHLIBSDIR as the corresponding + shared state output directories: + + do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}" + do_package[sstate-outputdirs] = "${PKGDATA_DIR} ${SHLIBSDIR}" + + + + These methods also include the ability to take a + lockfile when manipulating shared state directory + structures, for cases where file additions or removals + are sensitive: + + do_package[sstate-lockfile] = "${PACKAGELOCK}" + + + + + + + Behind the scenes, the shared state code works by looking in + SSTATE_DIR + and + SSTATE_MIRRORS + for shared state files. + Here is an example: + + SSTATE_MIRRORS ?= "\ + file://.* http://someserver.tld/share/sstate/PATH;downloadfilename=PATH \n \ + file://.* file:///some/local/dir/sstate/PATH" + + + The shared state directory + (SSTATE_DIR) is organized into + two-character subdirectories, where the subdirectory + names are based on the first two characters of the hash. + If the shared state directory structure for a mirror has the + same structure as SSTATE_DIR, you must + specify "PATH" as part of the URI to enable the build system + to map to the appropriate subdirectory. + + + + + The shared state package validity can be detected just by + looking at the filename since the filename contains the task + checksum (or signature) as described earlier in this section. + If a valid shared state package is found, the build process + downloads it and uses it to accelerate the task. + + + + The build processes use the *_setscene + tasks for the task acceleration phase. + BitBake goes through this phase before the main execution + code and tries to accelerate any tasks for which it can find + shared state packages. + If a shared state package for a task is available, the + shared state package is used. + This means the task and any tasks on which it is dependent + are not executed. + + + + As a real world example, the aim is when building an IPK-based + image, only the + do_package_write_ipk + tasks would have their shared state packages fetched and + extracted. + Since the sysroot is not used, it would never get extracted. + This is another reason why a task-based approach is preferred + over a recipe-based approach, which would have to install the + output from every task.n + +
+ +
+ Tips and Tricks + + + The code in the build system that supports incremental builds + is not simple code. + This section presents some tips and tricks that help you work + around issues related to shared state code. + + +
+ Debugging + + + Seeing what metadata went into creating the input signature + of a shared state (sstate) task can be a useful debugging + aid. + This information is available in signature information + (siginfo) files in + SSTATE_DIR. + For information on how to view and interpret information in + siginfo files, see the + "Viewing Task Variable Dependencies" + section in the Yocto Project Development Tasks Manual. + +
+ +
+ Invalidating Shared State + + + The OpenEmbedded build system uses checksums and shared + state cache to avoid unnecessarily rebuilding tasks. + Collectively, this scheme is known as "shared state code." + + + + As with all schemes, this one has some drawbacks. + It is possible that you could make implicit changes to your + code that the checksum calculations do not take into + account. + These implicit changes affect a task's output but do not + trigger the shared state code into rebuilding a recipe. + Consider an example during which a tool changes its output. + Assume that the output of rpmdeps + changes. + The result of the change should be that all the + package and + package_write_rpm shared state cache + items become invalid. + However, because the change to the output is + external to the code and therefore implicit, + the associated shared state cache items do not become + invalidated. + In this case, the build process uses the cached items + rather than running the task again. + Obviously, these types of implicit changes can cause + problems. + + + + To avoid these problems during the build, you need to + understand the effects of any changes you make. + Realize that changes you make directly to a function + are automatically factored into the checksum calculation. + Thus, these explicit changes invalidate the associated + area of shared state cache. + However, you need to be aware of any implicit changes that + are not obvious changes to the code and could affect + the output of a given task. + + + + When you identify an implicit change, you can easily + take steps to invalidate the cache and force the tasks + to run. + The steps you can take are as simple as changing a + function's comments in the source code. + For example, to invalidate package shared state files, + change the comment statements of + do_package + or the comments of one of the functions it calls. + Even though the change is purely cosmetic, it causes the + checksum to be recalculated and forces the OpenEmbedded + build system to run the task again. + + For an example of a commit that makes a cosmetic + change to invalidate shared state, see this + commit. + + +
+
+
+ +
+ Automatically Added Runtime Dependencies + + + The OpenEmbedded build system automatically adds common types of + runtime dependencies between packages, which means that you do not + need to explicitly declare the packages using + RDEPENDS. + Three automatic mechanisms exist (shlibdeps, + pcdeps, and depchains) + that handle shared libraries, package configuration (pkg-config) + modules, and -dev and + -dbg packages, respectively. + For other types of runtime dependencies, you must manually declare + the dependencies. + + + shlibdeps: + During the + do_package + task of each recipe, all shared libraries installed by the + recipe are located. + For each shared library, the package that contains the + shared library is registered as providing the shared + library. + More specifically, the package is registered as providing + the + soname + of the library. + The resulting shared-library-to-package mapping + is saved globally in + PKGDATA_DIR + by the + do_packagedata + task. + + Simultaneously, all executables and shared libraries + installed by the recipe are inspected to see what shared + libraries they link against. + For each shared library dependency that is found, + PKGDATA_DIR is queried to + see if some package (likely from a different recipe) + contains the shared library. + If such a package is found, a runtime dependency is added + from the package that depends on the shared library to the + package that contains the library. + + The automatically added runtime dependency also + includes a version restriction. + This version restriction specifies that at least the + current version of the package that provides the shared + library must be used, as if + "package (>= version)" + 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. + + If you want to avoid a package being registered as + providing a particular shared library (e.g. because the library + is for internal use only), then add the library to + PRIVATE_LIBS + inside the package's recipe. + + + pcdeps: + 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. + + Simultaneously, all pkg-config modules installed by + the recipe are inspected to see what other pkg-config + modules they depend on. + A module is seen as depending on another module if it + contains a "Requires:" line that specifies the other module. + For each module dependency, + PKGDATA_DIR is queried to see if some + package contains the module. + If such a package is found, a runtime dependency is added + from the package that depends on the module to the package + that contains the module. + + The pcdeps mechanism most often + infers dependencies between -dev + packages. + + + + depchains: + If a package foo depends on a package + bar, then foo-dev + and foo-dbg are also made to depend on + bar-dev and + bar-dbg, respectively. + Taking the -dev packages as an + example, the bar-dev package might + provide headers and shared library symlinks needed by + foo-dev, which shows the need + for a dependency between the packages. + + The dependencies added by + depchains are in the form of + RRECOMMENDS. + + By default, foo-dev also has an + RDEPENDS-style dependency on + foo, because the default value of + RDEPENDS_${PN}-dev (set in + bitbake.conf) includes + "${PN}". + + + To ensure that the dependency chain is never broken, + -dev and -dbg + packages are always generated by default, even if the + packages turn out to be empty. + See the + ALLOW_EMPTY + variable for more information. + + + + + + The do_package task depends on the + do_packagedata task of each recipe in + DEPENDS + through use of a + [deptask] + declaration, which guarantees that the required + shared-library/module-to-package mapping information will be available + when needed as long as DEPENDS has been + correctly set. + +
+ +
+ Fakeroot and Pseudo + + + Some tasks are easier to implement when allowed to perform certain + operations that are normally reserved for the root user (e.g. + do_install, + do_package_write*, + do_rootfs, + and + do_image*). + For example, the do_install task benefits + from being able to set the UID and GID of installed files to + arbitrary values. + + + + One approach to allowing tasks to perform root-only operations + 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. + Within this environment, the task and its child processes believe + that they are running as the root user, and see an internally + consistent view of the filesystem. + As long as generating the final output (e.g. a package or an image) + does not require root privileges, the fact that some earlier + steps ran in a fake root environment does not cause problems. + + + + The capability to run tasks in a fake root environment is known as + "fakeroot", + which is derived from the BitBake keyword/variable + flag that requests a fake root environment for a task. + + + + 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. + To keep track of "fake" file ownership and permissions resulting + from operations that require root permissions, Pseudo uses + an SQLite 3 database. + This database is stored in + ${WORKDIR}/pseudo/files.db + for individual recipes. + Storing the database in a file as opposed to in memory + gives persistence between tasks and builds, which is not + accomplished using fakeroot. + Caution + If you add your own task that manipulates the same files or + directories as a fakeroot task, then that task also needs to + run under fakeroot. + Otherwise, the task cannot run root-only operations, and + cannot see the fake file ownership and permissions set by the + other task. + You need to also add a dependency on + virtual/fakeroot-native:do_populate_sysroot, + giving the following: + + fakeroot do_mytask () { + ... + } + do_mytask[depends] += "virtual/fakeroot-native:do_populate_sysroot" + + + For more information, see the + FAKEROOT* + variables in the BitBake User Manual. + You can also reference the + "Pseudo" + and + "Why Not Fakeroot?" + articles for background information on Pseudo. + +
+ +
+ Wayland + + + Wayland + is a computer display server protocol that + provides a method for compositing window managers to communicate + directly with applications and video hardware and expects them to + communicate with input hardware using other libraries. + Using Wayland with supporting targets can result in better control + over graphics frame rendering than an application might otherwise + achieve. + + + + The Yocto Project provides the Wayland protocol libraries and the + reference + Weston + compositor as part of its release. + This section describes what you need to do to implement Wayland and + use the compositor when building an image for a supporting target. + + +
+ Support + + + The Wayland protocol libraries and the reference Weston + compositor ship as integrated packages in the + meta layer of the + Source Directory. + Specifically, you can find the recipes that build both Wayland + and Weston at + meta/recipes-graphics/wayland. + + + + You can build both the Wayland and Weston packages for use only + with targets that accept the + Mesa 3D and Direct Rendering Infrastructure, + which is also known as Mesa DRI. + This implies that you cannot build and use the packages if your + target uses, for example, the + Intel Embedded Media + and Graphics Driver + (Intel EMGD) that + overrides Mesa DRI. + + Due to lack of EGL support, Weston 1.0.3 will not run + directly on the emulated QEMU hardware. + However, this version of Weston will run under X emulation + without issues. + + +
+ +
+ Enabling Wayland in an Image + + + To enable Wayland, you need to enable it to be built and enable + it to be included in the image. + + +
+ Building + + + To cause Mesa to build the wayland-egl + platform and Weston to build Wayland with Kernel Mode + Setting + (KMS) + support, include the "wayland" flag in the + DISTRO_FEATURES + statement in your local.conf file: + + DISTRO_FEATURES_append = " wayland" + + + If X11 has been enabled elsewhere, Weston will build + Wayland with X11 support + + +
+ +
+ Installing + + + To install the Wayland feature into an image, you must + include the following + CORE_IMAGE_EXTRA_INSTALL + statement in your local.conf file: + + CORE_IMAGE_EXTRA_INSTALL += "wayland weston" + + +
+
+ +
+ Running Weston + + + To run Weston inside X11, enabling it as described earlier and + building a Sato image is sufficient. + If you are running your image under Sato, a Weston Launcher + appears in the "Utility" category. + + + + Alternatively, you can run Weston through the command-line + interpretor (CLI), which is better suited for development work. + To run Weston under the CLI, you need to do the following after + your image is built: + + + Run these commands to export + XDG_RUNTIME_DIR: + + mkdir -p /tmp/$USER-weston + chmod 0700 /tmp/$USER-weston + export XDG_RUNTIME_DIR=/tmp/$USER-weston + + + + Launch Weston in the shell: + + weston + + + +
+
+ +
+ Licenses + + + 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. + + + + 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 Tasks Manual. + + +
+ Tracking License Changes + + + The license of an upstream project might change in the future. + In order to prevent these changes going unnoticed, the + LIC_FILES_CHKSUM + variable tracks changes to the license text. The checksums are + validated at the end of the configure step, and if the + checksums do not match, the build will fail. + + +
+ Specifying the <filename>LIC_FILES_CHKSUM</filename> Variable + + + The LIC_FILES_CHKSUM + variable contains checksums of the license text in the + source code for the recipe. + Following is an example of how to specify + LIC_FILES_CHKSUM: + + LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \ + file://licfile1.txt;beginline=5;endline=29;md5=yyyy \ + file://licfile2.txt;endline=50;md5=zzzz \ + ..." + + Notes + + + When using "beginline" and "endline", realize + that line numbering begins with one and not + zero. + Also, the included lines are inclusive (i.e. + lines five through and including 29 in the + previous example for + licfile1.txt). + + + When a license check fails, the selected license + text is included as part of the QA message. + Using this output, you can determine the exact + start and finish for the needed license text. + + + + + + + The build system uses the + S + variable as the default directory when searching files + listed in LIC_FILES_CHKSUM. + The previous example employs the default directory. + + + + Consider this next example: + + LIC_FILES_CHKSUM = "file://src/ls.c;beginline=5;endline=16;\ + md5=bb14ed3c4cda583abc85401304b5cd4e" + LIC_FILES_CHKSUM = "file://${WORKDIR}/license.html;md5=5c94767cedb5d6987c902ac850ded2c6" + + + + + The first line locates a file in + ${S}/src/ls.c and isolates lines five + through 16 as license text. + The second line refers to a file in + WORKDIR. + + + + Note that LIC_FILES_CHKSUM variable is + mandatory for all recipes, unless the + LICENSE variable is set to "CLOSED". + +
+ +
+ Explanation of Syntax + + + As mentioned in the previous section, the + LIC_FILES_CHKSUM variable lists all + the important files that contain the license text for the + source code. + It is possible to specify a checksum for an entire file, + or a specific section of a file (specified by beginning and + ending line numbers with the "beginline" and "endline" + parameters, respectively). + The latter is useful for source files with a license + notice header, README documents, and so forth. + If you do not use the "beginline" parameter, then it is + assumed that the text begins on the first line of the file. + Similarly, if you do not use the "endline" parameter, + it is assumed that the license text ends with the last + line of the file. + + + + The "md5" parameter stores the md5 checksum of the license + text. + If the license text changes in any way as compared to + this parameter then a mismatch occurs. + This mismatch triggers a build failure and notifies + the developer. + Notification allows the developer to review and address + the license text changes. + Also note that if a mismatch occurs during the build, + the correct md5 checksum is placed in the build log and + can be easily copied to the recipe. + + + + There is no limit to how many files you can specify using + the LIC_FILES_CHKSUM variable. + Generally, however, every project requires a few + specifications for license tracking. + Many projects have a "COPYING" file that stores the + license information for all the source code files. + This practice allows you to just track the "COPYING" + file as long as it is kept up to date. + Tips + + + If you specify an empty or invalid "md5" + 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 + the build log. + + + If the whole file contains only license text, + you do not need to use the "beginline" and + "endline" parameters. + + + + +
+
+ +
+ Enabling Commercially Licensed Recipes + + + By default, the OpenEmbedded build system disables + components that have commercial or other special licensing + requirements. + Such requirements are defined on a + recipe-by-recipe basis through the + LICENSE_FLAGS + variable definition in the affected recipe. + For instance, the + poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly + recipe contains the following statement: + + LICENSE_FLAGS = "commercial" + + Here is a slightly more complicated example that contains both + an explicit recipe name and version (after variable expansion): + + LICENSE_FLAGS = "license_${PN}_${PV}" + + In order for a component restricted by a + LICENSE_FLAGS definition to be enabled and + included in an image, it needs to have a matching entry in the + global + LICENSE_FLAGS_WHITELIST + variable, which is a variable typically defined in your + local.conf file. + For example, to enable the + poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly + package, you could add either the string + "commercial_gst-plugins-ugly" or the more general string + "commercial" to LICENSE_FLAGS_WHITELIST. + See the + "License Flag Matching" + section for a full + explanation of how LICENSE_FLAGS matching + works. + Here is the example: + + LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly" + + Likewise, to additionally enable the package built from the + recipe containing + LICENSE_FLAGS = "license_${PN}_${PV}", + and assuming that the actual recipe name was + emgd_1.10.bb, the following string would + enable that package as well as the original + gst-plugins-ugly package: + + LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly license_emgd_1.10" + + As a convenience, you do not need to specify the complete + license string in the whitelist for every package. + You can use an abbreviated form, which consists + of just the first portion or portions of the license + string before the initial underscore character or characters. + A partial string will match any license that contains the + given string as the first portion of its license. + For example, the following whitelist string will also match + both of the packages previously mentioned as well as any other + packages that have licenses starting with "commercial" or + "license". + + LICENSE_FLAGS_WHITELIST = "commercial license" + + + +
+ License Flag Matching + + + 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 + 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 + system to exclude a recipe. + + + + In general, license flag matching is simple. + However, understanding some concepts will help you + correctly and effectively use matching. + + + + Before a flag + defined by a particular recipe is tested against the + contents of the whitelist, the expanded string + _${PN} is appended to the flag. + This expansion makes each + LICENSE_FLAGS value recipe-specific. + After expansion, the string is then matched against the + whitelist. + Thus, specifying + LICENSE_FLAGS = "commercial" + in recipe "foo", for example, results in the string + "commercial_foo". + And, to create a match, that string must appear in the + whitelist. + + + + Judicious use of the LICENSE_FLAGS + strings and the contents of the + LICENSE_FLAGS_WHITELIST variable + allows you a lot of flexibility for including or excluding + recipes based on licensing. + For example, you can broaden the matching capabilities by + using license flags string subsets in the whitelist. + + When using a string subset, be sure to use the part of + the expanded string that precedes the appended + underscore character (e.g. + usethispart_1.3, + usethispart_1.4, and so forth). + + For example, simply specifying the string "commercial" in + the whitelist matches any expanded + LICENSE_FLAGS definition that starts + with the string "commercial" such as "commercial_foo" and + "commercial_bar", which are the strings the build system + automatically generates for hypothetical recipes named + "foo" and "bar" assuming those recipes simply specify the + following: + + LICENSE_FLAGS = "commercial" + + Thus, you can choose to exhaustively + enumerate each license flag in the whitelist and + allow only specific recipes into the image, or + you can use a string subset that causes a broader range of + matches to allow a range of recipes into the image. + + + + This scheme works even if the + LICENSE_FLAGS string already + has _${PN} appended. + For example, the build system turns the license flag + "commercial_1.2_foo" into "commercial_1.2_foo_foo" and + would match both the general "commercial" and the specific + "commercial_1.2_foo" strings found in the whitelist, as + expected. + + + + Here are some other scenarios: + + + You can specify a versioned string in the recipe + such as "commercial_foo_1.2" in a "foo" recipe. + The build system expands this string to + "commercial_foo_1.2_foo". + Combine this license flag with a whitelist that has + the string "commercial" and you match the flag + along with any other flag that starts with the + string "commercial". + + + Under the same circumstances, you can use + "commercial_foo" in the whitelist and the build + system not only matches "commercial_foo_1.2" but + also matches any license flag with the string + "commercial_foo", regardless of the version. + + + You can be very specific and use both the + package and version parts in the whitelist (e.g. + "commercial_foo_1.2") to specifically match a + versioned recipe. + + + +
+ + +
+
+ + diff --git a/documentation/overview-manual/overview-manual-customization.xsl b/documentation/overview-manual/overview-manual-customization.xsl new file mode 100644 index 0000000000..22360e7bab --- /dev/null +++ b/documentation/overview-manual/overview-manual-customization.xsl @@ -0,0 +1,27 @@ + + + + + + + + + + + + + + + + + + + + + diff --git a/documentation/overview-manual/overview-manual-development-environment.xml b/documentation/overview-manual/overview-manual-development-environment.xml new file mode 100644 index 0000000000..7bcf87ffd9 --- /dev/null +++ b/documentation/overview-manual/overview-manual-development-environment.xml @@ -0,0 +1,972 @@ + %poky; ] > + + +The Yocto Project Development Environment + + + This chapter takes a look at the Yocto Project development + environment. + The chapter provides Yocto Project Development environment concepts that + help you understand how work is accomplished in an open source environment, + which is very different as compared to work accomplished in a closed, + proprietary environment. + + + + Specifically, this chapter addresses open source philosophy, source + repositories, workflows, Git, and licensing. + + +
+ Open Source Philosophy + + + Open source philosophy is characterized by software development + directed by peer production and collaboration through an active + community of developers. + Contrast this to the more standard centralized development models + used by commercial software companies where a finite set of developers + produces a product for sale using a defined set of procedures that + ultimately result in an end product whose architecture and source + material are closed to the public. + + + + Open source projects conceptually have differing concurrent agendas, + approaches, and production. + These facets of the development process can come from anyone in the + public (community) who has a stake in the software project. + The open source environment contains new copyright, licensing, domain, + and consumer issues that differ from the more traditional development + environment. + In an open source environment, the end product, source material, + and documentation are all available to the public at no cost. + + + + A benchmark example of an open source project is the Linux kernel, + which was initially conceived and created by Finnish computer science + student Linus Torvalds in 1991. + Conversely, a good example of a non-open source project is the + Windows family of operating + systems developed by + Microsoft Corporation. + + + + Wikipedia has a good historical description of the Open Source + Philosophy + here. + You can also find helpful information on how to participate in the + Linux Community + here. + +
+ +
+ The Development Host + + + A development host or build host is key to using the Yocto Project. + Because the goal of the Yocto Project is to develop images or + applications that run on embedded hardware, development of those + images and applications generally takes place on a system not + intended to run the software - the development host. + + + + You need to set up a development host in order to use it with the + Yocto Project. + Most find that it is best to have a native Linux machine function as + the development host. + However, it is possible to use a system that does not run Linux + as its operating system as your development host. + When you have a Mac or Windows-based system, you can set it up + as the development host by using + CROPS, + which leverages + Docker Containers. + Once you take the steps to set up a CROPS machine, you effectively + have access to a shell environment that is similar to what you see + when using a Linux-based development host. + For the steps needed to set up a system using CROPS, see the + "Setting Up to Use CROss PlatformS (CROPS)" + section in the Yocto Project Development Tasks Manual. + + + + If your development host is going to be a system that runs a Linux + distribution, steps still exist that you must take to prepare the + system for use with the Yocto Project. + You need to be sure that the Linux distribution on the system is + one that supports the Yocto Project. + You also need to be sure that the correct set of host packages are + installed that allow development using the Yocto Project. + For the steps needed to set up a development host that runs Linux, + see the + "Setting Up a Native Linux Host" + section in the Yocto Project Development Tasks Manual. + + + + Once your development host is set up to use the Yocto Project, + several methods exist for you to do work in the Yocto Project + environment: + + + Command Lines, BitBake, and Shells: + Traditional development in the Yocto Project involves using + OpenEmbedded build system, which uses BitBake, in a + command-line environment from a shell on your development + host. + You can accomplish this from a host that is a native Linux + machine or from a host that has been set up with CROPS. + Either way, you create, modify, and build images and + applications all within a shell-based environment using + components and tools available through your Linux distribution + and the Yocto Project. + + For a general flow of the build procedures, see the + "Building an Image" + section in the Yocto Project Development Tasks Manual. + + + Board Support Package (BSP) Development: + Development of BSPs involves using the Yocto Project to + create and test layers that allow easy development of + images and applications targeted for specific hardware. + To development BSPs, you need to take some additional steps + beyond what was described in setting up a development host. + + + The + Yocto Project Board Support Package (BSP) Developer's Guide' + provides BSP-related development information. + For specifics on development host preparation, see the + "Preparing Your Build Host to Work With BSP Layers" + section in the Yocto Project Board Support Package (BSP) + Developer's Guide. + + + Kernel Development: + If you are going to be developing kernels using the Yocto + Project you likely will be using devtool. + A workflow using devtool makes kernel + development quicker by reducing iteration cycle times. + + The + Yocto Project Linux Kernel Development Manual + provides kernel-related development information. + For specifics on development host preparation, see the + "Preparing the Build Host to Work on the Kernel" + section in the Yocto Project Linux Kernel Development Manual. + + + Using the Eclipse IDE: + One of two Yocto Project development methods that involves an + interface that effectively puts the Yocto Project into the + background is the popular Eclipse IDE. + This method of development is advantageous if you are already + familiar with working within Eclipse. + Development is supported through a plugin that you install + onto your development host. + + For steps that show you how to set up your development + host to use the Eclipse Yocto Project plugin, see the + "Developing Applications Using Eclipse" + Chapter in the Yocto Project Application Development and the + Extensible Software Development Kit (eSDK) manual. + + + Using the Toaster: + The other Yocto Project development method that involves an + interface that effectively puts the Yocto Project into the + background is Toaster. + Toaster provides an interface to the OpenEmbedded build system. + The interface enables you to configure and run your builds. + Information about builds is collected and stored in a database. + You can use Toaster to configure and start builds on multiple + remote build servers. + + For steps that show you how to set up your development + host to use Toaster and on how to use Toaster in general, + see the + Toaster User Manual. + + + +
+ +
+ Yocto Project Source Repositories + + + The Yocto Project team maintains complete source repositories for all + Yocto Project files at + . + This web-based source code browser is organized into categories by + function such as IDE Plugins, Matchbox, Poky, Yocto Linux Kernel, and + so forth. + From the interface, you can click on any particular item in the "Name" + column and see the URL at the bottom of the page that you need to clone + a Git repository for that particular item. + Having a local Git repository of the + Source Directory, + which is usually named "poky", allows + you to make changes, contribute to the history, and ultimately enhance + the Yocto Project's tools, Board Support Packages, and so forth. + + + + For any supported release of Yocto Project, you can also go to the + Yocto Project Website and + select the "Downloads" tab and get a released tarball of the + poky repository or any supported BSP tarballs. + Unpacking these tarballs gives you a snapshot of the released + files. + Notes + + + The recommended method for setting up the Yocto Project + Source Directory + and the files for supported BSPs + (e.g., meta-intel) is to use + Git to create a local copy of + the upstream repositories. + + + Be sure to always work in matching branches for both + the selected BSP repository and the + Source Directory + (i.e. poky) repository. + For example, if you have checked out the "master" branch + of poky and you are going to use + meta-intel, be sure to checkout the + "master" branch of meta-intel. + + + + + + + In summary, here is where you can get the project files needed for + development: + + + + Source Repositories: + + This area contains IDE Plugins, Matchbox, Poky, Poky Support, + Tools, Yocto Linux Kernel, and Yocto Metadata Layers. + You can create local copies of Git repositories for each of + these areas. + + + + For steps on how to view and access these upstream Git + repositories, see the + "Accessing Source Repositories" + Section in the Yocto Project Development Tasks Manual. + + + + Index of /releases: + + This is an index of releases such as + the Eclipse + Yocto Plug-in, miscellaneous support, Poky, Pseudo, installers + for cross-development toolchains, and all released versions of + Yocto Project in the form of images or tarballs. + Downloading and extracting these files does not produce a local + copy of the Git repository but rather a snapshot of a + particular release or image. + + + + For steps on how to view and access these files, see the + "Accessing Index of Releases" + section in the Yocto Project Development Tasks Manual. + + + "Downloads" page for the + Yocto Project Website: + + + The Yocto Project website includes a "DOWNLOADS" page + accessible through the "SOFTWARE" tab + that allows you to download any Yocto Project + release, tool, and Board Support Package (BSP) in tarball form. + The tarballs are similar to those found in the + Index of /releases: area. + + + + For steps on how to use the "DOWNLOADS" page, see the + "Using the Downloads Page" + section in the Yocto Project Development Tasks Manual. + + + +
+ +
+ Git Workflows and the Yocto Project + + + Developing using the Yocto Project likely requires the use of + Git. + Git is a free, open source distributed version control system + used as part of many collaborative design environments. + This section provides workflow concepts using the Yocto Project and + Git. + In particular, the information covers basic practices that describe + roles and actions in a collaborative development environment. + + If you are familiar with this type of development environment, you + might not want to read this section. + + + + + The Yocto Project files are maintained using Git in "branches" + whose Git histories track every change and whose structures + provide branches for all diverging functionality. + Although there is no need to use Git, many open source projects do so. + + + + For the Yocto Project, a key individual called the "maintainer" is + responsible for the integrity of the "master" branch of a given Git + repository. + The "master" branch is the “upstream” repository from which final or + most recent builds of a project occur. + The maintainer is responsible for accepting changes from other + developers and for organizing the underlying branch structure to + reflect release strategies and so forth. + + For information on finding out who is responsible for (maintains) + a particular area of code in the Yocto Project, see the + "Submitting a Change to the Yocto Project" + section of the Yocto Project Development Tasks Manual. + + + + + The Yocto Project poky Git repository also has an + upstream contribution Git repository named + poky-contrib. + You can see all the branches in this repository using the web interface + of the + Source Repositories organized + within the "Poky Support" area. + These branches hold changes (commits) to the project that have been + submitted or committed by the Yocto Project development team and by + community members who contribute to the project. + The maintainer determines if the changes are qualified to be moved + from the "contrib" branches into the "master" branch of the Git + repository. + + + + Developers (including contributing community members) create and + maintain cloned repositories of upstream branches. + The cloned repositories are local to their development platforms and + are used to develop changes. + When a developer is satisfied with a particular feature or change, + they "push" the change to the appropriate "contrib" repository. + + + + Developers are responsible for keeping their local repository + up-to-date with whatever upstream branch they are working against. + They are also responsible for straightening out any conflicts that + might arise within files that are being worked on simultaneously by + more than one person. + All this work is done locally on the development host before + anything is pushed to a "contrib" area and examined at the maintainer’s + level. + + + + A somewhat formal method exists by which developers commit changes + and push them into the "contrib" area and subsequently request that + the maintainer include them into an upstream branch. + This process is called “submitting a patch” or "submitting a change." + For information on submitting patches and changes, see the + "Submitting a Change to the Yocto Project" + section in the Yocto Project Development Tasks Manual. + + + + To summarize the development workflow: a single point of entry + exists for changes into a "master" or development branch of the + Git repository, which is controlled by the project’s maintainer. + And, a set of developers exist who independently develop, test, and + submit changes to "contrib" areas for the maintainer to examine. + The maintainer then chooses which changes are going to become a + permanent part of the project. + + + + + + + + While each development environment is unique, there are some best + practices or methods that help development run smoothly. + The following list describes some of these practices. + For more information about Git workflows, see the workflow topics in + the + Git Community Book. + + + Make Small Changes: + It is best to keep the changes you commit small as compared to + bundling many disparate changes into a single commit. + This practice not only keeps things manageable but also allows + the maintainer to more easily include or refuse changes. + + + Make Complete Changes: + It is also good practice to leave the repository in a + state that allows you to still successfully build your project. + In other words, do not commit half of a feature, + then add the other half as a separate, later commit. + Each commit should take you from one buildable project state + to another buildable state. + + + Use Branches Liberally: + It is very easy to create, use, and delete local branches in + your working Git repository on the development host. + You can name these branches anything you like. + It is helpful to give them names associated with the particular + feature or change on which you are working. + Once you are done with a feature or change and have merged it + into your local master branch, simply discard the temporary + branch. + + + Merge Changes: + The git merge command allows you to take + the changes from one branch and fold them into another branch. + This process is especially helpful when more than a single + developer might be working on different parts of the same + feature. + Merging changes also automatically identifies any collisions + or "conflicts" that might happen as a result of the same lines + of code being altered by two different developers. + + + Manage Branches: + Because branches are easy to use, you should use a system + where branches indicate varying levels of code readiness. + For example, you can have a "work" branch to develop in, a + "test" branch where the code or change is tested, a "stage" + branch where changes are ready to be committed, and so forth. + As your project develops, you can merge code across the + branches to reflect ever-increasing stable states of the + development. + + + Use Push and Pull: + The push-pull workflow is based on the concept of developers + "pushing" local commits to a remote repository, which is + usually a contribution repository. + This workflow is also based on developers "pulling" known + states of the project down into their local development + repositories. + The workflow easily allows you to pull changes submitted by + other developers from the upstream repository into your + work area ensuring that you have the most recent software + on which to develop. + The Yocto Project has two scripts named + create-pull-request and + send-pull-request that ship with the + release to facilitate this workflow. + You can find these scripts in the scripts + folder of the + Source Directory. + For information on how to use these scripts, see the + "Using Scripts to Push a Change Upstream and Request a Pull" + section in the Yocto Project Development Tasks Manual. + + + Patch Workflow: + This workflow allows you to notify the maintainer through an + email that you have a change (or patch) you would like + considered for the "master" branch of the Git repository. + To send this type of change, you format the patch and then + send the email using the Git commands + git format-patch and + git send-email. + For information on how to use these scripts, see the + "Submitting a Change to the Yocto Project" + section in the Yocto Project Development Tasks Manual. + + + +
+ +
+ Git + + + The Yocto Project makes extensive use of Git, which is a + free, open source distributed version control system. + Git supports distributed development, non-linear development, + and can handle large projects. + It is best that you have some fundamental understanding + of how Git tracks projects and how to work with Git if + you are going to use the Yocto Project for development. + This section provides a quick overview of how Git works and + provides you with a summary of some essential Git commands. + Notes + + + For more information on Git, see + . + + + If you need to download Git, it is recommended that you add + Git to your system through your distribution's "software + store" (e.g. for Ubuntu, use the Ubuntu Software feature). + For the Git download page, see + . + + + For information beyond the introductory nature in this + section, see the + "Working With Yocto Project Source Files" + section in the Yocto Project Development Tasks Manual. + + + + + +
+ Repositories, Tags, and Branches + + + As mentioned briefly in the previous section and also in the + "Git Workflows and the Yocto Project" + section, the Yocto Project maintains source repositories at + . + If you look at this web-interface of the repositories, each item + is a separate Git repository. + + + + Git repositories use branching techniques that track content + change (not files) within a project (e.g. a new feature or updated + documentation). + Creating a tree-like structure based on project divergence allows + for excellent historical information over the life of a project. + This methodology also allows for an environment from which you can + do lots of local experimentation on projects as you develop + changes or new features. + + + + A Git repository represents all development efforts for a given + project. + For example, the Git repository poky contains + all changes and developments for that repository over the course + of its entire life. + That means that all changes that make up all releases are captured. + The repository maintains a complete history of changes. + + + + You can create a local copy of any repository by "cloning" it + with the git clone command. + When you clone a Git repository, you end up with an identical + copy of the repository on your development system. + Once you have a local copy of a repository, you can take steps to + develop locally. + For examples on how to clone Git repositories, see the + "Working With Yocto Project Source Files" + section in the Yocto Project Development Tasks Manual. + + + + It is important to understand that Git tracks content change and + not files. + Git uses "branches" to organize different development efforts. + For example, the poky repository has + several branches that include the current "&DISTRO_NAME_NO_CAP;" + branch, the "master" branch, and many branches for past + Yocto Project releases. + You can see all the branches by going to + and + clicking on the + [...] + link beneath the "Branch" heading. + + + + Each of these branches represents a specific area of development. + The "master" branch represents the current or most recent + development. + All other branches represent offshoots of the "master" branch. + + + + When you create a local copy of a Git repository, the copy has + the same set of branches as the original. + This means you can use Git to create a local working area + (also called a branch) that tracks a specific development branch + from the upstream source Git repository. + in other words, you can define your local Git environment to + work on any development branch in the repository. + To help illustrate, consider the following example Git commands: + + $ cd ~ + $ git clone git://git.yoctoproject.org/poky + $ cd poky + $ git checkout -b &DISTRO_NAME_NO_CAP; origin/&DISTRO_NAME_NO_CAP; + + In the previous example after moving to the home directory, the + git clone command creates a + local copy of the upstream poky Git repository. + By default, Git checks out the "master" branch for your work. + After changing the working directory to the new local repository + (i.e. poky), the + git checkout command creates + and checks out a local branch named "&DISTRO_NAME_NO_CAP;", which + tracks the upstream "origin/&DISTRO_NAME_NO_CAP;" branch. + Changes you make while in this branch would ultimately affect + the upstream "&DISTRO_NAME_NO_CAP;" branch of the + poky repository. + + + + It is important to understand that when you create and checkout a + local working branch based on a branch name, + your local environment matches the "tip" of that particular + development branch at the time you created your local branch, + which could be different from the files in the "master" branch + of the upstream repository. + In other words, creating and checking out a local branch based on + the "&DISTRO_NAME_NO_CAP;" branch name is not the same as + checking out the "master" branch in the repository. + Keep reading to see how you create a local snapshot of a Yocto + Project Release. + + + + Git uses "tags" to mark specific changes in a repository branch + structure. + Typically, a tag is used to mark a special point such as the final + change (or commit) before a project is released. + You can see the tags used with the poky Git + repository by going to + and + clicking on the + [...] + link beneath the "Tag" heading. + + + + Some key tags for the poky repository are + jethro-14.0.3, + morty-16.0.1, + pyro-17.0.0, and + &DISTRO_NAME_NO_CAP;-&POKYVERSION;. + These tags represent Yocto Project releases. + + + + When you create a local copy of the Git repository, you also + have access to all the tags in the upstream repository. + Similar to branches, you can create and checkout a local working + Git branch based on a tag name. + When you do this, you get a snapshot of the Git repository that + reflects the state of the files when the change was made associated + with that tag. + The most common use is to checkout a working branch that matches + a specific Yocto Project release. + Here is an example: + + $ cd ~ + $ git clone git://git.yoctoproject.org/poky + $ cd poky + $ git fetch --all --tags --prune + $ git checkout tags/pyro-17.0.0 -b my-pyro-17.0.0 + + In this example, the name of the top-level directory of your + local Yocto Project repository is poky. + After moving to the poky directory, the + git fetch command makes all the upstream + tags available locally in your repository. + Finally, the git checkout command + creates and checks out a branch named "my-pyro-17.0.0" that is + based on the upstream branch whose "HEAD" matches the + commit in the repository associated with the "pyro-17.0.0" tag. + The files in your repository now exactly match that particular + Yocto Project release as it is tagged in the upstream Git + repository. + It is important to understand that when you create and + checkout a local working branch based on a tag, your environment + matches a specific point in time and not the entire development + branch (i.e. from the "tip" of the branch backwards). + +
+ +
+ Basic Commands + + + Git has an extensive set of commands that lets you manage changes + and perform collaboration over the life of a project. + Conveniently though, you can manage with a small set of basic + operations and workflows once you understand the basic + philosophy behind Git. + You do not have to be an expert in Git to be functional. + A good place to look for instruction on a minimal set of Git + commands is + here. + + + + If you do not know much about Git, you should educate + yourself by visiting the links previously mentioned. + + + + The following list of Git commands briefly describes some basic + Git operations as a way to get started. + As with any set of commands, this list (in most cases) simply shows + the base command and omits the many arguments it supports. + See the Git documentation for complete descriptions and strategies + on how to use these commands: + + + git init: + Initializes an empty Git repository. + You cannot use Git commands unless you have a + .git repository. + + + git clone: + Creates a local clone of a Git repository that is on + equal footing with a fellow developer’s Git repository + or an upstream repository. + + + git add: + Locally stages updated file contents to the index that + Git uses to track changes. + You must stage all files that have changed before you + can commit them. + + + git commit: + Creates a local "commit" that documents the changes you + made. + Only changes that have been staged can be committed. + Commits are used for historical purposes, for determining + if a maintainer of a project will allow the change, + and for ultimately pushing the change from your local + Git repository into the project’s upstream repository. + + + git status: + Reports any modified files that possibly need to be + staged and gives you a status of where you stand regarding + local commits as compared to the upstream repository. + + + git checkout branch-name: + Changes your local working branch and in this form + assumes the local branch already exists. + This command is analogous to "cd". + + + git checkout –b working-branch upstream-branch: + Creates and checks out a working branch on your local + machine. + The local branch tracks the upstream branch. + You can use your local branch to isolate your work. + It is a good idea to use local branches when adding + specific features or changes. + Using isolated branches facilitates easy removal of + changes if they do not work out. + + git branch: + Displays the existing local branches associated with your + local repository. + The branch that you have currently checked out is noted + with an asterisk character. + + + git branch -D branch-name: + Deletes an existing local branch. + You need to be in a local branch other than the one you + are deleting in order to delete + branch-name. + + + git pull --rebase: + Retrieves information from an upstream Git repository + and places it in your local Git repository. + You use this command to make sure you are synchronized with + the repository from which you are basing changes + (.e.g. the "master" branch). + The "--rebase" option ensures that any local commits you + have in your branch are preserved at the top of your + local branch. + + + git push repo-name local-branch:upstream-branch: + Sends all your committed local changes to the upstream Git + repository that your local repository is tracking + (e.g. a contribution repository). + The maintainer of the project draws from these repositories + to merge changes (commits) into the appropriate branch + of project's upstream repository. + + + git merge: + Combines or adds changes from one + local branch of your repository with another branch. + When you create a local Git repository, the default branch + is named "master". + A typical workflow is to create a temporary branch that is + based off "master" that you would use for isolated work. + You would make your changes in that isolated branch, + stage and commit them locally, switch to the "master" + branch, and then use the git merge + command to apply the changes from your isolated branch + into the currently checked out branch (e.g. "master"). + After the merge is complete and if you are done with + working in that isolated branch, you can safely delete + the isolated branch. + + + git cherry-pick commits: + Choose and apply specific commits from one branch + into another branch. + There are times when you might not be able to merge + all the changes in one branch with + another but need to pick out certain ones. + + + gitk: + Provides a GUI view of the branches and changes in your + local Git repository. + This command is a good way to graphically see where things + have diverged in your local repository. + + You need to install the gitk + package on your development system to use this + command. + + + + git log: + Reports a history of your commits to the repository. + This report lists all commits regardless of whether you + have pushed them upstream or not. + + + git diff: + Displays line-by-line differences between a local + working file and the same file as understood by Git. + This command is useful to see what you have changed + in any given file. + + + +
+
+ +
+ Licensing + + + Because open source projects are open to the public, they have + different licensing structures in place. + License evolution for both Open Source and Free Software has an + interesting history. + If you are interested in this history, you can find basic information + here: + + + Open source license history + + + Free software license history + + + + + + In general, the Yocto Project is broadly licensed under the + Massachusetts Institute of Technology (MIT) License. + MIT licensing permits the reuse of software within proprietary + software as long as the license is distributed with that software. + MIT is also compatible with the GNU General Public License (GPL). + Patches to the Yocto Project follow the upstream licensing scheme. + You can find information on the MIT license + here. + You can find information on the GNU GPL + here. + + + + When you build an image using the Yocto Project, the build process + uses a known list of licenses to ensure compliance. + You can find this list in the + Source Directory + at meta/files/common-licenses. + Once the build completes, the list of all licenses found and used + during that build are kept in the + Build Directory + at tmp/deploy/licenses. + + + + If a module requires a license that is not in the base list, the + build process generates a warning during the build. + These tools make it easier for a developer to be certain of the + licenses with which their shipped products must comply. + However, even with these tools it is still up to the developer to + resolve potential licensing issues. + + + + The base list of licenses used by the build process is a combination + of the Software Package Data Exchange (SPDX) list and the Open + Source Initiative (OSI) projects. + SPDX Group is a working group of + the Linux Foundation that maintains a specification for a standard + format for communicating the components, licenses, and copyrights + associated with a software package. + OSI is a corporation + dedicated to the Open Source Definition and the effort for reviewing + and approving licenses that conform to the Open Source Definition + (OSD). + + + + You can find a list of the combined SPDX and OSI licenses that the + Yocto Project uses in the + meta/files/common-licenses directory in your + Source Directory. + + + + For information that can help you maintain compliance with various + open source licensing during the lifecycle of a product created using + the Yocto Project, see the + "Maintaining Open Source License Compliance During Your Product's Lifecycle" + section in the Yocto Project Development Tasks Manual. + +
+ + diff --git a/documentation/overview-manual/overview-manual-eclipse-customization.xsl b/documentation/overview-manual/overview-manual-eclipse-customization.xsl new file mode 100644 index 0000000000..aaf99ea1ba --- /dev/null +++ b/documentation/overview-manual/overview-manual-eclipse-customization.xsl @@ -0,0 +1,35 @@ + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/documentation/overview-manual/overview-manual-intro.xml b/documentation/overview-manual/overview-manual-intro.xml new file mode 100644 index 0000000000..2976f7c1b6 --- /dev/null +++ b/documentation/overview-manual/overview-manual-intro.xml @@ -0,0 +1,111 @@ + %poky; ] > + + + +The Yocto Project Overview and Concepts Manual +
+ Welcome + + + Welcome to the Yocto Project Overview and Concepts Manual! + This manual introduces the Yocto Project by providing concepts, + software overviews, best-known-methods (BKMs), and any other + high-level introductory information suitable for a new Yocto + Project user. + + + + The following list describes what you can get from this manual: + + + Introducing the Yocto Project: + This chapter provides an introduction to the Yocto + Project. + You will learn about features and challenges of the + Yocto Project, the layer model, components and tools, + development methods, the Poky reference distribution, + the OpenEmbedded build system workflow, and some basic + Yocto terms. + + + The Yocto Project Development Environment: + This chapter helps you get started understanding the + Yocto Project development environment. + You will learn about open source, development hosts, + Yocto Project source repositories, workflows using Git + and the Yocto Project, a Git primer, and information + about licensing. + + + + + + This manual does not give you the following: + + + Step-by-step Instructions for Development Tasks: + Instructional procedures reside in other manuals within + the Yocto Project documentation set. + For example, the + Yocto Project Development Tasks Manual + provides examples on how to perform various development + tasks. + As another example, the + Yocto Project Application Development and the Extensible Software Development Kit (eSDK) + manual contains detailed instructions on how to install an + SDK, which is used to develop applications for target + hardware. + + + Reference Material: + This type of material resides in an appropriate reference + manual. + For example, system variables are documented in the + Yocto Project Reference Manual. + As another example, the + Yocto Project Board Support Package (BSP) Developer's Guide + contains reference information on BSPs. + + + Detailed Public Information Not Specific to the + Yocto Project: + For example, exhaustive information on how to use the + Source Control Manager Git is better covered with Internet + searches and official Git Documentation than through the + Yocto Project documentation. + + + +
+ +
+ Other Information + + + Because this manual presents information for many different + topics, supplemental information is recommended for full + comprehension. + For additional introductory information on the Yocto Project, see + the Yocto Project Website. + If you want to build an image with no knowledge of Yocto Project + as a way of quickly testing it out, see the + Yocto Project Quick Build + document. + + + + For a comprehensive list of links and other documentation, see the + "Links and Related Documentation" + section in the Yocto Project Reference Manual. + For a paper showing how to set up and run a quick build using the + Yocto Project, see the + "My First Yocto Project Build" + paper. + +
+ + diff --git a/documentation/overview-manual/overview-manual-style.css b/documentation/overview-manual/overview-manual-style.css new file mode 100644 index 0000000000..97a364b125 --- /dev/null +++ b/documentation/overview-manual/overview-manual-style.css @@ -0,0 +1,988 @@ +/* + Generic XHTML / DocBook XHTML CSS Stylesheet. + + Browser wrangling and typographic design by + Oyvind Kolas / pippin@gimp.org + + Customised for Poky by + Matthew Allum / mallum@o-hand.com + + Thanks to: + Liam R. E. Quin + William Skaggs + Jakub Steiner + + Structure + --------- + + The stylesheet is divided into the following sections: + + Positioning + Margins, paddings, width, font-size, clearing. + Decorations + Borders, style + Colors + Colors + Graphics + Graphical backgrounds + Nasty IE tweaks + Workarounds needed to make it work in internet explorer, + currently makes the stylesheet non validating, but up until + this point it is validating. + Mozilla extensions + Transparency for footer + Rounded corners on boxes + +*/ + + + /*************** / + / Positioning / +/ ***************/ + +body { + font-family: Verdana, Sans, sans-serif; + + min-width: 640px; + width: 80%; + margin: 0em auto; + padding: 2em 5em 5em 5em; + color: #333; +} + +h1,h2,h3,h4,h5,h6,h7 { + font-family: Arial, Sans; + color: #00557D; + clear: both; +} + +h1 { + font-size: 2em; + text-align: left; + padding: 0em 0em 0em 0em; + margin: 2em 0em 0em 0em; +} + +h2.subtitle { + margin: 0.10em 0em 3.0em 0em; + padding: 0em 0em 0em 0em; + font-size: 1.8em; + padding-left: 20%; + font-weight: normal; + font-style: italic; +} + +h2 { + margin: 2em 0em 0.66em 0em; + padding: 0.5em 0em 0em 0em; + font-size: 1.5em; + font-weight: bold; +} + +h3.subtitle { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; + font-size: 142.14%; + text-align: right; +} + +h3 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 140%; + font-weight: bold; +} + +h4 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 120%; + font-weight: bold; +} + +h5 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 110%; + font-weight: bold; +} + +h6 { + margin: 1em 0em 0em 0em; + padding: 1em 0em 0em 0em; + font-size: 110%; + font-weight: bold; +} + +.authorgroup { + background-color: transparent; + background-repeat: no-repeat; + padding-top: 256px; + background-image: url("figures/overview-manual-title.png"); + background-position: left top; + margin-top: -256px; + padding-right: 50px; + margin-left: 0px; + text-align: right; + width: 740px; +} + +h3.author { + margin: 0em 0me 0em 0em; + padding: 0em 0em 0em 0em; + font-weight: normal; + font-size: 100%; + color: #333; + clear: both; +} + +.author tt.email { + font-size: 66%; +} + +.titlepage hr { + width: 0em; + clear: both; +} + +.revhistory { + padding-top: 2em; + clear: both; +} + +.toc, +.list-of-tables, +.list-of-examples, +.list-of-figures { + padding: 1.33em 0em 2.5em 0em; + color: #00557D; +} + +.toc p, +.list-of-tables p, +.list-of-figures p, +.list-of-examples p { + padding: 0em 0em 0em 0em; + padding: 0em 0em 0.3em; + margin: 1.5em 0em 0em 0em; +} + +.toc p b, +.list-of-tables p b, +.list-of-figures p b, +.list-of-examples p b{ + font-size: 100.0%; + font-weight: bold; +} + +.toc dl, +.list-of-tables dl, +.list-of-figures dl, +.list-of-examples dl { + margin: 0em 0em 0.5em 0em; + padding: 0em 0em 0em 0em; +} + +.toc dt { + margin: 0em 0em 0em 0em; + padding: 0em 0em 0em 0em; +} + +.toc dd { + margin: 0em 0em 0em 2.6em; + padding: 0em 0em 0em 0em; +} + +div.glossary dl, +div.variablelist dl { +} + +.glossary dl dt, +.variablelist dl dt, +.variablelist dl dt span.term { + font-weight: normal; + width: 20em; + text-align: right; +} + +.variablelist dl dt { + margin-top: 0.5em; +} + +.glossary dl dd, +.variablelist dl dd { + margin-top: -1em; + margin-left: 25.5em; +} + +.glossary dd p, +.variablelist dd p { + margin-top: 0em; + margin-bottom: 1em; +} + + +div.calloutlist table td { + padding: 0em 0em 0em 0em; + margin: 0em 0em 0em 0em; +} + +div.calloutlist table td p { + margin-top: 0em; + margin-bottom: 1em; +} + +div p.copyright { + text-align: left; +} + +div.legalnotice p.legalnotice-title { + margin-bottom: 0em; +} + +p { + line-height: 1.5em; + margin-top: 0em; + +} + +dl { + padding-top: 0em; +} + +hr { + border: solid 1px; +} + + +.mediaobject, +.mediaobjectco { + text-align: center; +} + +img { + border: none; +} + +ul { + padding: 0em 0em 0em 1.5em; +} + +ul li { + padding: 0em 0em 0em 0em; +} + +ul li p { + text-align: left; +} + +table { + width :100%; +} + +th { + padding: 0.25em; + text-align: left; + font-weight: normal; + vertical-align: top; +} + +td { + padding: 0.25em; + vertical-align: top; +} + +p a[id] { + margin: 0px; + padding: 0px; + display: inline; + background-image: none; +} + +a { + text-decoration: underline; + color: #444; +} + +pre { + overflow: auto; +} + +a:hover { + text-decoration: underline; + /*font-weight: bold;*/ +} + +/* This style defines how the permalink character + appears by itself and when hovered over with + the mouse. */ + +[alt='Permalink'] { color: #eee; } +[alt='Permalink']:hover { color: black; } + + +div.informalfigure, +div.informalexample, +div.informaltable, +div.figure, +div.table, +div.example { + margin: 1em 0em; + padding: 1em; + page-break-inside: avoid; +} + + +div.informalfigure p.title b, +div.informalexample p.title b, +div.informaltable p.title b, +div.figure p.title b, +div.example p.title b, +div.table p.title b{ + padding-top: 0em; + margin-top: 0em; + font-size: 100%; + font-weight: normal; +} + +.mediaobject .caption, +.mediaobject .caption p { + text-align: center; + font-size: 80%; + padding-top: 0.5em; + padding-bottom: 0.5em; +} + +.epigraph { + padding-left: 55%; + margin-bottom: 1em; +} + +.epigraph p { + text-align: left; +} + +.epigraph .quote { + font-style: italic; +} +.epigraph .attribution { + font-style: normal; + text-align: right; +} + +span.application { + font-style: italic; +} + +.programlisting { + font-family: monospace; + font-size: 80%; + white-space: pre; + margin: 1.33em 0em; + padding: 1.33em; +} + +.tip, +.warning, +.caution, +.note { + margin-top: 1em; + margin-bottom: 1em; + +} + +/* force full width of table within div */ +.tip table, +.warning table, +.caution table, +.note table { + border: none; + width: 100%; +} + + +.tip table th, +.warning table th, +.caution table th, +.note table th { + padding: 0.8em 0.0em 0.0em 0.0em; + margin : 0em 0em 0em 0em; +} + +.tip p, +.warning p, +.caution p, +.note p { + margin-top: 0.5em; + margin-bottom: 0.5em; + padding-right: 1em; + text-align: left; +} + +.acronym { + text-transform: uppercase; +} + +b.keycap, +.keycap { + padding: 0.09em 0.3em; + margin: 0em; +} + +.itemizedlist li { + clear: none; +} + +.filename { + font-size: medium; + font-family: Courier, monospace; +} + + +div.navheader, div.heading{ + position: absolute; + left: 0em; + top: 0em; + width: 100%; + background-color: #cdf; + width: 100%; +} + +div.navfooter, div.footing{ + position: fixed; + left: 0em; + bottom: 0em; + background-color: #eee; + width: 100%; +} + + +div.navheader td, +div.navfooter td { + font-size: 66%; +} + +div.navheader table th { + /*font-family: Georgia, Times, serif;*/ + /*font-size: x-large;*/ + font-size: 80%; +} + +div.navheader table { + border-left: 0em; + border-right: 0em; + border-top: 0em; + width: 100%; +} + +div.navfooter table { + border-left: 0em; + border-right: 0em; + border-bottom: 0em; + width: 100%; +} + +div.navheader table td a, +div.navfooter table td a { + color: #777; + text-decoration: none; +} + +/* normal text in the footer */ +div.navfooter table td { + color: black; +} + +div.navheader table td a:visited, +div.navfooter table td a:visited { + color: #444; +} + + +/* links in header and footer */ +div.navheader table td a:hover, +div.navfooter table td a:hover { + text-decoration: underline; + background-color: transparent; + color: #33a; +} + +div.navheader hr, +div.navfooter hr { + display: none; +} + + +.qandaset tr.question td p { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; +} + +.qandaset tr.answer td p { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; +} +.answer td { + padding-bottom: 1.5em; +} + +.emphasis { + font-weight: bold; +} + + + /************* / + / decorations / +/ *************/ + +.titlepage { +} + +.part .title { +} + +.subtitle { + border: none; +} + +/* +h1 { + border: none; +} + +h2 { + border-top: solid 0.2em; + border-bottom: solid 0.06em; +} + +h3 { + border-top: 0em; + border-bottom: solid 0.06em; +} + +h4 { + border: 0em; + border-bottom: solid 0.06em; +} + +h5 { + border: 0em; +} +*/ + +.programlisting { + border: solid 1px; +} + +div.figure, +div.table, +div.informalfigure, +div.informaltable, +div.informalexample, +div.example { + border: 1px solid; +} + + + +.tip, +.warning, +.caution, +.note { + border: 1px solid; +} + +.tip table th, +.warning table th, +.caution table th, +.note table th { + border-bottom: 1px solid; +} + +.question td { + border-top: 1px solid black; +} + +.answer { +} + + +b.keycap, +.keycap { + border: 1px solid; +} + + +div.navheader, div.heading{ + border-bottom: 1px solid; +} + + +div.navfooter, div.footing{ + border-top: 1px solid; +} + + /********* / + / colors / +/ *********/ + +body { + color: #333; + background: white; +} + +a { + background: transparent; +} + +a:hover { + background-color: #dedede; +} + + +h1, +h2, +h3, +h4, +h5, +h6, +h7, +h8 { + background-color: transparent; +} + +hr { + border-color: #aaa; +} + + +.tip, .warning, .caution, .note { + border-color: #fff; +} + + +.tip table th, +.warning table th, +.caution table th, +.note table th { + border-bottom-color: #fff; +} + + +.warning { + background-color: #f0f0f2; +} + +.caution { + background-color: #f0f0f2; +} + +.tip { + background-color: #f0f0f2; +} + +.note { + background-color: #f0f0f2; +} + +.glossary dl dt, +.variablelist dl dt, +.variablelist dl dt span.term { + color: #044; +} + +div.figure, +div.table, +div.example, +div.informalfigure, +div.informaltable, +div.informalexample { + border-color: #aaa; +} + +pre.programlisting { + color: black; + background-color: #fff; + border-color: #aaa; + border-width: 2px; +} + +.guimenu, +.guilabel, +.guimenuitem { + background-color: #eee; +} + + +b.keycap, +.keycap { + background-color: #eee; + border-color: #999; +} + + +div.navheader { + border-color: black; +} + + +div.navfooter { + border-color: black; +} + +.writernotes { + color: red; +} + + + /*********** / + / graphics / +/ ***********/ + +/* +body { + background-image: url("images/body_bg.jpg"); + background-attachment: fixed; +} + +.navheader, +.note, +.tip { + background-image: url("images/note_bg.jpg"); + background-attachment: fixed; +} + +.warning, +.caution { + background-image: url("images/warning_bg.jpg"); + background-attachment: fixed; +} + +.figure, +.informalfigure, +.example, +.informalexample, +.table, +.informaltable { + background-image: url("images/figure_bg.jpg"); + background-attachment: fixed; +} + +*/ +h1, +h2, +h3, +h4, +h5, +h6, +h7{ +} + +/* +Example of how to stick an image as part of the title. + +div.article .titlepage .title +{ + background-image: url("figures/white-on-black.png"); + background-position: center; + background-repeat: repeat-x; +} +*/ + +div.preface .titlepage .title, +div.colophon .title, +div.chapter .titlepage .title, +div.article .titlepage .title +{ +} + +div.section div.section .titlepage .title, +div.sect2 .titlepage .title { + background: none; +} + + +h1.title { + background-color: transparent; + background-repeat: no-repeat; + height: 256px; + text-indent: -9000px; + overflow:hidden; +} + +h2.subtitle { + background-color: transparent; + text-indent: -9000px; + overflow:hidden; + width: 0px; + display: none; +} + + /*************************************** / + / pippin.gimp.org specific alterations / +/ ***************************************/ + +/* +div.heading, div.navheader { + color: #777; + font-size: 80%; + padding: 0; + margin: 0; + text-align: left; + position: absolute; + top: 0px; + left: 0px; + width: 100%; + height: 50px; + background: url('/gfx/heading_bg.png') transparent; + background-repeat: repeat-x; + background-attachment: fixed; + border: none; +} + +div.heading a { + color: #444; +} + +div.footing, div.navfooter { + border: none; + color: #ddd; + font-size: 80%; + text-align:right; + + width: 100%; + padding-top: 10px; + position: absolute; + bottom: 0px; + left: 0px; + + background: url('/gfx/footing_bg.png') transparent; +} +*/ + + + + /****************** / + / nasty ie tweaks / +/ ******************/ + +/* +div.heading, div.navheader { + width:expression(document.body.clientWidth + "px"); +} + +div.footing, div.navfooter { + width:expression(document.body.clientWidth + "px"); + margin-left:expression("-5em"); +} +body { + padding:expression("4em 5em 0em 5em"); +} +*/ + + /**************************************** / + / mozilla vendor specific css extensions / +/ ****************************************/ +/* +div.navfooter, div.footing{ + -moz-opacity: 0.8em; +} + +div.figure, +div.table, +div.informalfigure, +div.informaltable, +div.informalexample, +div.example, +.tip, +.warning, +.caution, +.note { + -moz-border-radius: 0.5em; +} + +b.keycap, +.keycap { + -moz-border-radius: 0.3em; +} +*/ + +table tr td table tr td { + display: none; +} + + +hr { + display: none; +} + +table { + border: 0em; +} + + .photo { + float: right; + margin-left: 1.5em; + margin-bottom: 1.5em; + margin-top: 0em; + max-width: 17em; + border: 1px solid gray; + padding: 3px; + background: white; +} + .seperator { + padding-top: 2em; + clear: both; + } + + #validators { + margin-top: 5em; + text-align: right; + color: #777; + } + @media print { + body { + font-size: 8pt; + } + .noprint { + display: none; + } + } + + +.tip, +.note { + background: #f0f0f2; + color: #333; + padding: 20px; + margin: 20px; +} + +.tip h3, +.note h3 { + padding: 0em; + margin: 0em; + font-size: 2em; + font-weight: bold; + color: #333; +} + +.tip a, +.note a { + color: #333; + text-decoration: underline; +} + +.footnote { + font-size: small; + color: #333; +} + +/* Changes the announcement text */ +.tip h3, +.warning h3, +.caution h3, +.note h3 { + font-size:large; + color: #00557D; +} diff --git a/documentation/overview-manual/overview-manual-yp-intro.xml b/documentation/overview-manual/overview-manual-yp-intro.xml new file mode 100644 index 0000000000..437635842a --- /dev/null +++ b/documentation/overview-manual/overview-manual-yp-intro.xml @@ -0,0 +1,1335 @@ + %poky; ] > + + + Introducing the Yocto Project + +
+ What is the Yocto Project? + + + The Yocto Project is an open source collaboration project + that helps developers create custom Linux-based systems that are + designed for embedded products regardless of the product's hardware + architecture. + Yocto Project provides a flexible toolset and a development + environment that allows embedded device developers across the + world to collaborate through shared technologies, software stacks, + configurations, and best practices used to create these tailored + Linux images. + + + + Thousands of developers worldwide have discovered that Yocto + Project provides advantages in both systems and applications + development, archival and management benefits, and customizations + used for speed, footprint, and memory utilization. + The project is a standard when it comes to delivering hardware + support and software stacks, allowing software configuration + and build interchange, and build and support customizations for + multiple hardware platforms and software stacks that can be + maintained and scaled. + + + + + + + + For further introductory information on the Yocto Project, you + might be interested in this + article + by Drew Moseley and in this short introductory + video. + + + + The remainder of this section overviews advantages and challenges + tied to the Yocto Project. + + +
+ Features + + + The following list describes features and advantages of the + Yocto Project: + + + Widely Adopted Across the Industry: + Semiconductor, operating system, software, and + service vendors exist whose products and services + adopt and support the Yocto Project. + For a look at the companies involved with the Yocto + Project, see the membership, associate, and + participant pages on the Yocto Project home page. + + + Architecture Agnostic: + Yocto Project supports Intel, ARM, MIPS, AMD, PPC + and other architectures. + Most ODMs, OSVs, and chip vendors create and supply + BSPs that support their hardware. + If you have custom silicon, you can create a BSP + that supports that architecture. + + Aside from lots of architecture support, the + Yocto Project fully supports a wide range of device + emulation through the Quick EMUlator (QEMU). + + + Images and Code Transfer Easily: + Yocto Project output can easily move between + architectures without moving to new development + environments. + Additionally, if you have used the Yocto Project to + create an image or application and you find yourself + not able to support it, commercial Linux vendors such + as Wind River, Mentor Graphics, Timesys, and ENEA could + take it and provide ongoing support. + These vendors have offerings that are built using + the Yocto Project. + + + Flexibility: + Corporations use the Yocto Project many different ways. + One example is to create an internal Linux distribution + as a code base the corporation can use across multiple + product groups. + Through customization and layering, a project group + can leverage the base Linux distribution to create + a distribution that works for their product needs. + + + Ideal for Constrained Embedded and IoT devices: + Unlike a full Linux distribution, you can use the + Yocto Project to create exactly what you need for + embedded devices. + You only add the feature support or packages that you + absolutely need for the device. + For devices that have display hardware, you can use + available system components such as X11, GTK+, Qt, + Clutter, and SDL (among others) to create a rich user + experience. + For devices that do not have a display or where you + want to use alternative UI frameworks, you can choose + to not install these components. + + + Comprehensive Toolchain Capabilities: + Toolchains for supported architectures satisfy most + use cases. + However, if your hardware supports features that are + not part of a standard toolchain, you can easily + customize that toolchain through specification of + platform-specific tuning parameters. + And, should you need to use a third-party toolchain, + mechanisms built into the Yocto Project allow for that. + + + Mechanism Rules Over Policy: + Focusing on mechanism rather than policy ensures that + you are free to set policies based on the needs of your + design instead of adopting decisions enforced by some + system software provider. + + + Uses a Layer Model: + The Yocto Project layer infrastructure groups related + functionality into separate bundles. + You can incrementally add these grouped functionalities + to your project as needed. + Using layers to isolate and group functionality + reduces project complexity and redundancy, allows you + to easily extend the system, make customizations, + and keep functionality organized. + + + Supports Partial Builds: + You can build and rebuild individual packages as + needed. + Yocto Project accomplishes this through its + shared-state cache (sstate) scheme. + Being able to build and debug components individually + eases project development. + + + Releases According to a Strict Schedule: + Major releases occur on a six-month cycle predictably + in October and April. + The most recent two releases support point releases + to address common vulnerabilities and exposures. + This predictability is crucial for projects based on + the Yocto Project and allows development teams to + plan activities. + + + Rich Ecosystem of Individuals and Organizations: + For open source projects, the value of community is + very important. + Support forums, expertise, and active developers who + continue to push the Yocto Project forward are readily + available. + + + Binary Reproducibility: + The Yocto Project allows you to be very specific about + dependencies and achieves very high percentages of + binary reproducibility (e.g. 99.8% for + core-image-minimal). + When distributions are not specific about which + packages are pulled in and in what order to support + dependencies, other build systems can arbitrarily + include packages. + + + License Manifest: + The Yocto Project provides a license manifest for + review by people who need to track the use of open + source licenses (e.g.legal teams). + + + +
+ +
+ Challenges + + + The following list presents challenges you might encounter + when developing using the Yocto Project: + + + Steep Learning Curve: + The Yocto Project has a steep learning curve and has + many different ways to accomplish similar tasks. + It can be difficult to choose how to proceed when + varying methods exist by which to accomplish a given + task. + + + Understanding What Changes You Need to Make + For Your Design Requires Some Research: + Beyond the simple tutorial stage, understanding what + changes need to be made for your particular design + can require a significant amount of research and + investigation. + For information that helps you transition from + trying out the Yocto Project to using it for your + project, see the "What I wish I'd Known" and + "Transitioning to a Custom Environment for Systems + Development" documents on the Yocto Project website. + + + Project Workflow Could Be Confusing: + The Yocto Project workflow could be confusing if you + are used to traditional desktop and server software + development. + In a desktop development environment, mechanisms exist + to easily pull and install new packages, which are + typically pre-compiled binaries from servers accessible + over the Internet. + Using the Yocto Project, you must modify your + configuration and rebuild to add additional packages. + + + Working in a Cross-Build Environment Can + Feel Unfamiliar: + When developing code to run on a target, compilation, + execution, and testing done on the actual target + can be faster than running a BitBake build on a + development host and then deploying binaries to the + target for test. + While the Yocto Project does support development tools + on the target, the additional step of integrating your + changes back into the Yocto Project build environment + would be required. + Yocto Project supports an intermediate approach that + involves making changes on the development system + within the BitBake environment and then deploying only + the updated packages to the target. + + The Yocto Project OpenEmbedded build system + produces packages in standard formats (i.e. RPM, + DEB, IPK, and TAR). + You can deploy these packages into the running system + on the target by using utilities on the target such + as rpm or + ipk. + + + Initial Build Times Can be Significant: + Long initial build times are unfortunately unavoidable + due to the large number of packages initially built + from scratch for a fully functioning Linux system. + Once that initial build is completed, however, the + shared-state (sstate) cache mechanism Yocto Project + uses keeps the system from rebuilding packages that + have not been "touched" since the last build. + The sstate mechanism significantly reduces times + for successive builds. + + + +
+
+ +
+ The Yocto Project Layer Model + + + The Yocto Project's "Layer Model" is a development model for + embedded and IoT Linux creation that distinguishes the + Yocto Project from other simple build systems. + The Layer Model simultaneously supports collaboration and + customization. + Layers are repositories that contain related sets of instructions + that tell the OpenEmbedded build system what to do. + You can collaborate, share, and reuse layers. + + + + Layers can contain changes to previous instructions or settings + at any time. + This powerful override capability is what allows you to customize + previously supplied collaborative or community layers to suit your + product requirements. + + + + You use different layers to logically separate information in your + build. + As an example, you could have BSP, GUI, distro configuration, + middleware, or application layers. + Putting your entire build into one layer limits and complicates + future customization and reuse. + Isolating information into layers, on the other hand, helps + simplify future customizations and reuse. + You might find it tempting to keep everything in one layer when + working on a single project. + However, the more modular your Metadata, the easier + it is to cope with future changes. + Notes + + + Use Board Support Package (BSP) layers from silicon + vendors when possible. + + + Familiarize yourself with the + Yocto Project curated layer index + or the + OpenEmbedded layer index. + The latter contains more layers but they are less + universally validated. + + + Layers support the inclusion of technologies, hardware + components, and software components. + The Yocto Project Compatible designation provides a + minimum level of standardization that contributes to a + strong ecosystem. + "YP Compatible" is applied to appropriate products and + software components such as BSPs, other OE-compatible + layers, and related open-source projects, allowing the + producer to use Yocto Project badges and branding + assets. + + + + + + + To illustrate how layers are used to keep things modular, consider + machine customizations. + These types of customizations typically reside in a special layer, + rather than a general layer, called a BSP Layer. + Furthermore, the machine customizations should be isolated from + recipes and Metadata that support a new GUI environment, + for example. + This situation gives you a couple of layers: one for the machine + configurations, and one for the GUI environment. + It is important to understand, however, that the BSP layer can + still make machine-specific additions to recipes within the GUI + environment layer without polluting the GUI layer itself + with those machine-specific changes. + You can accomplish this through a recipe that is a BitBake append + (.bbappend) file, which is described later + in this section. + + For general information on BSP layer structure, see the + Board Support Packages (BSP) - Developer's Guide. + + + + + The + Source Directory + contains both general layers and BSP layers right out of the box. + You can easily identify layers that ship with a Yocto Project + release in the Source Directory by their names. + Layers typically have names that begin with the string + meta-. + + It is not a requirement that a layer name begin with the + prefix meta-, but it is a commonly + accepted standard in the Yocto Project community. + + For example, if you were to examine the + tree view + of the poky repository, you will see several + layers: meta, + meta-skeleton, + meta-selftest, + meta-poky, and + meta-yocto-bsp. + Each of these repositories represents a distinct layer. + + + + For procedures on how to create layers, see the + "Understanding and Creating Layers" + section in the Yocto Project Development Tasks Manual. + +
+ +
+ Components and Tools + + + The Yocto Project employs a collection of components and + tools used by the project itself, by project developers, + and by those using the Yocto Project. + These components and tools are open source projects and + metadata that are separate from the reference distribution + (Poky) and the OpenEmbedded build system. + Most of the components and tools are downloaded separately. + + + + This section provides brief overviews of the components and + tools associated with the Yocto Project. + + +
+ Development Tools + + + The following list consists of tools that help you develop + images and applications using the Yocto Project: + + + CROPS: + CROPS + is an open source, cross-platform development framework + that leverages + Docker Containers. + CROPS provides an easily managed, extensible environment + that allows you to build binaries for a variety of + architectures on Windows, Linux and Mac OS X hosts. + + + devtool: + This command-line tool is available as part of the + extensible SDK (eSDK) and is its cornerstone. + You can use devtool to help build, + test, and package software within the eSDK. + You can use the tool to optionally integrate what you + build into an image built by the OpenEmbedded build + system. + + The devtool command employs + a number of sub-commands that allow you to add, modify, + and upgrade recipes. + As with the OpenEmbedded build system, “recipes” + represent software packages within + devtool. + When you use devtool add, a recipe + is automatically created. + When you use devtool modify, the + specified existing recipe is used in order to determine + where to get the source code and how to patch it. + In both cases, an environment is set up so that when + you build the recipe a source tree that is under your + control is used in order to allow you to make changes + to the source as desired. + By default, both new recipes and the source go into + a “workspace” directory under the eSDK. + The devtool upgrade command + updates an existing recipe so that you can build it + for an updated set of source files. + + You can read about the + devtool workflow in the Yocto + Project Application Development and Extensible + Software Development Kit (eSDK) Manual in the + "Using devtool in Your SDK Workflow'" + section. + + + Extensible Software Development Kit (eSDK): + The eSDK provides a cross-development toolchain and + libraries tailored to the contents of a specific image. + The eSDK makes it easy to add new applications and + libraries to an image, modify the source for an + existing component, test changes on the target + hardware, and integrate into the rest of the + OpenEmbedded build system. + The eSDK gives you a toolchain experience supplemented + with the powerful set of devtool + commands tailored for the Yocto Project environment. + + + For information on the eSDK, see the + Yocto Project Application Development and Extensible Software Development Kit (eSDK) Manual. + + + Eclipse IDE Plug-in: + This plug-in enables you to use the popular Eclipse + Integrated Development Environment (IDE), which allows + for development using the Yocto Project all within the + Eclipse IDE. + You can work within Eclipse to cross-compile, deploy, + and execute your output into a QEMU emulation session + as well as onto actual target hardware. + + The environment also supports performance + enhancing tools that allow you to perform remote + profiling, tracing, collection of power data, + collection of latency data, and collection of + performance data. + + Once you enable the plug-in, standard Eclipse + functions automatically use the cross-toolchain + and target system libraries. + You can build applications using any of these + libraries. + + For more information on the Eclipse plug-in, + see the + "Working Within Eclipse" + section in the Yocto Project Application Development + and the Extensible Software Development Kit (eSDK) + manual. + + + Toaster: + Toaster is a web interface to the Yocto Project + OpenEmbedded build system. + Toaster allows you to configure, run, and view + information about builds. + + + +
+ +
+ Production Tools + + + The following list consists of tools that help production + related activities using the Yocto Project: + + + Auto Upgrade Helper: + This utility when used in conjunction with the + OpenEmbedded build system (BitBake and OE-Core) + automatically generates upgrades for recipes that + are based on new versions of the recipes published + upstream. + + + Recipe Reporting System: + The Recipe Reporting System tracks recipe versions + available for Yocto Project. + The main purpose of the system is to help you + manage the recipes you maintain and to offer a dynamic + overview of the project. + The Recipe Reporting System is built on top + the of OpenEmbedded Metadata Index, which is a website + that indexes layers for the OpenEmbedded build system. + + + Patchwork: + Patchwork + is a fork of a project originally started by + OzLabs. + The project is a web-based tracking system designed + to streamline the process of bringing contributions + into a project. + The Yocto Project uses Patchwork as an organizational + tool to handle patches, which number in the thousands + for every release. + + + AutoBuilder: + AutoBuilder is a project that automates build tests + and quality assurance (QA). + By using the public AutoBuilder, anyone can determine + the status of the current "master" branch of Poky. + + + A goal of the Yocto Project is to lead the + open source industry with a project that automates + testing and QA procedures. + In doing so, the project encourages a development + community that publishes QA and test plans, publicly + demonstrates QA and test plans, and encourages + development of tools that automate and test and QA + procedures for the benefit of the development + community. + + You can learn more about the AutoBuilder used + by the Yocto Project + here. + + + Cross-Prelink: + Prelinking is the process of pre-computing the load + addresses and link tables generated by the dynamic + linker as compared to doing this at runtime. + Doing this ahead of time results in performance + improvements when the application is launched and + reduced memory usage for libraries shared by many + applications. + + Historically, cross-prelink is a variant of + prelink, which was conceived by + Jakub Jelínek + a number of years ago. + Both prelink and cross-prelink are maintained in the + same repository albeit on separate branches. + By providing an emulated runtime dynamic linker + (i.e. glibc-derived + ld.so emulation), the + cross-prelink project extends the prelink software’s + ability to prelink a sysroot environment. + Additionally, the cross-prelink software enables the + ability to work in sysroot style environments. + + The dynamic linker determines standard load + address calculations based on a variety of factors + such as mapping addresses, library usage, and library + function conflicts. + The prelink tool uses this information, from the + dynamic linker, to determine unique load addresses + for executable and linkable format (ELF) binaries + that are shared libraries and dynamically linked. + The prelink tool modifies these ELF binaries with the + pre-computed information. + The result is faster loading and often lower memory + consumption because more of the library code can + be re-used from shared Copy-On-Write (COW) pages. + + + The original upstream prelink project only + supports running prelink on the end target device + due to the reliance on the target device’s dynamic + linker. + This restriction causes issues when developing a + cross-compiled system. + The cross-prelink adds a synthesized dynamic loader + that runs on the host, thus permitting cross-prelinking + without ever having to run on a read-write target + filesystem. + + + Pseudo: + Pseudo is the Yocto Project implementation of + fakeroot, + which is used to run commands in an environment + that seemingly has root privileges. + + During a build, it can be necessary to perform + operations that require system administrator + privileges. + For example, file ownership or permissions might need + definition. + Pseudo is a tool that you can either use directly or + through the environment variable + LD_PRELOAD. + Either method allows these operations to succeed as + if system administrator privileges exist even + when they do not. + + You can read more about Pseudo in the + "Fakeroot and Pseudo" + section of the Yocto Project Overview and Concepts + Manual. + + + +
+ +
+ Open-Embedded Build System Components + + + The following list consists of components associated with the + Open-Embedded build system: + + + BitBake: + BitBake is a core component of the Yocto Project and is + used by the OpenEmbedded build system to build images. + While BitBake is key to the build system, BitBake + is maintained separately from the Yocto Project. + + BitBake is a generic task execution engine that + allows shell and Python tasks to be run efficiently + and in parallel while working within complex inter-task + dependency constraints. + In short, BitBake is a build engine that works + through recipes written in a specific format in order + to perform sets of tasks. + + You can learn more about BitBake in the + BitBake User Manual. + + + OpenEmbedded-Core: + OpenEmbedded-Core (OE-Core) is a common layer of + metadata (i.e. recipes, classes, and associated files) + used by OpenEmbedded-derived systems, which includes + the Yocto Project. + The Yocto Project and the OpenEmbedded Project both + maintain the OpenEmbedded-Core. + You can find the OE-Core metadata in the Yocto + Project + Source Repositories + here. + + + Historically, the Yocto Project integrated the + OE-Core metadata throughout the Yocto Project + source repository reference system (Poky). + After Yocto Project Version 1.0, the Yocto Project + and OpenEmbedded agreed to work together and share a + common core set of metadata (OE-Core), which contained + much of the functionality previously found in Poky. + This collaboration achieved a long-standing + OpenEmbedded objective for having a more tightly + controlled and quality-assured core. + The results also fit well with the Yocto Project + objective of achieving a smaller number of fully + featured tools as compared to many different ones. + + + Sharing a core set of metadata results in Poky + as an integration layer on top of OE-Core. + You can see that in this + figure. + The Yocto Project combines various components such as + BitBake, OE-Core, script “glue”, and documentation + for its build system. + + + +
+ +
+ Reference Distribution (Poky) + + + Poky is the Yocto Project reference distribution. + It contains the OpenEmbedded build system (BitBake and OE-Core) + as well as a set of metadata to get you started building your + own distribution. + See the + figure in + "What is the Yocto Project?" section for an illustration + that shows Poky and its relationship with other parts of the + Yocto Project. + + To use the Yocto Project tools and components, you + can download (clone) Poky and use it + to bootstrap your own distribution. + + Poky does not contain binary files. + It is a working example of how to build your own custom + Linux distribution from source. + + You can read more about Poky in the + "Reference Embedded Distribution (Poky)" + section. + +
+ +
+ Packages for Finished Targets + + + The following lists components associated with packages + for finished targets: + + + Matchbox: + Matchbox is an Open Source, base environment for the + X Window System running on non-desktop, embedded + platforms such as handhelds, set-top boxes, kiosks, + and anything else for which screen space, input + mechanisms, or system resources are limited. + + Matchbox consists of a number of interchangeable + and optional applications that you can tailor to a + specific, non-desktop platform to enhance usability + in constrained environments. + + You can find the Matchbox source in its + repository + listed in the Yocto Project + Source Repositories. + + + Opkg + Open PacKaGe management (opkg) is a lightweight + package management system based on the itsy package + (ipkg) management system. + Opkg is written in C and resembles Advanced Package + Tool (APT) and Debian Package (dpkg) in operation. + + + Opkg is intended for use on embedded Linux + devices and is used in this capacity in the + OpenEmbedded + and + OpenWrt + projects, as well as the Yocto Project. + + As best it can, opkg maintains backwards + compatibility with ipkg and conforms to a subset + of Debian’s policy manual regarding control files. + + + + +
+ +
+ Archived Components + + + The Build Appliance is a virtual machine image that enables + you to build and boot a custom embedded Linux image with + the Yocto Project using a non-Linux development system. + + + + Historically, the Build Appliance was the second of three + methods by which you could use the Yocto Project on a system + that was not native to Linux. + + + Hob: + Hob, which is now deprecated and is no longer available + since the 2.1 release of the Yocto Project provided + a rudimentary, GUI-based interface to the Yocto + Project. + Toaster has fully replaced Hob. + + + Build Appliance: + Post Hob, the Build Appliance became available. + It was never recommended that you use the Build + Appliance as a day-to-day production development + environment with the Yocto Project. + Build Appliance was useful as a way to try out + development in the Yocto Project environment. + + + CROPS: + The final and best solution available now for + developing using the Yocto Project on a system + not native to Linux is with + CROPS. + + + +
+
+ +
+ Development Methods + + + The Yocto Project development environment usually involves a + Build Host + and target hardware. + You use the Build Host to build images and develop applications, + while you use the target hardware to test deployed software. + + + + This section provides an introduction to the choices or + development methods you have when setting up your Build Host. + Depending on the your particular workflow preference and the + type of operating system your Build Host runs, several choices + exist that allow you to use the Yocto Project. + + For additional detail about the Yocto Project development + environment, see the + "The Yocto Project Development Environment" + chapter. + + + + Native Linux Host: + By far the best option for a Build Host. + A system running Linux as its native operating system + allows you to develop software by directly using the + BitBake + tool. + You can accomplish all aspects of development from a + familiar shell of a supported Linux distribution. + + For information on how to set up a Build Host on + a system running Linux as its native operating system, + see the + "Setting Up a Native Linux Host" + section in the Yocto Project Development Tasks Manual. + + + CROss PlatformS (CROPS): + Typically, you use + CROPS, + which leverages + Docker Containers, + to set up a Build Host that is not running Linux (e.g. + Microsoft + Windows + or + macOS). + + You can, however, use CROPS on a Linux-based system. + + CROPS is an open source, cross-platform development + framework that provides an easily managed, extensible + environment for building binaries targeted for a variety + of architectures on Windows, macOS, or Linux hosts. + Once the Build Host is set up using CROPS, you can prepare + a shell environment to mimic that of a shell being used + on a system natively running Linux. + + For information on how to set up a Build Host with + CROPS, see the + "Setting Up to Use CROss PlatformS (CROPS)" + section in the Yocto Project Development Tasks Manual. + + + Toaster: + Regardless of what your Build Host is running, you can + use Toaster to develop software using the Yocto Project. + Toaster is a web interface to the Yocto Project's + OpenEmbedded build system. + The interface enables you to configure and run your + builds. + Information about builds is collected and stored in a + database. + You can use Toaster to configure and start builds on + multiple remote build servers. + + For information about and how to use Toaster, + see the + Toaster User Manual. + + + Eclipse IDE: + If your Build Host supports and runs the popular + Eclipse IDE, you can install the Yocto Project Eclipse + plug-in and use the Yocto Project to develop software. + The plug-in integrates the Yocto Project functionality + into Eclipse development practices. + + For information about how to install and use the + Yocto Project Eclipse plug-in, see the + "Developing Applications Using Eclipse" + section in the Yocto Project Application Development and + the Extensible Software Development Kit (eSDK) Manual. + + + +
+ +
+ Reference Embedded Distribution (Poky) + + + "Poky", which is pronounced Pock-ee, is the + name of the Yocto Project's reference distribution or Reference OS + Kit. + Poky contains the + OpenEmbedded Build System + build system + (BitBake and + OpenEmbedded-Core) + as well as a set of + metadata to get + you started building your own distro. + In other words, Poky is a base specification of the functionality + needed for a typical embedded system as well as the components + from the Yocto Project that allow you to build a distribution into + a usable binary image. + + + + Poky is a combined repository of BitBake, OpenEmbedded-Core + (which is found in meta), + meta-poky, + meta-yocto-bsp, and documentation provided + all together and known to work well together. + You can view these items that make up the Poky repository in the + Source Repositories. + + If you are interested in all the contents of the + poky Git repository, see the + "Top-Level Core Components" + section in the Yocto Project Reference Manual. + + + + + The following figure illustrates what generally comprises Poky: + + + + BitBake is a task executor and scheduler that is the heart of + the OpenEmbedded build system. + + + meta-poky, which is Poky-specific + metadata. + + + meta-yocto-bsp, which is Yocto + Project-specific Board Support Packages (BSPs). + + + OpenEmbedded-Core (OE-Core) metadata, which includes + shared configurations, global variable definitions, + shared classes, packaging, and recipes. + Classes define the encapsulation and inheritance of build + logic. + Recipes are the logical units of software and images + to be built. + + + Documentation, which contains the Yocto Project source + files used to make the set of user manuals. + + + + While Poky is a "complete" distribution specification and is + tested and put through QA, you cannot use it as a product + "out of the box" in its current form. + + + + + To use the Yocto Project tools, you can use Git to clone (download) + the Poky repository then use your local copy of the reference + distribution to bootstrap your own distribution. + + Poky does not contain binary files. + It is a working example of how to build your own custom Linux distribution + from source. + + + + + Poky has a regular, well established, six-month release cycle + under its own version. + Major releases occur at the same time major releases (point + releases) occur for the Yocto Project, which are typically in the + Spring and Fall. + For more information on the Yocto Project release schedule and + cadence, see the + "Yocto Project Releases and the Stable Release Process" + chapter in the Yocto Project Reference Manual. + + + + Much has been said about Poky being a "default configuration." + A default configuration provides a starting image footprint. + You can use Poky out of the box to create an image ranging from a + shell-accessible minimal image all the way up to a Linux + Standard Base-compliant image that uses a GNOME Mobile and + Embedded (GMAE) based reference user interface called Sato. + + + + One of the most powerful properties of Poky is that every aspect + of a build is controlled by the metadata. + You can use metadata to augment these base image types by + adding metadata layers that extend functionality. + These layers can provide, for example, an additional software + stack for an image type, add a board support package (BSP) for + additional hardware, or even create a new image type. + + + + Metadata is loosely grouped into configuration files or package + recipes. + A recipe is a collection of non-executable metadata used by + BitBake to set variables or define additional build-time tasks. + A recipe contains fields such as the recipe description, the recipe + version, the license of the package and the upstream source + repository. + A recipe might also indicate that the build process uses autotools, + make, distutils or any other build process, in which case the basic + functionality can be defined by the classes it inherits from + the OE-Core layer's class definitions in + ./meta/classes. + Within a recipe you can also define additional tasks as well as + task prerequisites. + Recipe syntax through BitBake also supports both + _prepend and _append + operators as a method of extending task functionality. + These operators inject code into the beginning or end of a task. + For information on these BitBake operators, see the + "Appending and Prepending (Override Style Syntax)" + section in the BitBake User's Manual. + +
+ +
+ The OpenEmbedded Build System Workflow + + + The OpenEmbedded build system uses a "workflow" to accomplish + image and SDK generation. + The following figure overviews that workflow: + + Following is a brief summary of the "workflow": + + + Developers specify architecture, policies, patches and + configuration details. + + + The build system fetches and downloads the source code + from the specified location. + The build system supports standard methods such as tarballs + or source code repositories systems such as Git. + + + Once downloaded, the build system extracts the sources + into a local work area where patches are applied and + common steps for configuring and compiling the software + are run. + + + The build system then installs the software into a + temporary staging area where the binary package format you + select (DEB, RPM, or IPK) is used to roll up the software. + + + Different QA and sanity checks run throughout entire + build process. + + + After the binaries are created, the build system + generates a binary package feed that is used to create + the final root file image. + + + The build system generates the file system image and a + customized Extensible SDK (eSDSK) for application + development in parallel. + + + + + + For a very detailed look at this workflow, see the + "Development Concepts" + section in the Yocto Project Overview and Concepts Manual. + +
+ + +
+ Some Basic Terms + + + It helps to understand some basic fundamental terms when + learning the Yocto Project. + Although a list of terms exists in the + "Yocto Project Terms" + section of the Yocto Project Reference Manual, this section + provides the definitions of some terms helpful for getting started: + + + Configuration Files: + Files that hold global definitions of variables, + user-defined variables, and hardware configuration + information. + These files tell the OpenEmbedded build system what to + build and what to put into the image to support a + particular platform. + + + Extensible Software Development Kit (eSDK): + A custom SDK for application developers. + This eSDK allows developers to incorporate their library + and programming changes back into the image to make + their code available to other application developers. + For information on the eSDK, see the + Yocto Project Application Development and Extensible Software Development Kit (eSDK) + manual. + + + Layer: + A collection of related recipes. + Layers allow you to consolidate related metadata to + customize your build. + Layers also isolate information used when building + for multiple architectures. + Layers are hierarchical in their ability to override + previous specifications. + You can include any number of available layers from the + Yocto Project and customize the build by adding your + layers after them. + You can search the Layer Index for layers used within + Yocto Project. + + For more detailed information on layers, see the + "Understanding and Creating Layers" + section in the Yocto Project Development Tasks Manual. + For a discussion specifically on BSP Layers, see the + "BSP Layers" + section in the Yocto Project Board Support Packages (BSP) + Developer's Guide. + + + Metadata: + A key element of the Yocto Project is the Metadata that + is used to construct a Linux distribution and is contained + in the files that the + OpenEmbedded build system parses + when building an image. + In general, Metadata includes recipes, configuration + files, and other information that refers to the build + instructions themselves, as well as the data used to + control what things get built and the effects of the + build. + Metadata also includes commands and data used to + indicate what versions of software are used, from + where they are obtained, and changes or additions to the + software itself (patches or auxiliary files) that + are used to fix bugs or customize the software for use + in a particular situation. + OpenEmbedded-Core is an important set of validated + metadata. + + + OpenEmbedded Build System: + The terms "BitBake" and "build system" are sometimes + used for the OpenEmbedded Build System. + + BitBake is a task scheduler and execution engine + that parses instructions (i.e. recipes) and configuration + data. + After a parsing phase, BitBake creates a dependency tree + to order the compilation, schedules the compilation of + the included code, and finally executes the building + of the specified custom Linux image (distribution). + BitBake is similar to the make + tool. + + During a build process, the build system tracks + dependencies and performs a native or cross-compilation + of the package. + As a first step in a cross-build setup, the framework + attempts to create a cross-compiler toolchain + (i.e. Extensible SDK) suited for the target platform. + + + OpenEmbedded-Core (OE-Core): + OE-Core is metadata comprised of foundation recipes, + classes, and associated files that are meant to be + common among many different OpenEmbedded-derived systems, + including the Yocto Project. + OE-Core is a curated subset of an original repository + developed by the OpenEmbedded community that has been + pared down into a smaller, core set of continuously + validated recipes. + The result is a tightly controlled and quality-assured + core set of recipes. + + You can see the Metadata in the + meta directory of the Yocto Project + Source Repositories. + + + Packages: + In the context of the Yocto Project, this term refers to a + recipe's packaged output produced by BitBake (i.e. a + "baked recipe"). + A package is generally the compiled binaries produced from the + recipe's sources. + You "bake" something by running it through BitBake. + + It is worth noting that the term "package" can, + in general, have subtle meanings. + For example, the packages referred to in the + "Required Packages for the Host Development System" + section in the Yocto Project Reference Manual are compiled + binaries that, when installed, add functionality to your + Linux distribution. + + Another point worth noting is that historically within + the Yocto Project, recipes were referred to as packages - thus, + the existence of several BitBake variables that are seemingly + mis-named, + (e.g. PR, + PV, + and + PE). + + + Poky: + Poky is a reference embedded distribution and a reference + test configuration. + Poky provides the following: + + + A base-level functional distro used to illustrate + how to customize a distribution. + + + A means by which to test the Yocto Project + components (i.e. Poky is used to validate + the Yocto Project). + + + A vehicle through which you can download + the Yocto Project. + + + Poky is not a product level distro. + Rather, it is a good starting point for customization. + + Poky is an integration layer on top of OE-Core. + + + + Recipe: + The most common form of metadata. + A recipe contains a list of settings and tasks + (i.e. instructions) for building packages that are then + used to build the binary image. + A recipe describes where you get source code and which + patches to apply. + Recipes describe dependencies for libraries or for other + recipes as well as configuration and compilation options. + Related recipes are consolidated into a layer. + + + +
+ + diff --git a/documentation/overview-manual/overview-manual.xml b/documentation/overview-manual/overview-manual.xml new file mode 100644 index 0000000000..f04fbaf3bd --- /dev/null +++ b/documentation/overview-manual/overview-manual.xml @@ -0,0 +1,108 @@ + %poky; ] > + + + + + + + + + + + + Yocto Project Overview and Concepts Manual + + + + + Scott Rifenbark + + Scotty's Documentation Services, INC + + srifenbark@gmail.com + + + + + + 2.5 + April 2018 + The initial document released with the Yocto Project 2.5 Release. + + + + + ©RIGHT_YEAR; + Linux Foundation + + + + + Permission is granted to copy, distribute and/or modify this document under + the terms of the + Creative Commons Attribution-Share Alike 2.0 UK: England & Wales as published by + Creative Commons. + + Manual Notes + + + This version of the + Yocto Project Overview and Concepts Manual + is for the &YOCTO_DOC_VERSION; release of the + Yocto Project. + To be sure you have the latest version of the manual + for this release, go to the + Yocto Project documentation page + and select the manual from that site. + Manuals from the site are more up-to-date than manuals + derived from the Yocto Project released TAR files. + + + If you located this manual through a web search, the + version of the manual might not be the one you want + (e.g. the search might have returned a manual much + older than the Yocto Project version with which you + are working). + You can see all Yocto Project major releases by + visiting the + Releases + page. + If you need a version of this manual for a different + Yocto Project release, visit the + Yocto Project documentation page + and select the manual set by using the + "ACTIVE RELEASES DOCUMENTATION" or "DOCUMENTS ARCHIVE" + pull-down menus. + + + To report any inaccuracies or problems with this + manual, send an email to the Yocto Project + discussion group at + yocto@yoctoproject.com or log into + the freenode #yocto channel. + + + + + + + + + + + + + + + + + diff --git a/documentation/poky.ent b/documentation/poky.ent index c7a691ef46..469d80f3de 100644 --- a/documentation/poky.ent +++ b/documentation/poky.ent @@ -62,7 +62,7 @@ - + diff --git a/documentation/tools/mega-manual.sed b/documentation/tools/mega-manual.sed index f93adba725..e1dc98ad42 100644 --- a/documentation/tools/mega-manual.sed +++ b/documentation/tools/mega-manual.sed @@ -16,7 +16,7 @@ s/"ulink" href="http:\/\/www.yoctoproject.org\/docs\/2.5\/poky-ref-manual\/poky- s/"ulink" href="http:\/\/www.yoctoproject.org\/docs\/2.5\/sdk-manual\/sdk-manual.html#/"link" href="#/g s/"ulink" href="http:\/\/www.yoctoproject.org\/docs\/2.5\/bsp-guide\/bsp-guide.html#/"link" href="#/g s/"ulink" href="http:\/\/www.yoctoproject.org\/docs\/2.5\/dev-manual\/dev-manual.html#/"link" href="#/g -s/"ulink" href="http:\/\/www.yoctoproject.org\/docs\/2.5\/getting-started\/getting-started.html#/"link" href="#/g +s/"ulink" href="http:\/\/www.yoctoproject.org\/docs\/2.5\/overview-manual\/overview-manual.html#/"link" href="#/g s/"ulink" href="http:\/\/www.yoctoproject.org\/docs\/2.5\/brief-yoctoprojectqs\/brief-yoctoprojectqs.html#/"link" href="#/g s/"ulink" href="http:\/\/www.yoctoproject.org\/docs\/2.5\/kernel-dev\/kernel-dev.html#/"link" href="#/g s/"ulink" href="http:\/\/www.yoctoproject.org\/docs\/2.5\/profile-manual\/profile-manual.html#/"link" href="#/g @@ -27,7 +27,7 @@ s/"ulink" href="http:\/\/www.yoctoproject.org\/docs\/2.5\/toaster-manual\/toaste s/Yocto Project Quick Build<\/a>/Yocto Project Quick Build/g s/Yocto Project Quick Start<\/a>/Yocto Project Quick Start/g s/Yocto Project Development Tasks Manual<\/a>/Yocto Project Development Tasks Manual/g -s/Yocto Project Overview and Concepts Manual<\/a>/Yocto project Overview and Concepts Manual/g +s/Yocto Project Overview and Concepts Manual<\/a>/Yocto project Overview and Concepts Manual/g s/Yocto Project Application Development and the Extensible Software Development Kit (eSDK)<\/a>/Yocto Project Application Development and the Extensible Software Development Kit (eSDK)/g s/Yocto Project Board Support Package (BSP) Developer's Guide<\/a>/Yocto Project Board Support Package (BSP) Developer's Guide/g s/Yocto Project Profiling and Tracing Manual<\/a>/Yocto Project Profiling and Tracing Manual/g -- cgit v1.2.3-54-g00ecf