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/ref-manual/introduction.xml | 937 ------------------------------ 1 file changed, 937 deletions(-) delete mode 100644 documentation/ref-manual/introduction.xml (limited to 'documentation/ref-manual/introduction.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. - - - -
- - - -- cgit v1.2.3-54-g00ecf