From 60cfd0785b2d64ec808e08ad9f716047542d8ba9 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Fri, 5 Jan 2018 15:43:42 -0800 Subject: ref-manual: Separated terms into separate chapter Pulling out some introductory information from the old "Introduction" chapter of the ref-manual has isolated the system requirements and term definitions sections. I have decided to create a new chapter for terms as they are a reference item. This leaves system requirements also alone as a new chapter. So, I dumped the introduction.xml chapter in favor of the two new chapters. (From yocto-docs rev: 35c41b3008845c94e10be19b37409b0d1a469ff5) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/mega-manual/mega-manual.xml | 5 +- documentation/ref-manual/introduction.xml | 937 --------------------- documentation/ref-manual/ref-manual.xml | 4 +- .../ref-manual/ref-system-requirements.xml | 492 +++++++++++ documentation/ref-manual/ref-terms.xml | 436 ++++++++++ 5 files changed, 935 insertions(+), 939 deletions(-) delete mode 100644 documentation/ref-manual/introduction.xml create mode 100644 documentation/ref-manual/ref-system-requirements.xml create mode 100644 documentation/ref-manual/ref-terms.xml diff --git a/documentation/mega-manual/mega-manual.xml b/documentation/mega-manual/mega-manual.xml index 68fb1e17d8..efefa17032 100644 --- a/documentation/mega-manual/mega-manual.xml +++ b/documentation/mega-manual/mega-manual.xml @@ -231,7 +231,10 @@ + xmlns:xi="http://www.w3.org/2003/XInclude" href="../ref-manual/ref-system-requirements.xml"/> + + diff --git a/documentation/ref-manual/introduction.xml b/documentation/ref-manual/introduction.xml deleted file mode 100644 index 098dbc8a22..0000000000 --- a/documentation/ref-manual/introduction.xml +++ /dev/null @@ -1,937 +0,0 @@ - %poky; ] > - - -Introduction - -
- Welcome - - - Welcome to the Yocto Project Reference Manual. - This manual provides reference information for the current release - of the Yocto Project. - This manual is best used after you have an understanding - of the basics of the Yocto Project. - The manual is neither meant to be read as a starting point to the - Yocto Project nor read from start to finish. - Use this manual to find concepts, variable definitions, class - descriptions, and so forth as needed during the course of using - the Yocto Project. - - - - For introductory information on the Yocto Project, see the - Yocto Project Website and the - "Yocto Project Development Environment" - chapter in the Yocto Project Overview Manual. - - - - If you want to use the Yocto Project to test run building an image - without having to understand concepts, work through the - Yocto Project Quick Start. - You can find "how-to" information in the - Yocto Project Development Tasks Manual. - Tip - For more information about the Yocto Project Documentation set, - see the - "Links and Related Documentation" - section. - - -
- -
-System Requirements - - For general Yocto Project system requirements, see the - "Setting Up to Use the Yocto Project" section - in the Yocto Project Quick Start. - The remainder of this section provides details on system requirements - not covered in the Yocto Project Quick Start. - - -
- Supported Linux Distributions - - - Currently, the Yocto Project is supported on the following - distributions: - - - Yocto Project releases are tested against the stable Linux - distributions in the following list. - The Yocto Project should work on other distributions but - validation is not performed against them. - - - - In particular, the Yocto Project does not support - and currently has no plans to support - rolling-releases or development distributions due to their - constantly changing nature. - We welcome patches and bug reports, but keep in mind that - our priority is on the supported platforms listed below. - - - - If you encounter problems, please go to - Yocto Project Bugzilla - and submit a bug. - We are interested in hearing about your experience. - - - - - Ubuntu 14.04 (LTS) - Ubuntu 14.10 - Ubuntu 15.04 - Ubuntu 15.10 - Ubuntu 16.04 - - Fedora release 22 - Fedora release 23 - - CentOS release 7.x - - Debian GNU/Linux 8.x (Jessie) - Debian GNU/Linux 9.x (Stretch) - - - openSUSE 13.2 - openSUSE 42.1 - - - - - While the Yocto Project Team attempts to ensure all Yocto Project - releases are one hundred percent compatible with each officially - supported Linux distribution, instances might exist where you - encounter a problem while using the Yocto Project on a specific - distribution. - -
- -
- Required Packages for the Host Development System - - - The list of packages you need on the host development system can - be large when covering all build scenarios using the Yocto Project. - This section provides required packages according to - Linux distribution and function. - - -
- Ubuntu and Debian - - - The following list shows the required packages by function - given a supported Ubuntu or Debian Linux distribution: - - If your build system has the - oss4-dev package installed, you - might experience QEMU build failures due to the package - installing its own custom - /usr/include/linux/soundcard.h on - the Debian system. - If you run into this situation, either of the following - solutions exist: - - $ sudo apt-get build-dep qemu - $ sudo apt-get remove oss4-dev - - - - Essentials: - Packages needed to build an image on a headless - system: - - $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL; - - Graphical and Eclipse Plug-In Extras: - Packages recommended if the host system has graphics - support or if you are going to use the Eclipse - IDE: - - $ sudo apt-get install libsdl1.2-dev xterm - - Documentation: - Packages needed if you are going to build out the - Yocto Project documentation manuals: - - $ sudo apt-get install make xsltproc docbook-utils fop dblatex xmlto - - OpenEmbedded Self-Test (oe-selftest): - Packages needed if you are going to run - oe-selftest: - - $ sudo apt-get install python-git - - - - -
- -
- Fedora Packages - - - The following list shows the required packages by function - given a supported Fedora Linux distribution: - - Essentials: - Packages needed to build an image for a headless - system: - - $ sudo dnf install &FEDORA_HOST_PACKAGES_ESSENTIAL; - - Graphical and Eclipse Plug-In Extras: - Packages recommended if the host system has graphics - support or if you are going to use the Eclipse - IDE: - - $ sudo dnf install SDL-devel xterm - - Documentation: - Packages needed if you are going to build out the - Yocto Project documentation manuals: - - $ sudo dnf install make docbook-style-dsssl docbook-style-xsl \ - docbook-dtds docbook-utils fop libxslt dblatex xmlto - - OpenEmbedded Self-Test (oe-selftest): - Packages needed if you are going to run - oe-selftest: - - $ sudo dnf install python3-GitPython - - - - -
- -
- openSUSE Packages - - - The following list shows the required packages by function - given a supported openSUSE Linux distribution: - - Essentials: - Packages needed to build an image for a headless - system: - - $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL; - - Graphical and Eclipse Plug-In Extras: - Packages recommended if the host system has graphics - support or if you are going to use the Eclipse - IDE: - - $ sudo zypper install libSDL-devel xterm - - Documentation: - Packages needed if you are going to build out the - Yocto Project documentation manuals: - - $ sudo zypper install make dblatex xmlto - - OpenEmbedded Self-Test (oe-selftest): - Packages needed if you are going to run - oe-selftest: - - $ sudo zypper install python-GitPython - - - - Sanity testing, through the - testimage - classes, does not work on systems using the - Wicked - network manager. - - -
- -
- CentOS Packages - - - The following list shows the required packages by function - given a supported CentOS Linux distribution: - - For CentOS 6.x, some of the versions of the components - provided by the distribution are too old (e.g. Git, Python, - and tar). - It is recommended that you install the buildtools in order - to provide versions that will work with the OpenEmbedded - build system. - For information on how to install the buildtools tarball, - see the - "Required Git, Tar, and Python Versions" - section. - - - Essentials: - Packages needed to build an image for a headless - system: - - $ sudo yum install &CENTOS_HOST_PACKAGES_ESSENTIAL; SDL-devel xterm - - Notes - - - Extra Packages for Enterprise Linux - (i.e. epel-release) - is a collection of packages from Fedora - built on RHEL/CentOS for easy installation - of packages not included in enterprise - Linux by default. - You need to install these packages - separately. - - - The makecache command - consumes additional Metadata from - epel-release. - - - - - Graphical and Eclipse Plug-In Extras: - Packages recommended if the host system has graphics - support or if you are going to use the Eclipse - IDE: - - $ sudo yum install SDL-devel xterm - - Documentation: - Packages needed if you are going to build out the - Yocto Project documentation manuals: - - $ sudo yum install make docbook-style-dsssl docbook-style-xsl \ - docbook-dtds docbook-utils fop libxslt dblatex xmlto - - OpenEmbedded Self-Test (oe-selftest): - Packages needed if you are going to run - oe-selftest: - - $ sudo yum install GitPython - - - - -
-
- -
- Required Git, tar, and Python Versions - - - In order to use the build system, your host development system - must meet the following version requirements for Git, tar, and - Python: - - Git 1.8.3.1 or greater - tar 1.27 or greater - Python 3.4.0 or greater - - - - - If your host development system does not meet all these requirements, - you can resolve this by installing a buildtools - tarball that contains these tools. - You can get the tarball one of two ways: download a pre-built - tarball or use BitBake to build the tarball. - - -
- Downloading a Pre-Built <filename>buildtools</filename> Tarball - - - Downloading and running a pre-built buildtools installer is - the easiest of the two methods by which you can get these tools: - - - Locate and download the *.sh at - . - - - Execute the installation script. - Here is an example: - - $ sh poky-glibc-x86_64-buildtools-tarball-x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh - - During execution, a prompt appears that allows you to - choose the installation directory. - For example, you could choose the following: - - /home/your-username/buildtools - - - - Source the tools environment setup script by using a - command like the following: - - $ source /home/your_username/buildtools/environment-setup-i586-poky-linux - - Of course, you need to supply your installation directory and be - sure to use the right file (i.e. i585 or x86-64). - - - After you have sourced the setup script, - the tools are added to PATH - and any other environment variables required to run the - tools are initialized. - The results are working versions versions of Git, tar, - Python and chrpath. - - - -
- -
- Building Your Own <filename>buildtools</filename> Tarball - - - Building and running your own buildtools installer applies - only when you have a build host that can already run BitBake. - In this case, you use that machine to build the - .sh file and then - take steps to transfer and run it on a - machine that does not meet the minimal Git, tar, and Python - requirements. - - - - Here are the steps to take to build and run your own - buildtools installer: - - - On the machine that is able to run BitBake, - be sure you have set up your build environment with - the setup script - (&OE_INIT_FILE;). - - - Run the BitBake command to build the tarball: - - $ bitbake buildtools-tarball - - - The - SDKMACHINE - variable in your local.conf file - determines whether you build tools for a 32-bit - or 64-bit system. - - Once the build completes, you can find the - .sh file that installs - the tools in the tmp/deploy/sdk - subdirectory of the - Build Directory. - The installer file has the string "buildtools" - in the name. - - - Transfer the .sh file from the - build host to the machine that does not meet the - Git, tar, or Python requirements. - - - On the machine that does not meet the requirements, - run the .sh file - to install the tools. - Here is an example: - - $ sh poky-glibc-x86_64-buildtools-tarball-x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh - - During execution, a prompt appears that allows you to - choose the installation directory. - For example, you could choose the following: - - /home/your_username/buildtools - - - - Source the tools environment setup script by using a - command like the following: - - $ source /home/your_username/buildtools/environment-setup-i586-poky-linux - - Of course, you need to supply your installation directory and be - sure to use the right file (i.e. i585 or x86-64). - - - After you have sourced the setup script, - the tools are added to PATH - and any other environment variables required to run the - tools are initialized. - The results are working versions versions of Git, tar, - Python and chrpath. - - - -
-
-
- -
- Yocto Project Terms - - - Following is a list of terms and definitions users new to the Yocto - Project development environment might find helpful. - While some of these terms are universal, the list includes them - just in case: - - - Append Files: - Files that append build information to a recipe file. - Append files are known as BitBake append files and - .bbappend files. - The OpenEmbedded build system expects every append file to have - a corresponding recipe (.bb) file. - Furthermore, the append file and corresponding recipe file - must use the same root filename. - The filenames can differ only in the file type suffix used - (e.g. - formfactor_0.0.bb and - formfactor_0.0.bbappend). - - Information in append files extends or overrides the - information in the similarly-named recipe file. - For an example of an append file in use, see the - "Using .bbappend Files in Your Layer" - section in the Yocto Project Development Tasks Manual. - - Append files can also use wildcard patterns in their - version numbers so they can be applied to more than one - version of the underlying recipe file. - - - - BitBake: - The task executor and scheduler used by the OpenEmbedded build - system to build images. - For more information on BitBake, see the - BitBake User Manual. - - - Board Support Package (BSP): - A group of drivers, definitions, and other components that - provide support for a specific hardware configuration. - For more information on BSPs, see the - Yocto Project Board Support Package (BSP) Developer's Guide. - - - - Build Directory: - This term refers to the area used by the OpenEmbedded build - system for builds. - The area is created when you source the - setup environment script that is found in the Source Directory - (i.e. &OE_INIT_FILE;). - The - TOPDIR - variable points to the Build Directory. - - You have a lot of flexibility when creating the Build - Directory. - Following are some examples that show how to create the - directory. - The examples assume your - Source Directory is - named poky: - - Create the Build Directory inside your - Source Directory and let the name of the Build - Directory default to build: - - $ cd $HOME/poky - $ source &OE_INIT_FILE; - - - Create the Build Directory inside your - home directory and specifically name it - test-builds: - - $ cd $HOME - $ source poky/&OE_INIT_FILE; test-builds - - - - Provide a directory path and specifically name the - Build Directory. - Any intermediate folders in the pathname must exist. - This next example creates a Build Directory named - YP-&POKYVERSION; - in your home directory within the existing - directory mybuilds: - - $cd $HOME - $ source $HOME/poky/&OE_INIT_FILE; $HOME/mybuilds/YP-&POKYVERSION; - - - - - By default, the Build Directory contains - TMPDIR, - which is a temporary directory the build system uses for - its work. - TMPDIR cannot be under NFS. - Thus, by default, the Build Directory cannot be under NFS. - However, if you need the Build Directory to be under NFS, - you can set this up by setting TMPDIR - in your local.conf file - to use a local drive. - Doing so effectively separates TMPDIR - from TOPDIR, which is the Build - Directory. - - - - Build System: - The system used to build images in a Yocto Project - Development environment. - The build system is sometimes referred to as the - development host. - - - Classes: - Files that provide for logic encapsulation and inheritance so - that commonly used patterns can be defined once and then - easily used in multiple recipes. - For reference information on the Yocto Project classes, see the - "Classes" chapter. - Class files end with the .bbclass - filename extension. - - - Configuration File: - Configuration information in various .conf - files provides global definitions of variables. - The conf/local.conf configuration file in - the - Build Directory - contains user-defined variables that affect every build. - The meta-poky/conf/distro/poky.conf - configuration file defines Yocto "distro" configuration - variables used only when building with this policy. - Machine configuration files, which - are located throughout the - Source Directory, define - variables for specific hardware and are only used when building - for that target (e.g. the - machine/beaglebone.conf configuration - file defines variables for the Texas Instruments ARM Cortex-A8 - development board). - Configuration files end with a .conf - filename extension. - - - Cross-Development Toolchain: - In general, a cross-development toolchain is a collection of - software development tools and utilities that run on one - architecture and allow you to develop software for a - different, or targeted, architecture. - These toolchains contain cross-compilers, linkers, and - debuggers that are specific to the target architecture. - - The Yocto Project supports two different cross-development - toolchains: - - - A toolchain only used by and within - BitBake when building an image for a target - architecture. - - A relocatable toolchain used outside of - BitBake by developers when developing applications - that will run on a targeted device. - - - - Creation of these toolchains is simple and automated. - For information on toolchain concepts as they apply to the - Yocto Project, see the - "Cross-Development Toolchain Generation" - section. - You can also find more information on using the - relocatable toolchain in the - Yocto Project Application Development and the Extensible Software Development Kit (eSDK) - manual. - - - Image: - An image is an artifact of the BitBake build process given - a collection of recipes and related Metadata. - Images are the binary output that run on specific hardware or - QEMU and are used for specific use-cases. - For a list of the supported image types that the Yocto Project - provides, see the - "Images" - chapter. - - - Layer: - A collection of recipes representing the core, - a BSP, or an application stack. - For a discussion specifically on BSP Layers, see the - "BSP Layers" - section in the Yocto Project Board Support Packages (BSP) - Developer's Guide. - - - Metadata: - The files that BitBake parses when building an image. - In general, Metadata includes recipes, classes, and - configuration files. - In the context of the kernel ("kernel Metadata"), the - term refers to the kernel config fragments and features - contained in the - yocto-kernel-cache - Git repository. - - - OE-Core: - A core set of Metadata originating with OpenEmbedded (OE) - that is shared between OE and the Yocto Project. - This Metadata is found in the meta - directory of the - Source Directory. - - - OpenEmbedded Build System: - The build system specific to the Yocto Project. - The OpenEmbedded build system is based on another project known - as "Poky", which uses - BitBake as the task - executor. - Throughout the Yocto Project documentation set, the - OpenEmbedded build system is sometimes referred to simply - as "the build system". - If other build systems, such as a host or target build system - are referenced, the documentation clearly states the - difference. - - For some historical information about Poky, see the - Poky term. - - - - Package: - 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 - "The Build Host Packages" - section in the Yocto Project Quick Start 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). - - - Package Groups: - Arbitrary groups of software Recipes. - You use package groups to hold recipes that, when built, - usually accomplish a single task. - For example, a package group could contain the recipes for a - company’s proprietary or value-add software. - Or, the package group could contain the recipes that enable - graphics. - A package group is really just another recipe. - Because package group files are recipes, they end with the - .bb filename extension. - - - Poky: - The term "poky", which is pronounced - Pah-kee, can mean several things: - - - In its most general sense, poky is an open-source - project that was initially developed by OpenedHand. - OpenedHand developed poky off of the existing - OpenEmbedded build system to create a commercially - supportable build system for embedded Linux. - After Intel Corporation acquired OpenedHand, the - poky project became the basis for the Yocto Project's - build system. - - - Within the Yocto Project - Source Repositories, - "poky" exists as a separate Git - repository from which you can clone to yield a local - Git repository that is a copy on your host system. - Thus, "poky" can refer to the upstream or - local copy of the files used for development within - the Yocto Project. - - - Finally, "poky" can refer to the default - DISTRO - (i.e. distribution) created when you use the Yocto - Project in conjunction with the - poky repository to build an image. - - - - - Recipe: - A set of instructions for building packages. - A recipe describes where you get source code, which patches - to apply, how to configure the source, how to compile it and so on. - Recipes also describe dependencies for libraries or for other - recipes. - Recipes represent the logical unit of execution, the software - to build, the images to build, and use the - .bb file extension. - - - Reference Kit: - A working example of a system, which includes a - BSP - as well as a - build system - and other components, that can work on specific hardware. - - - - Source Directory: - This term refers to the directory structure created as a result - of creating a local copy of the poky Git - repository git://git.yoctoproject.org/poky - or expanding a released poky tarball. - - Creating a local copy of the poky - Git repository is the recommended method for setting up - your Source Directory. - - Sometimes you might hear the term "poky directory" used to refer - to this directory structure. - - The OpenEmbedded build system does not support file or - directory names that contain spaces. - Be sure that the Source Directory you use does not contain - these types of names. - - - The Source Directory contains BitBake, Documentation, - Metadata and other files that all support the Yocto Project. - Consequently, you must have the Source Directory in place on - your development system in order to do any development using - the Yocto Project. - - When you create a local copy of the Git repository, you - can name the repository anything you like. - Throughout much of the documentation, "poky" - is used as the name of the top-level folder of the local copy of - the poky Git repository. - So, for example, cloning the poky Git - repository results in a local Git repository whose top-level - folder is also named "poky". - - While it is not recommended that you use tarball expansion - to set up the Source Directory, if you do, the top-level - directory name of the Source Directory is derived from the - Yocto Project release tarball. - For example, downloading and unpacking - &YOCTO_POKY_TARBALL; results in a - Source Directory whose root folder is named - &YOCTO_POKY;. - - It is important to understand the differences between the - Source Directory created by unpacking a released tarball as - compared to cloning - git://git.yoctoproject.org/poky. - When you unpack a tarball, you have an exact copy of the files - based on the time of release - a fixed release point. - Any changes you make to your local files in the Source Directory - are on top of the release and will remain local only. - On the other hand, when you clone the poky - Git repository, you have an active development repository with - access to the upstream repository's branches and tags. - In this case, any local changes you make to the local - Source Directory can be later applied to active development - branches of the upstream poky Git - repository. - - For more information on concepts related to Git - repositories, branches, and tags, see the - "Repositories, Tags, and Branches" - section in the Yocto Project Overview Manual. - - Task: - A unit of execution for BitBake (e.g. - do_compile, - do_fetch, - do_patch, - and so forth). - - Toaster: - 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. - For information on Toaster, see the - Yocto Project Toaster Manual. - - - Upstream: - A reference to source code or repositories - that are not local to the development system but located in a - master area that is controlled by the maintainer of the source - code. - For example, in order for a developer to work on a particular - piece of code, they need to first get a copy of it from an - "upstream" source. - - - -
- - - diff --git a/documentation/ref-manual/ref-manual.xml b/documentation/ref-manual/ref-manual.xml index a24a9e310d..e69ab72c62 100644 --- a/documentation/ref-manual/ref-manual.xml +++ b/documentation/ref-manual/ref-manual.xml @@ -166,7 +166,9 @@ - + + + diff --git a/documentation/ref-manual/ref-system-requirements.xml b/documentation/ref-manual/ref-system-requirements.xml new file mode 100644 index 0000000000..dfa2c2b6d1 --- /dev/null +++ b/documentation/ref-manual/ref-system-requirements.xml @@ -0,0 +1,492 @@ + %poky; ] > + + +System Requirements + + + Welcome to the Yocto Project Reference Manual! + This manual provides reference information for the current release + of the Yocto Project. + The manual is best used after you have an understanding + of the basics of the Yocto Project. + The manual is neither meant to be read as a starting point to the + Yocto Project nor read from start to finish. + Use this manual to find variable definitions, class + descriptions, and so forth as needed during the course of using + the Yocto Project. + + + + For introductory information on the Yocto Project, see the + Yocto Project Website and the + "Yocto Project Development Environment" + chapter in the Yocto Project Overview Manual. + + + + If you want to use the Yocto Project to test run building an image + without having to understand concepts, work through the + Yocto Project Quick Start. + You can find "how-to" information in the + Yocto Project Development Tasks Manual. + Tip + For more information about the Yocto Project Documentation set, + see the + "Links and Related Documentation" + section. + + + +
+ Supported Linux Distributions + + + Currently, the Yocto Project is supported on the following + distributions: + + + Yocto Project releases are tested against the stable Linux + distributions in the following list. + The Yocto Project should work on other distributions but + validation is not performed against them. + + + + In particular, the Yocto Project does not support + and currently has no plans to support + rolling-releases or development distributions due to their + constantly changing nature. + We welcome patches and bug reports, but keep in mind that + our priority is on the supported platforms listed below. + + + + If you encounter problems, please go to + Yocto Project Bugzilla + and submit a bug. + We are interested in hearing about your experience. + + + + + Ubuntu 14.04 (LTS) + Ubuntu 14.10 + Ubuntu 15.04 + Ubuntu 15.10 + Ubuntu 16.04 + + Fedora release 22 + Fedora release 23 + + CentOS release 7.x + + Debian GNU/Linux 8.x (Jessie) + Debian GNU/Linux 9.x (Stretch) + + + openSUSE 13.2 + openSUSE 42.1 + + + + + While the Yocto Project Team attempts to ensure all Yocto Project + releases are one hundred percent compatible with each officially + supported Linux distribution, instances might exist where you + encounter a problem while using the Yocto Project on a specific + distribution. + +
+ +
+ Required Packages for the Host Development System + + + The list of packages you need on the host development system can + be large when covering all build scenarios using the Yocto Project. + This section provides required packages according to + Linux distribution and function. + + +
+ Ubuntu and Debian + + + The following list shows the required packages by function + given a supported Ubuntu or Debian Linux distribution: + + If your build system has the + oss4-dev package installed, you + might experience QEMU build failures due to the package + installing its own custom + /usr/include/linux/soundcard.h on + the Debian system. + If you run into this situation, either of the following + solutions exist: + + $ sudo apt-get build-dep qemu + $ sudo apt-get remove oss4-dev + + + + Essentials: + Packages needed to build an image on a headless + system: + + $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL; + + Graphical and Eclipse Plug-In Extras: + Packages recommended if the host system has graphics + support or if you are going to use the Eclipse + IDE: + + $ sudo apt-get install libsdl1.2-dev xterm + + Documentation: + Packages needed if you are going to build out the + Yocto Project documentation manuals: + + $ sudo apt-get install make xsltproc docbook-utils fop dblatex xmlto + + OpenEmbedded Self-Test (oe-selftest): + Packages needed if you are going to run + oe-selftest: + + $ sudo apt-get install python-git + + + + +
+ +
+ Fedora Packages + + + The following list shows the required packages by function + given a supported Fedora Linux distribution: + + Essentials: + Packages needed to build an image for a headless + system: + + $ sudo dnf install &FEDORA_HOST_PACKAGES_ESSENTIAL; + + Graphical and Eclipse Plug-In Extras: + Packages recommended if the host system has graphics + support or if you are going to use the Eclipse + IDE: + + $ sudo dnf install SDL-devel xterm + + Documentation: + Packages needed if you are going to build out the + Yocto Project documentation manuals: + + $ sudo dnf install make docbook-style-dsssl docbook-style-xsl \ + docbook-dtds docbook-utils fop libxslt dblatex xmlto + + OpenEmbedded Self-Test (oe-selftest): + Packages needed if you are going to run + oe-selftest: + + $ sudo dnf install python3-GitPython + + + + +
+ +
+ openSUSE Packages + + + The following list shows the required packages by function + given a supported openSUSE Linux distribution: + + Essentials: + Packages needed to build an image for a headless + system: + + $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL; + + Graphical and Eclipse Plug-In Extras: + Packages recommended if the host system has graphics + support or if you are going to use the Eclipse + IDE: + + $ sudo zypper install libSDL-devel xterm + + Documentation: + Packages needed if you are going to build out the + Yocto Project documentation manuals: + + $ sudo zypper install make dblatex xmlto + + OpenEmbedded Self-Test (oe-selftest): + Packages needed if you are going to run + oe-selftest: + + $ sudo zypper install python-GitPython + + + + Sanity testing, through the + testimage + classes, does not work on systems using the + Wicked + network manager. + + +
+ +
+ CentOS Packages + + + The following list shows the required packages by function + given a supported CentOS Linux distribution: + + For CentOS 6.x, some of the versions of the components + provided by the distribution are too old (e.g. Git, Python, + and tar). + It is recommended that you install the buildtools in order + to provide versions that will work with the OpenEmbedded + build system. + For information on how to install the buildtools tarball, + see the + "Required Git, Tar, and Python Versions" + section. + + + Essentials: + Packages needed to build an image for a headless + system: + + $ sudo yum install &CENTOS_HOST_PACKAGES_ESSENTIAL; SDL-devel xterm + + Notes + + + Extra Packages for Enterprise Linux + (i.e. epel-release) + is a collection of packages from Fedora + built on RHEL/CentOS for easy installation + of packages not included in enterprise + Linux by default. + You need to install these packages + separately. + + + The makecache command + consumes additional Metadata from + epel-release. + + + + + Graphical and Eclipse Plug-In Extras: + Packages recommended if the host system has graphics + support or if you are going to use the Eclipse + IDE: + + $ sudo yum install SDL-devel xterm + + Documentation: + Packages needed if you are going to build out the + Yocto Project documentation manuals: + + $ sudo yum install make docbook-style-dsssl docbook-style-xsl \ + docbook-dtds docbook-utils fop libxslt dblatex xmlto + + OpenEmbedded Self-Test (oe-selftest): + Packages needed if you are going to run + oe-selftest: + + $ sudo yum install GitPython + + + + +
+
+ +
+ Required Git, tar, and Python Versions + + + In order to use the build system, your host development system + must meet the following version requirements for Git, tar, and + Python: + + Git 1.8.3.1 or greater + tar 1.27 or greater + Python 3.4.0 or greater + + + + + If your host development system does not meet all these requirements, + you can resolve this by installing a buildtools + tarball that contains these tools. + You can get the tarball one of two ways: download a pre-built + tarball or use BitBake to build the tarball. + + +
+ Downloading a Pre-Built <filename>buildtools</filename> Tarball + + + Downloading and running a pre-built buildtools installer is + the easiest of the two methods by which you can get these tools: + + + Locate and download the *.sh at + . + + + Execute the installation script. + Here is an example: + + $ sh poky-glibc-x86_64-buildtools-tarball-x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh + + During execution, a prompt appears that allows you to + choose the installation directory. + For example, you could choose the following: + + /home/your-username/buildtools + + + + Source the tools environment setup script by using a + command like the following: + + $ source /home/your_username/buildtools/environment-setup-i586-poky-linux + + Of course, you need to supply your installation directory and be + sure to use the right file (i.e. i585 or x86-64). + + + After you have sourced the setup script, + the tools are added to PATH + and any other environment variables required to run the + tools are initialized. + The results are working versions versions of Git, tar, + Python and chrpath. + + + +
+ +
+ Building Your Own <filename>buildtools</filename> Tarball + + + Building and running your own buildtools installer applies + only when you have a build host that can already run BitBake. + In this case, you use that machine to build the + .sh file and then + take steps to transfer and run it on a + machine that does not meet the minimal Git, tar, and Python + requirements. + + + + Here are the steps to take to build and run your own + buildtools installer: + + + On the machine that is able to run BitBake, + be sure you have set up your build environment with + the setup script + (&OE_INIT_FILE;). + + + Run the BitBake command to build the tarball: + + $ bitbake buildtools-tarball + + + The + SDKMACHINE + variable in your local.conf file + determines whether you build tools for a 32-bit + or 64-bit system. + + Once the build completes, you can find the + .sh file that installs + the tools in the tmp/deploy/sdk + subdirectory of the + Build Directory. + The installer file has the string "buildtools" + in the name. + + + Transfer the .sh file from the + build host to the machine that does not meet the + Git, tar, or Python requirements. + + + On the machine that does not meet the requirements, + run the .sh file + to install the tools. + Here is an example: + + $ sh poky-glibc-x86_64-buildtools-tarball-x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh + + During execution, a prompt appears that allows you to + choose the installation directory. + For example, you could choose the following: + + /home/your_username/buildtools + + + + Source the tools environment setup script by using a + command like the following: + + $ source /home/your_username/buildtools/environment-setup-i586-poky-linux + + Of course, you need to supply your installation directory and be + sure to use the right file (i.e. i585 or x86-64). + + + After you have sourced the setup script, + the tools are added to PATH + and any other environment variables required to run the + tools are initialized. + The results are working versions versions of Git, tar, + Python and chrpath. + + + +
+
+ + diff --git a/documentation/ref-manual/ref-terms.xml b/documentation/ref-manual/ref-terms.xml new file mode 100644 index 0000000000..f5ff7df5fb --- /dev/null +++ b/documentation/ref-manual/ref-terms.xml @@ -0,0 +1,436 @@ + %poky; ] > + + +Yocto Project Terms + + + Following is a list of terms and definitions users new to the Yocto + Project development environment might find helpful. + While some of these terms are universal, the list includes them + just in case: + + + Append Files: + Files that append build information to a recipe file. + Append files are known as BitBake append files and + .bbappend files. + The OpenEmbedded build system expects every append file to have + a corresponding recipe (.bb) file. + Furthermore, the append file and corresponding recipe file + must use the same root filename. + The filenames can differ only in the file type suffix used + (e.g. + formfactor_0.0.bb and + formfactor_0.0.bbappend). + + Information in append files extends or overrides the + information in the similarly-named recipe file. + For an example of an append file in use, see the + "Using .bbappend Files in Your Layer" + section in the Yocto Project Development Tasks Manual. + + Append files can also use wildcard patterns in their + version numbers so they can be applied to more than one + version of the underlying recipe file. + + + + BitBake: + The task executor and scheduler used by the OpenEmbedded build + system to build images. + For more information on BitBake, see the + BitBake User Manual. + + + Board Support Package (BSP): + A group of drivers, definitions, and other components that + provide support for a specific hardware configuration. + For more information on BSPs, see the + Yocto Project Board Support Package (BSP) Developer's Guide. + + + + Build Directory: + This term refers to the area used by the OpenEmbedded build + system for builds. + The area is created when you source the + setup environment script that is found in the Source Directory + (i.e. &OE_INIT_FILE;). + The + TOPDIR + variable points to the Build Directory. + + You have a lot of flexibility when creating the Build + Directory. + Following are some examples that show how to create the + directory. + The examples assume your + Source Directory is + named poky: + + Create the Build Directory inside your + Source Directory and let the name of the Build + Directory default to build: + + $ cd $HOME/poky + $ source &OE_INIT_FILE; + + + Create the Build Directory inside your + home directory and specifically name it + test-builds: + + $ cd $HOME + $ source poky/&OE_INIT_FILE; test-builds + + + + Provide a directory path and specifically name the + Build Directory. + Any intermediate folders in the pathname must exist. + This next example creates a Build Directory named + YP-&POKYVERSION; + in your home directory within the existing + directory mybuilds: + + $cd $HOME + $ source $HOME/poky/&OE_INIT_FILE; $HOME/mybuilds/YP-&POKYVERSION; + + + + + By default, the Build Directory contains + TMPDIR, + which is a temporary directory the build system uses for + its work. + TMPDIR cannot be under NFS. + Thus, by default, the Build Directory cannot be under NFS. + However, if you need the Build Directory to be under NFS, + you can set this up by setting TMPDIR + in your local.conf file + to use a local drive. + Doing so effectively separates TMPDIR + from TOPDIR, which is the Build + Directory. + + + + Build System: + The system used to build images in a Yocto Project + Development environment. + The build system is sometimes referred to as the + development host. + + + Classes: + Files that provide for logic encapsulation and inheritance so + that commonly used patterns can be defined once and then + easily used in multiple recipes. + For reference information on the Yocto Project classes, see the + "Classes" chapter. + Class files end with the .bbclass + filename extension. + + + Configuration File: + Configuration information in various .conf + files provides global definitions of variables. + The conf/local.conf configuration file in + the + Build Directory + contains user-defined variables that affect every build. + The meta-poky/conf/distro/poky.conf + configuration file defines Yocto "distro" configuration + variables used only when building with this policy. + Machine configuration files, which + are located throughout the + Source Directory, define + variables for specific hardware and are only used when building + for that target (e.g. the + machine/beaglebone.conf configuration + file defines variables for the Texas Instruments ARM Cortex-A8 + development board). + Configuration files end with a .conf + filename extension. + + + Cross-Development Toolchain: + In general, a cross-development toolchain is a collection of + software development tools and utilities that run on one + architecture and allow you to develop software for a + different, or targeted, architecture. + These toolchains contain cross-compilers, linkers, and + debuggers that are specific to the target architecture. + + The Yocto Project supports two different cross-development + toolchains: + + + A toolchain only used by and within + BitBake when building an image for a target + architecture. + + A relocatable toolchain used outside of + BitBake by developers when developing applications + that will run on a targeted device. + + + + Creation of these toolchains is simple and automated. + For information on toolchain concepts as they apply to the + Yocto Project, see the + "Cross-Development Toolchain Generation" + section. + You can also find more information on using the + relocatable toolchain in the + Yocto Project Application Development and the Extensible Software Development Kit (eSDK) + manual. + + + Image: + An image is an artifact of the BitBake build process given + a collection of recipes and related Metadata. + Images are the binary output that run on specific hardware or + QEMU and are used for specific use-cases. + For a list of the supported image types that the Yocto Project + provides, see the + "Images" + chapter. + + + Layer: + A collection of recipes representing the core, + a BSP, or an application stack. + For a discussion specifically on BSP Layers, see the + "BSP Layers" + section in the Yocto Project Board Support Packages (BSP) + Developer's Guide. + + + Metadata: + The files that BitBake parses when building an image. + In general, Metadata includes recipes, classes, and + configuration files. + In the context of the kernel ("kernel Metadata"), the + term refers to the kernel config fragments and features + contained in the + yocto-kernel-cache + Git repository. + + + OE-Core: + A core set of Metadata originating with OpenEmbedded (OE) + that is shared between OE and the Yocto Project. + This Metadata is found in the meta + directory of the + Source Directory. + + + OpenEmbedded Build System: + The build system specific to the Yocto Project. + The OpenEmbedded build system is based on another project known + as "Poky", which uses + BitBake as the task + executor. + Throughout the Yocto Project documentation set, the + OpenEmbedded build system is sometimes referred to simply + as "the build system". + If other build systems, such as a host or target build system + are referenced, the documentation clearly states the + difference. + + For some historical information about Poky, see the + Poky term. + + + + Package: + 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 + "The Build Host Packages" + section in the Yocto Project Quick Start 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). + + + Package Groups: + Arbitrary groups of software Recipes. + You use package groups to hold recipes that, when built, + usually accomplish a single task. + For example, a package group could contain the recipes for a + company’s proprietary or value-add software. + Or, the package group could contain the recipes that enable + graphics. + A package group is really just another recipe. + Because package group files are recipes, they end with the + .bb filename extension. + + + Poky: + The term "poky", which is pronounced + Pah-kee, can mean several things: + + + In its most general sense, poky is an open-source + project that was initially developed by OpenedHand. + OpenedHand developed poky off of the existing + OpenEmbedded build system to create a commercially + supportable build system for embedded Linux. + After Intel Corporation acquired OpenedHand, the + poky project became the basis for the Yocto Project's + build system. + + + Within the Yocto Project + Source Repositories, + "poky" exists as a separate Git + repository from which you can clone to yield a local + Git repository that is a copy on your host system. + Thus, "poky" can refer to the upstream or + local copy of the files used for development within + the Yocto Project. + + + Finally, "poky" can refer to the default + DISTRO + (i.e. distribution) created when you use the Yocto + Project in conjunction with the + poky repository to build an image. + + + + + Recipe: + A set of instructions for building packages. + A recipe describes where you get source code, which patches + to apply, how to configure the source, how to compile it and so on. + Recipes also describe dependencies for libraries or for other + recipes. + Recipes represent the logical unit of execution, the software + to build, the images to build, and use the + .bb file extension. + + + Reference Kit: + A working example of a system, which includes a + BSP + as well as a + build system + and other components, that can work on specific hardware. + + + + Source Directory: + This term refers to the directory structure created as a result + of creating a local copy of the poky Git + repository git://git.yoctoproject.org/poky + or expanding a released poky tarball. + + Creating a local copy of the poky + Git repository is the recommended method for setting up + your Source Directory. + + Sometimes you might hear the term "poky directory" used to refer + to this directory structure. + + The OpenEmbedded build system does not support file or + directory names that contain spaces. + Be sure that the Source Directory you use does not contain + these types of names. + + + The Source Directory contains BitBake, Documentation, + Metadata and other files that all support the Yocto Project. + Consequently, you must have the Source Directory in place on + your development system in order to do any development using + the Yocto Project. + + When you create a local copy of the Git repository, you + can name the repository anything you like. + Throughout much of the documentation, "poky" + is used as the name of the top-level folder of the local copy of + the poky Git repository. + So, for example, cloning the poky Git + repository results in a local Git repository whose top-level + folder is also named "poky". + + While it is not recommended that you use tarball expansion + to set up the Source Directory, if you do, the top-level + directory name of the Source Directory is derived from the + Yocto Project release tarball. + For example, downloading and unpacking + &YOCTO_POKY_TARBALL; results in a + Source Directory whose root folder is named + &YOCTO_POKY;. + + It is important to understand the differences between the + Source Directory created by unpacking a released tarball as + compared to cloning + git://git.yoctoproject.org/poky. + When you unpack a tarball, you have an exact copy of the files + based on the time of release - a fixed release point. + Any changes you make to your local files in the Source Directory + are on top of the release and will remain local only. + On the other hand, when you clone the poky + Git repository, you have an active development repository with + access to the upstream repository's branches and tags. + In this case, any local changes you make to the local + Source Directory can be later applied to active development + branches of the upstream poky Git + repository. + + For more information on concepts related to Git + repositories, branches, and tags, see the + "Repositories, Tags, and Branches" + section in the Yocto Project Overview Manual. + + Task: + A unit of execution for BitBake (e.g. + do_compile, + do_fetch, + do_patch, + and so forth). + + Toaster: + 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. + For information on Toaster, see the + Yocto Project Toaster Manual. + + + Upstream: + A reference to source code or repositories + that are not local to the development system but located in a + master area that is controlled by the maintainer of the source + code. + For example, in order for a developer to work on a particular + piece of code, they need to first get a copy of it from an + "upstream" source. + + + + + + -- cgit v1.2.3-54-g00ecf