diff options
Diffstat (limited to 'import-layers/yocto-poky/documentation/ref-manual/introduction.xml')
| -rw-r--r-- | import-layers/yocto-poky/documentation/ref-manual/introduction.xml | 691 |
1 files changed, 580 insertions, 111 deletions
diff --git a/import-layers/yocto-poky/documentation/ref-manual/introduction.xml b/import-layers/yocto-poky/documentation/ref-manual/introduction.xml index eec6cb34f..29ef2d550 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/introduction.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/introduction.xml @@ -5,118 +5,159 @@ <chapter id='ref-manual-intro'> <title>Introduction</title> -<section id='intro-welcome'> - <title>Introduction</title> +<section id='ref-welcome'> + <title>Welcome</title> <para> + Welcome to the Yocto Project Reference Manual. This manual provides reference information for the current release of the Yocto Project. - The Yocto Project is an open-source collaboration project focused - on embedded Linux developers. - Amongst other things, the Yocto Project uses the OpenEmbedded build - system, which is based on the Poky project, to construct complete - Linux images. - You can find complete introductory and getting started information - on the Yocto Project by reading the - <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>. + 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. </para> <para> - For task-based information using the Yocto Project, see the - <ulink url='&YOCTO_DOCS_DEV_URL;'>Yocto Project Development Manual</ulink> - and the <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>. - For Board Support Package (BSP) structure information, see the - <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>. - For information on how to use a Software Development Kit, (SDK), see the - <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>. - You can find information on tracing and profiling in the - <ulink url='&YOCTO_DOCS_PROF_URL;'>Yocto Project Profiling and Tracing Manual</ulink>. - For information on BitBake, which is the task execution tool the - OpenEmbedded build system is based on, see the - <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual'>BitBake User Manual</ulink>. - Finally, you can also find lots of Yocto Project information on the - <ulink url="&YOCTO_HOME_URL;">Yocto Project website</ulink>. + For introductory information on the Yocto Project, see the + <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink> and the + "<link linkend='yp-intro'>Introducing the Yocto Project Development Environment</link>" + section. </para> -</section> -<section id='intro-manualoverview'> - <title>Documentation Overview</title> <para> - This reference manual consists of the following: - <itemizedlist> - <listitem><para><emphasis> - <link linkend='usingpoky'>Using the Yocto Project</link>:</emphasis> - Provides an overview of the components that make up the Yocto Project - followed by information about debugging images created in the Yocto Project. - </para></listitem> - <listitem><para><emphasis> - <link linkend='closer-look'>A Closer Look at the Yocto Project Development Environment</link>:</emphasis> - Provides a more detailed look at the Yocto Project development - environment within the context of development. - </para></listitem> - <listitem><para><emphasis> - <link linkend='technical-details'>Technical Details</link>:</emphasis> - Describes fundamental Yocto Project components as well as an explanation - behind how the Yocto Project uses shared state (sstate) cache to speed build time. - </para></listitem> - <listitem><para><emphasis> - <link linkend='migration'>Migrating to a Newer Yocto Project Release</link>:</emphasis> - Describes release-specific information that helps you move from - one Yocto Project Release to another. - </para></listitem> - <listitem><para><emphasis> - <link linkend='ref-structure'>Directory Structure</link>:</emphasis> - Describes the - <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> created - either by unpacking a released Yocto Project tarball on your host development system, - or by cloning the upstream - <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>Poky</ulink> Git repository. - </para></listitem> - <listitem><para><emphasis> - <link linkend='ref-classes'>Classes</link>:</emphasis> - Describes the classes used in the Yocto Project.</para></listitem> - <listitem><para><emphasis> - <link linkend='ref-tasks'>Tasks</link>:</emphasis> - Describes the tasks defined by the OpenEmbedded build system. - </para></listitem> - <listitem><para><emphasis> - <link linkend='ref-devtool-reference'><filename>devtool</filename> Quick Reference</link>:</emphasis> - Provides a quick reference for the <filename>devtool</filename> - command. - </para></listitem> - <listitem><para><emphasis> - <link linkend='ref-qa-checks'>QA Error and Warning Messages</link>:</emphasis> - Lists and describes QA warning and error messages. - </para></listitem> - <listitem><para><emphasis> - <link linkend='ref-images'>Images</link>:</emphasis> - Describes the standard images that the Yocto Project supports. - </para></listitem> - <listitem><para><emphasis> - <link linkend='ref-features'>Features</link>:</emphasis> - Describes mechanisms for creating distribution, machine, and image - features during the build process using the OpenEmbedded build system.</para></listitem> - <listitem><para><emphasis> - <link linkend='ref-variables-glos'>Variables Glossary</link>:</emphasis> - Presents most variables used by the OpenEmbedded build system, which - uses BitBake. - Entries describe the function of the variable and how to apply them. - </para></listitem> - <listitem><para><emphasis> - <link linkend='ref-varlocality'>Variable Context</link>:</emphasis> - Provides variable locality or context.</para></listitem> - <listitem><para><emphasis> - <link linkend='faq'>FAQ</link>:</emphasis> - Provides answers for commonly asked questions in the Yocto Project - development environment.</para></listitem> - <listitem><para><emphasis> - <link linkend='resources'>Contributing to the Yocto Project</link>:</emphasis> - Provides guidance on how you can contribute back to the Yocto - Project.</para></listitem> - </itemizedlist> + If you want to use the Yocto Project to test run building an image + without having to understand concepts, work through the + <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>. + You can find "how-to" information in the + <ulink url='&YOCTO_DOCS_DEV_URL;'>Yocto Project Development Tasks Manual</ulink>. + <note><title>Tip</title> + For more information about the Yocto Project Documentation set, + see the + "<link linkend='resources-links-and-related-documentation'>Links and Related Documentation</link>" + section. + </note> </para> </section> +<section id='yp-intro'> + <title>Introducing the Yocto Project Development Environment</title> + + <para> + The Yocto Project is an open-source collaboration project whose + focus is for developers of embedded Linux systems. + Among other things, the Yocto Project uses an + <link linkend='build-system-term'>OpenEmbedded build system</link>. + The build system, which is based on the OpenEmbedded (OE) project and + uses the + <link linkend='bitbake-term'>BitBake</link> tool, constructs complete + Linux images for architectures based on ARM, MIPS, PowerPC, x86 and + x86-64. + <note> + Historically, the OpenEmbedded build system, which is the + combination of BitBake and OE components, formed a reference + build host that was known as + "<link linkend='poky'>Poky</link>" (<emphasis>Pah</emphasis>-kee). + The term "Poky", as used throughout the Yocto Project Documentation + set, can have different meanings. + </note> + The Yocto Project provides various ancillary tools for the embedded + developer and also features the Sato reference User Interface, which + is optimized for stylus-driven, low-resolution screens. + </para> + + <mediaobject> + <imageobject> + <imagedata fileref="figures/YP-flow-diagram.png" + format="PNG" align='center' width="8in"/> + </imageobject> + </mediaobject> + + <para> + Here are some highlights for the Yocto Project: + </para> + + <itemizedlist> + <listitem><para> + Provides a recent Linux kernel along with a set of system + commands and libraries suitable for the embedded + environment. + </para></listitem> + <listitem><para> + Makes available system components such as X11, GTK+, Qt, + Clutter, and SDL (among others) so you can create a rich user + experience on devices that have display hardware. + For devices that do not have a display or where you wish to + use alternative UI frameworks, these components need not be + installed. + </para></listitem> + <listitem><para> + Creates a focused and stable core compatible with the + OpenEmbedded project with which you can easily and reliably + build and develop. + </para></listitem> + <listitem><para> + Fully supports a wide range of hardware and device emulation + through the Quick EMUlator (QEMU). + </para></listitem> + <listitem><para> + Provides a layer mechanism that allows you to easily extend + the system, make customizations, and keep them organized. + </para></listitem> + </itemizedlist> + + <para> + You can use the Yocto Project to generate images for many kinds + of devices. + As mentioned earlier, the Yocto Project supports creation of + reference images that you can boot within and emulate using QEMU. + The standard example machines target QEMU full-system + emulation for 32-bit and 64-bit variants of x86, ARM, MIPS, and + PowerPC architectures. + Beyond emulation, you can use the layer mechanism to extend + support to just about any platform that Linux can run on and that + a toolchain can target. + </para> + + <para> + Another Yocto Project feature is the Sato reference User + Interface. + This optional UI that is based on GTK+ is intended for devices with + restricted screen sizes and is included as part of the + OpenEmbedded Core layer so that developers can test parts of the + software stack. + </para> + + <para> + While the Yocto Project does not provide a strict testing framework, + it does provide or generate for you artifacts that let you perform + target-level and emulated testing and debugging. + Additionally, if you are an + <trademark class='trade'>Eclipse</trademark> IDE user, you can + install an Eclipse Yocto Plug-in to allow you to develop within that + familiar environment. + </para> + + <para> + By default, using the Yocto Project to build an image creates a Poky + distribution. + However, you can create your own distribution by providing key + <link link='metadata'>Metadata</link>. + A good example is Angstrom, which has had a distribution + based on the Yocto Project since its inception. + Other examples include commercial distributions like + <ulink url='https://www.yoctoproject.org/organization/wind-river-systems'>Wind River Linux</ulink>, + <ulink url='https://www.yoctoproject.org/organization/mentor-graphics'>Mentor Embedded Linux</ulink>, + <ulink url='https://www.yoctoproject.org/organization/enea-ab'>ENEA Linux</ulink> + and <ulink url='https://www.yoctoproject.org/ecosystem/member-organizations'>others</ulink>. + See the "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-your-own-distribution'>Creating Your Own Distribution</ulink>" + section in the Yocto Project Development Tasks Manual for more + information. + </para> +</section> <section id='intro-requirements'> <title>System Requirements</title> @@ -163,12 +204,12 @@ <listitem><para>Ubuntu 10.04</para></listitem> <listitem><para>Ubuntu 11.10</para></listitem> <listitem><para>Ubuntu 12.04 (LTS)</para></listitem> - <listitem><para>Ubuntu 13.10</para></listitem> --> - <listitem><para>Ubuntu 14.04 (LTS)</para></listitem> + <listitem><para>Ubuntu 13.10</para></listitem> + <listitem><para>Ubuntu 14.04 (LTS)</para></listitem> --> <listitem><para>Ubuntu 14.10</para></listitem> <listitem><para>Ubuntu 15.04</para></listitem> <listitem><para>Ubuntu 15.10</para></listitem> - <listitem><para>Ubuntu 16.04</para></listitem> + <listitem><para>Ubuntu 16.04 (LTS)</para></listitem> <!-- <listitem><para>Fedora 16 (Verne)</para></listitem> <listitem><para>Fedora 17 (Spherical)</para></listitem> <listitem><para>Fedora release 19 (Schrödinger's Cat)</para></listitem> @@ -185,6 +226,7 @@ <!-- <listitem><para>Debian GNU/Linux 6.0 (Squeeze)</para></listitem> <listitem><para>Debian GNU/Linux 7.x (Wheezy)</para></listitem> --> <listitem><para>Debian GNU/Linux 8.x (Jessie)</para></listitem> + <listitem><para>Debian GNU/Linux 9.x (Stretch)</para></listitem> <!-- <listitem><para>Debian GNU/Linux 7.1 (Wheezy)</para></listitem> <listitem><para>Debian GNU/Linux 7.2 (Wheezy)</para></listitem> <listitem><para>Debian GNU/Linux 7.3 (Wheezy)</para></listitem> @@ -413,7 +455,7 @@ Python: <itemizedlist> <listitem><para>Git 1.8.3.1 or greater</para></listitem> - <listitem><para>tar 1.24 or greater</para></listitem> + <listitem><para>tar 1.27 or greater</para></listitem> <listitem><para>Python 3.4.0 or greater</para></listitem> </itemizedlist> </para> @@ -492,9 +534,7 @@ On the machine that is able to run BitBake, be sure you have set up your build environment with the setup script - (<link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link> - or - <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>). + (<link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>). </para></listitem> <listitem><para> Run the BitBake command to build the tarball: @@ -512,7 +552,7 @@ <filename>.sh</filename> file that installs the tools in the <filename>tmp/deploy/sdk</filename> subdirectory of the - <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. + <link linkend='build-directory'>Build Directory</link>. The installer file has the string "buildtools" in the name. </para></listitem> @@ -600,12 +640,441 @@ <title>Development Checkouts</title> <para> Development using the Yocto Project requires a local - <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. + <link linkend='source-directory'>Source Directory</link>. You can set up the Source Directory by cloning a copy of the upstream - <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>poky</ulink> Git repository. + <link linkend='poky'>poky</link> Git repository. For information on how to do this, see the - "<ulink url='&YOCTO_DOCS_DEV_URL;#getting-setup'>Getting Set Up</ulink>" - section in the Yocto Project Development Manual. + "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-yocto-project-source-files'>Working With Yocto Project Source Files</ulink>" + section in the Yocto Project Development Tasks Manual. + </para> +</section> + +<section id='yocto-project-terms'> + <title>Yocto Project Terms</title> + + <para> + 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: + <itemizedlist> + <listitem><para> + <emphasis>Append Files:</emphasis> + Files that append build information to a recipe file. + Append files are known as BitBake append files and + <filename>.bbappend</filename> files. + The OpenEmbedded build system expects every append file to have + a corresponding recipe (<filename>.bb</filename>) 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. + <filename>formfactor_0.0.bb</filename> and + <filename>formfactor_0.0.bbappend</filename>).</para> + + <para>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 + "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>" + section in the Yocto Project Development Tasks Manual. + <note> + 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. + </note> + </para></listitem> + <listitem><para id='bitbake-term'> + <emphasis>BitBake:</emphasis> + The task executor and scheduler used by the OpenEmbedded build + system to build images. + For more information on BitBake, see the + <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>. + </para></listitem> + <listitem><para id='board-support-package-bsp-term'> + <emphasis>Board Support Package (BSP):</emphasis> + A group of drivers, definitions, and other components that + provide support for a specific hardware configuration. + For more information on BSPs, see the + <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>. + </para></listitem> + <listitem> + <para id='build-directory'> + <emphasis>Build Directory:</emphasis> + This term refers to the area used by the OpenEmbedded build + system for builds. + The area is created when you <filename>source</filename> the + setup environment script that is found in the Source Directory + (i.e. <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>). + The + <link linkend='var-TOPDIR'><filename>TOPDIR</filename></link> + variable points to the Build Directory.</para> + + <para>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 + <link linkend='source-directory'>Source Directory</link> is + named <filename>poky</filename>: + <itemizedlist> + <listitem><para>Create the Build Directory inside your + Source Directory and let the name of the Build + Directory default to <filename>build</filename>: + <literallayout class='monospaced'> + $ cd $HOME/poky + $ source &OE_INIT_FILE; + </literallayout> + </para></listitem> + <listitem><para>Create the Build Directory inside your + home directory and specifically name it + <filename>test-builds</filename>: + <literallayout class='monospaced'> + $ cd $HOME + $ source poky/&OE_INIT_FILE; test-builds + </literallayout> + </para></listitem> + <listitem><para> + 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 + <filename>YP-&POKYVERSION;</filename> + in your home directory within the existing + directory <filename>mybuilds</filename>: + <literallayout class='monospaced'> + $cd $HOME + $ source $HOME/poky/&OE_INIT_FILE; $HOME/mybuilds/YP-&POKYVERSION; + </literallayout> + </para></listitem> + </itemizedlist> + <note> + By default, the Build Directory contains + <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>, + which is a temporary directory the build system uses for + its work. + <filename>TMPDIR</filename> 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 <filename>TMPDIR</filename> + in your <filename>local.conf</filename> file + to use a local drive. + Doing so effectively separates <filename>TMPDIR</filename> + from <filename>TOPDIR</filename>, which is the Build + Directory. + </note> + </para></listitem> + <listitem><para id='hardware-build-system-term'> + <emphasis>Build System:</emphasis> + The system used to build images in a Yocto Project + Development environment. + The build system is sometimes referred to as the + development host. + </para></listitem> + <listitem><para> + <emphasis>Classes:</emphasis> + 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 + "<link linkend='ref-classes'>Classes</link>" chapter. + Class files end with the <filename>.bbclass</filename> + filename extension. + </para></listitem> + <listitem><para> + <emphasis>Configuration File:</emphasis> + Configuration information in various <filename>.conf</filename> + files provides global definitions of variables. + The <filename>conf/local.conf</filename> configuration file in + the + <link linkend='build-directory'>Build Directory</link> + contains user-defined variables that affect every build. + The <filename>meta-poky/conf/distro/poky.conf</filename> + configuration file defines Yocto "distro" configuration + variables used only when building with this policy. + Machine configuration files, which + are located throughout the + <link linkend='source-directory'>Source Directory</link>, define + variables for specific hardware and are only used when building + for that target (e.g. the + <filename>machine/beaglebone.conf</filename> configuration + file defines variables for the Texas Instruments ARM Cortex-A8 + development board). + Configuration files end with a <filename>.conf</filename> + filename extension. + </para></listitem> + <listitem><para id='cross-development-toolchain'> + <emphasis>Cross-Development Toolchain:</emphasis> + 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.</para> + + <para>The Yocto Project supports two different cross-development + toolchains: + <itemizedlist> + <listitem><para> + A toolchain only used by and within + BitBake when building an image for a target + architecture. + </para></listitem> + <listitem><para>A relocatable toolchain used outside of + BitBake by developers when developing applications + that will run on a targeted device. + </para></listitem> + </itemizedlist></para> + + <para>Creation of these toolchains is simple and automated. + For information on toolchain concepts as they apply to the + Yocto Project, see the + "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>" + section. + You can also find more information on using the + relocatable toolchain in the + <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink> + manual. + </para></listitem> + <listitem><para> + <emphasis>Image:</emphasis> + 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 + "<link linkend='ref-images'>Images</link>" + chapter. + </para></listitem> + <listitem><para> + <emphasis>Layer:</emphasis> + A collection of recipes representing the core, + a BSP, or an application stack. + For a discussion specifically on BSP Layers, see the + "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>" + section in the Yocto Project Board Support Packages (BSP) + Developer's Guide. + </para></listitem> + <listitem><para id='metadata'> + <emphasis>Metadata:</emphasis> + 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 + <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/yocto-kernel-cache'><filename>yocto-kernel-cache</filename></ulink> + Git repository. + </para></listitem> + <listitem><para id='oe-core'> + <emphasis>OE-Core:</emphasis> + A core set of Metadata originating with OpenEmbedded (OE) + that is shared between OE and the Yocto Project. + This Metadata is found in the <filename>meta</filename> + directory of the + <link linkend='source-directory'>Source Directory</link>. + </para></listitem> + <listitem><para id='build-system-term'> + <emphasis>OpenEmbedded Build System:</emphasis> + The build system specific to the Yocto Project. + The OpenEmbedded build system is based on another project known + as "Poky", which uses + <link linkend='bitbake-term'>BitBake</link> 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. + <note> + For some historical information about Poky, see the + <link linkend='poky'>Poky</link> term. + </note> + </para></listitem> + <listitem><para> + <emphasis>Package:</emphasis> + 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.</para> + + <para>It is worth noting that the term "package" can, + in general, have subtle meanings. + For example, the packages referred to in the + "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Build Host Packages</ulink>" + section in the Yocto Project Quick Start are compiled binaries + that, when installed, add functionality to your Linux + distribution.</para> + + <para>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. <link linkend='var-PR'><filename>PR</filename></link>, + <link linkend='var-PV'><filename>PV</filename></link>, and + <link linkend='var-PE'><filename>PE</filename></link>). + </para></listitem> + <listitem><para> + <emphasis>Package Groups:</emphasis> + 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 + <filename>.bb</filename> filename extension. + </para></listitem> + <listitem><para id='poky'> + <emphasis>Poky:</emphasis> + The term "poky", which is pronounced + <emphasis>Pah</emphasis>-kee, can mean several things: + <itemizedlist> + <listitem><para> + 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. + </para></listitem> + <listitem><para> + Within the Yocto Project + <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>, + "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. + </para></listitem> + <listitem><para> + Finally, "poky" can refer to the default + <link linkend='var-DISTRO'><filename>DISTRO</filename></link> + (i.e. distribution) created when you use the Yocto + Project in conjunction with the + <filename>poky</filename> repository to build an image. + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para> + <emphasis>Recipe:</emphasis> + 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 + <filename>.bb</filename> file extension. + </para></listitem> + <listitem><para id='reference-kit-term'> + <emphasis>Reference Kit:</emphasis> + A working example of a system, which includes a + <link linkend='board-support-package-bsp-term'>BSP</link> + as well as a + <link linkend='hardware-build-system-term'>build system</link> + and other components, that can work on specific hardware. + </para></listitem> + <listitem> + <para id='source-directory'> + <emphasis>Source Directory:</emphasis> + This term refers to the directory structure created as a result + of creating a local copy of the <filename>poky</filename> Git + repository <filename>git://git.yoctoproject.org/poky</filename> + or expanding a released <filename>poky</filename> tarball. + <note> + Creating a local copy of the <filename>poky</filename> + Git repository is the recommended method for setting up + your Source Directory. + </note> + Sometimes you might hear the term "poky directory" used to refer + to this directory structure. + <note> + 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. + </note></para> + + <para>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.</para> + + <para>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 <filename>poky</filename> Git + repository results in a local Git repository whose top-level + folder is also named "poky".</para> + + <para>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 + <filename>&YOCTO_POKY_TARBALL;</filename> results in a + Source Directory whose root folder is named + <filename>&YOCTO_POKY;</filename>.</para> + + <para>It is important to understand the differences between the + Source Directory created by unpacking a released tarball as + compared to cloning + <filename>git://git.yoctoproject.org/poky</filename>. + 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 <filename>poky</filename> + 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 <filename>poky</filename> Git + repository.</para> + + <para>For more information on concepts related to Git + repositories, branches, and tags, see the + "<link linkend='repositories-tags-and-branches'>Repositories, Tags, and Branches</link>" + section. + </para></listitem> + <listitem><para><emphasis>Task:</emphasis> + A unit of execution for BitBake (e.g. + <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>, + <link linkend='ref-tasks-fetch'><filename>do_fetch</filename></link>, + <link linkend='ref-tasks-patch'><filename>do_patch</filename></link>, + and so forth). + </para></listitem> + <listitem><para id='toaster-term'><emphasis>Toaster:</emphasis> + A web interface to the Yocto Project's + <link linkend='build-system-term'>OpenEmbedded Build System</link>. + 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 + <ulink url='&YOCTO_DOCS_TOAST_URL;'>Yocto Project Toaster Manual</ulink>. + </para></listitem> + <listitem><para> + <emphasis>Upstream:</emphasis> + 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. + </para></listitem> + </itemizedlist> </para> </section> |