diff options
Diffstat (limited to 'poky/documentation/overview-manual/overview-manual-yp-intro.xml')
| -rw-r--r-- | poky/documentation/overview-manual/overview-manual-yp-intro.xml | 1357 |
1 files changed, 1357 insertions, 0 deletions
diff --git a/poky/documentation/overview-manual/overview-manual-yp-intro.xml b/poky/documentation/overview-manual/overview-manual-yp-intro.xml new file mode 100644 index 000000000..ccf5e274a --- /dev/null +++ b/poky/documentation/overview-manual/overview-manual-yp-intro.xml @@ -0,0 +1,1357 @@ +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" +[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > + +<chapter id='overview-yp'> + <title>Introducing the Yocto Project</title> + + <section id='what-is-the-yocto-project'> + <title>What is the Yocto Project?</title> + + <para> + The Yocto Project is an open source collaboration project + that helps developers create custom Linux-based systems that are + designed for embedded products regardless of the product's hardware + architecture. + Yocto Project provides a flexible toolset and a development + environment that allows embedded device developers across the + world to collaborate through shared technologies, software stacks, + configurations, and best practices used to create these tailored + Linux images. + </para> + + <para> + Thousands of developers worldwide have discovered that Yocto + Project provides advantages in both systems and applications + development, archival and management benefits, and customizations + used for speed, footprint, and memory utilization. + The project is a standard when it comes to delivering embedded + software stacks. + The project allows software customizations and build interchange + for multiple hardware platforms as well as software stacks that + can be maintained and scaled. + </para> + + <para id='yp-key-dev-elements'> + <imagedata fileref="figures/key-dev-elements.png" format="PNG" align='center' width="8in"/> + </para> + + <para> + For further introductory information on the Yocto Project, you + might be interested in this + <ulink url='https://www.embedded.com/electronics-blogs/say-what-/4458600/Why-the-Yocto-Project-for-my-IoT-Project-'>article</ulink> + by Drew Moseley and in this short introductory + <ulink url='https://www.youtube.com/watch?v=utZpKM7i5Z4'>video</ulink>. + </para> + + <para> + The remainder of this section overviews advantages and challenges + tied to the Yocto Project. + </para> + + <section id='gs-features'> + <title>Features</title> + + <para> + The following list describes features and advantages of the + Yocto Project: + <itemizedlist> + <listitem><para> + <emphasis>Widely Adopted Across the Industry:</emphasis> + Semiconductor, operating system, software, and + service vendors exist whose products and services + adopt and support the Yocto Project. + For a look at the Yocto Project community and + the companies involved with the Yocto + Project, see the "COMMUNITY" and "ECOSYSTEM" tabs + on the + <ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink> + home page. + </para></listitem> + <listitem><para> + <emphasis>Architecture Agnostic:</emphasis> + Yocto Project supports Intel, ARM, MIPS, AMD, PPC + and other architectures. + Most ODMs, OSVs, and chip vendors create and supply + BSPs that support their hardware. + If you have custom silicon, you can create a BSP + that supports that architecture.</para> + + <para>Aside from lots of architecture support, the + Yocto Project fully supports a wide range of device + emulation through the Quick EMUlator (QEMU). + </para></listitem> + <listitem><para> + <emphasis>Images and Code Transfer Easily:</emphasis> + Yocto Project output can easily move between + architectures without moving to new development + environments. + Additionally, if you have used the Yocto Project to + create an image or application and you find yourself + not able to support it, commercial Linux vendors such + as Wind River, Mentor Graphics, Timesys, and ENEA could + take it and provide ongoing support. + These vendors have offerings that are built using + the Yocto Project. + </para></listitem> + <listitem><para> + <emphasis>Flexibility:</emphasis> + Corporations use the Yocto Project many different ways. + One example is to create an internal Linux distribution + as a code base the corporation can use across multiple + product groups. + Through customization and layering, a project group + can leverage the base Linux distribution to create + a distribution that works for their product needs. + </para></listitem> + <listitem><para> + <emphasis>Ideal for Constrained Embedded and IoT devices:</emphasis> + Unlike a full Linux distribution, you can use the + Yocto Project to create exactly what you need for + embedded devices. + You only add the feature support or packages that you + absolutely need for the device. + For devices that have display hardware, you can use + available system components such as X11, GTK+, Qt, + Clutter, and SDL (among others) to create a rich user + experience. + For devices that do not have a display or where you + want to use alternative UI frameworks, you can choose + to not install these components. + </para></listitem> + <listitem><para> + <emphasis>Comprehensive Toolchain Capabilities:</emphasis> + Toolchains for supported architectures satisfy most + use cases. + However, if your hardware supports features that are + not part of a standard toolchain, you can easily + customize that toolchain through specification of + platform-specific tuning parameters. + And, should you need to use a third-party toolchain, + mechanisms built into the Yocto Project allow for that. + </para></listitem> + <listitem><para> + <emphasis>Mechanism Rules Over Policy:</emphasis> + Focusing on mechanism rather than policy ensures that + you are free to set policies based on the needs of your + design instead of adopting decisions enforced by some + system software provider. + </para></listitem> + <listitem><para> + <emphasis>Uses a Layer Model:</emphasis> + The Yocto Project + <link linkend='the-yocto-project-layer-model'>layer infrastructure</link> + groups related functionality into separate bundles. + You can incrementally add these grouped functionalities + to your project as needed. + Using layers to isolate and group functionality + reduces project complexity and redundancy, allows you + to easily extend the system, make customizations, + and keep functionality organized. + </para></listitem> + <listitem><para> + <emphasis>Supports Partial Builds:</emphasis> + You can build and rebuild individual packages as + needed. + Yocto Project accomplishes this through its + <link linkend='shared-state-cache'>shared-state cache</link> + (sstate) scheme. + Being able to build and debug components individually + eases project development. + </para></listitem> + <listitem><para> + <emphasis>Releases According to a Strict Schedule:</emphasis> + Major releases occur on a + <ulink url='&YOCTO_DOCS_REF_URL;#ref-release-process'>six-month cycle</ulink> + predictably in October and April. + The most recent two releases support point releases + to address common vulnerabilities and exposures. + This predictability is crucial for projects based on + the Yocto Project and allows development teams to + plan activities. + </para></listitem> + <listitem><para> + <emphasis>Rich Ecosystem of Individuals and Organizations:</emphasis> + For open source projects, the value of community is + very important. + Support forums, expertise, and active developers who + continue to push the Yocto Project forward are readily + available. + </para></listitem> + <listitem><para> + <emphasis>Binary Reproducibility:</emphasis> + The Yocto Project allows you to be very specific about + dependencies and achieves very high percentages of + binary reproducibility (e.g. 99.8% for + <filename>core-image-minimal</filename>). + When distributions are not specific about which + packages are pulled in and in what order to support + dependencies, other build systems can arbitrarily + include packages. + </para></listitem> + <listitem><para> + <emphasis>License Manifest:</emphasis> + The Yocto Project provides a + <ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>license manifest</ulink> + for review by people who need to track the use of open + source licenses (e.g.legal teams). + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='gs-challenges'> + <title>Challenges</title> + + <para> + The following list presents challenges you might encounter + when developing using the Yocto Project: + <itemizedlist> + <listitem><para> + <emphasis>Steep Learning Curve:</emphasis> + The Yocto Project has a steep learning curve and has + many different ways to accomplish similar tasks. + It can be difficult to choose how to proceed when + varying methods exist by which to accomplish a given + task. + </para></listitem> + <listitem><para> + <emphasis>Understanding What Changes You Need to Make + For Your Design Requires Some Research:</emphasis> + Beyond the simple tutorial stage, understanding what + changes need to be made for your particular design + can require a significant amount of research and + investigation. + For information that helps you transition from + trying out the Yocto Project to using it for your + project, see the + "<ulink url='&YOCTO_HOME_URL;/docs/what-i-wish-id-known/'>What I wish I'd Known</ulink>" + and + "<ulink url='&YOCTO_HOME_URL;/docs/transitioning-to-a-custom-environment/'>Transitioning to a Custom Environment for Systems Development</ulink>" + documents on the Yocto Project website. + </para></listitem> + <listitem><para> + <emphasis>Project Workflow Could Be Confusing:</emphasis> + The + <link linkend='overview-development-environment'>Yocto Project workflow</link> + could be confusing if you are used to traditional + desktop and server software development. + In a desktop development environment, mechanisms exist + to easily pull and install new packages, which are + typically pre-compiled binaries from servers accessible + over the Internet. + Using the Yocto Project, you must modify your + configuration and rebuild to add additional packages. + </para></listitem> + <listitem><para> + <emphasis>Working in a Cross-Build Environment Can + Feel Unfamiliar:</emphasis> + When developing code to run on a target, compilation, + execution, and testing done on the actual target + can be faster than running a BitBake build on a + development host and then deploying binaries to the + target for test. + While the Yocto Project does support development tools + on the target, the additional step of integrating your + changes back into the Yocto Project build environment + would be required. + Yocto Project supports an intermediate approach that + involves making changes on the development system + within the BitBake environment and then deploying only + the updated packages to the target.</para> + + <para>The Yocto Project + <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink> + produces packages in standard formats (i.e. RPM, + DEB, IPK, and TAR). + You can deploy these packages into the running system + on the target by using utilities on the target such + as <filename>rpm</filename> or + <filename>ipk</filename>. + </para></listitem> + <listitem><para> + <emphasis>Initial Build Times Can be Significant:</emphasis> + Long initial build times are unfortunately unavoidable + due to the large number of packages initially built + from scratch for a fully functioning Linux system. + Once that initial build is completed, however, the + shared-state (sstate) cache mechanism Yocto Project + uses keeps the system from rebuilding packages that + have not been "touched" since the last build. + The sstate mechanism significantly reduces times + for successive builds. + </para></listitem> + </itemizedlist> + </para> + </section> + </section> + + <section id='the-yocto-project-layer-model'> + <title>The Yocto Project Layer Model</title> + + <para> + The Yocto Project's "Layer Model" is a development model for + embedded and IoT Linux creation that distinguishes the + Yocto Project from other simple build systems. + The Layer Model simultaneously supports collaboration and + customization. + Layers are repositories that contain related sets of instructions + that tell the + <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink> + what to do. + You can collaborate, share, and reuse layers. + </para> + + <para> + Layers can contain changes to previous instructions or settings + at any time. + This powerful override capability is what allows you to customize + previously supplied collaborative or community layers to suit your + product requirements. + </para> + + <para> + You use different layers to logically separate information in your + build. + As an example, you could have BSP, GUI, distro configuration, + middleware, or application layers. + Putting your entire build into one layer limits and complicates + future customization and reuse. + Isolating information into layers, on the other hand, helps + simplify future customizations and reuse. + You might find it tempting to keep everything in one layer when + working on a single project. + However, the more modular your Metadata, the easier + it is to cope with future changes. + <note><title>Notes</title> + <itemizedlist> + <listitem><para> + Use Board Support Package (BSP) layers from silicon + vendors when possible. + </para></listitem> + <listitem><para> + Familiarize yourself with the + <ulink url='https://caffelli-staging.yoctoproject.org/software-overview/layers/'>Yocto Project curated layer index</ulink> + or the + <ulink url='http://layers.openembedded.org/layerindex/branch/master/layers/'>OpenEmbedded layer index</ulink>. + The latter contains more layers but they are less + universally validated. + </para></listitem> + <listitem><para> + Layers support the inclusion of technologies, hardware + components, and software components. + The + <ulink url='&YOCTO_DOCS_DEV_URL;#making-sure-your-layer-is-compatible-with-yocto-project'>Yocto Project Compatible</ulink> + designation provides a minimum level of standardization + that contributes to a strong ecosystem. + "YP Compatible" is applied to appropriate products and + software components such as BSPs, other OE-compatible + layers, and related open-source projects, allowing the + producer to use Yocto Project badges and branding + assets. + </para></listitem> + </itemizedlist> + </note> + </para> + + <para> + To illustrate how layers are used to keep things modular, consider + machine customizations. + These types of customizations typically reside in a special layer, + rather than a general layer, called a BSP Layer. + Furthermore, the machine customizations should be isolated from + recipes and Metadata that support a new GUI environment, + for example. + This situation gives you a couple of layers: one for the machine + configurations, and one for the GUI environment. + It is important to understand, however, that the BSP layer can + still make machine-specific additions to recipes within the GUI + environment layer without polluting the GUI layer itself + with those machine-specific changes. + You can accomplish this through a recipe that is a BitBake append + (<filename>.bbappend</filename>) file, which is described later + in this section. + <note> + For general information on BSP layer structure, see the + <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Packages (BSP) Developer's Guide</ulink>. + </note> + </para> + + <para> + The + <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> + contains both general layers and BSP layers right out of the box. + You can easily identify layers that ship with a Yocto Project + release in the Source Directory by their names. + Layers typically have names that begin with the string + <filename>meta-</filename>. + <note> + It is not a requirement that a layer name begin with the + prefix <filename>meta-</filename>, but it is a commonly + accepted standard in the Yocto Project community. + </note> + For example, if you were to examine the + <ulink url='https://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/'>tree view</ulink> + of the <filename>poky</filename> repository, you will see several + layers: <filename>meta</filename>, + <filename>meta-skeleton</filename>, + <filename>meta-selftest</filename>, + <filename>meta-poky</filename>, and + <filename>meta-yocto-bsp</filename>. + Each of these repositories represents a distinct layer. + </para> + + <para> + For procedures on how to create layers, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" + section in the Yocto Project Development Tasks Manual. + </para> + </section> + + <section id='components-and-tools'> + <title>Components and Tools</title> + + <para> + The Yocto Project employs a collection of components and + tools used by the project itself, by project developers, + and by those using the Yocto Project. + These components and tools are open source projects and + metadata that are separate from the reference distribution + (<ulink url='&YOCTO_DOCS_REF_URL;#poky'>Poky</ulink>) + and the + <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>. + Most of the components and tools are downloaded separately. + </para> + + <para> + This section provides brief overviews of the components and + tools associated with the Yocto Project. + </para> + + <section id='gs-development-tools'> + <title>Development Tools</title> + + <para> + The following list consists of tools that help you develop + images and applications using the Yocto Project: + <itemizedlist> + <listitem><para id='gs-crops-overview'> + <emphasis>CROPS:</emphasis> + <ulink url='https://git.yoctoproject.org/cgit/cgit.cgi/crops/about/'>CROPS</ulink> + is an open source, cross-platform development framework + that leverages + <ulink url='https://www.docker.com/'>Docker Containers</ulink>. + CROPS provides an easily managed, extensible environment + that allows you to build binaries for a variety of + architectures on Windows, Linux and Mac OS X hosts. + </para></listitem> + <listitem><para> + <emphasis><filename>devtool</filename>:</emphasis> + This command-line tool is available as part of the + extensible SDK (eSDK) and is its cornerstone. + You can use <filename>devtool</filename> to help build, + test, and package software within the eSDK. + You can use the tool to optionally integrate what you + build into an image built by the OpenEmbedded build + system.</para> + + <para>The <filename>devtool</filename> command employs + a number of sub-commands that allow you to add, modify, + and upgrade recipes. + As with the OpenEmbedded build system, “recipes” + represent software packages within + <filename>devtool</filename>. + When you use <filename>devtool add</filename>, a recipe + is automatically created. + When you use <filename>devtool modify</filename>, the + specified existing recipe is used in order to determine + where to get the source code and how to patch it. + In both cases, an environment is set up so that when + you build the recipe a source tree that is under your + control is used in order to allow you to make changes + to the source as desired. + By default, both new recipes and the source go into + a “workspace” directory under the eSDK. + The <filename>devtool upgrade</filename> command + updates an existing recipe so that you can build it + for an updated set of source files.</para> + + <para>You can read about the + <filename>devtool</filename> workflow in the Yocto + Project Application Development and Extensible + Software Development Kit (eSDK) Manual in the + "<ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'>Using <filename>devtool</filename> in Your SDK Workflow'</ulink>" + section. + </para></listitem> + <listitem><para> + <emphasis>Extensible Software Development Kit (eSDK):</emphasis> + The eSDK provides a cross-development toolchain and + libraries tailored to the contents of a specific image. + The eSDK makes it easy to add new applications and + libraries to an image, modify the source for an + existing component, test changes on the target + hardware, and integrate into the rest of the + OpenEmbedded build system. + The eSDK gives you a toolchain experience supplemented + with the powerful set of <filename>devtool</filename> + commands tailored for the Yocto Project environment. + </para> + + <para>For information on the eSDK, see 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><trademark class='trade'>Eclipse</trademark> IDE Plug-in:</emphasis> + This plug-in enables you to use the popular Eclipse + Integrated Development Environment (IDE), which allows + for development using the Yocto Project all within the + Eclipse IDE. + You can work within Eclipse to cross-compile, deploy, + and execute your output into a QEMU emulation session + as well as onto actual target hardware.</para> + + <para>The environment also supports performance + enhancing tools that allow you to perform remote + profiling, tracing, collection of power data, + collection of latency data, and collection of + performance data.</para> + + <para>Once you enable the plug-in, standard Eclipse + functions automatically use the cross-toolchain + and target system libraries. + You can build applications using any of these + libraries.</para> + + <para>For more information on the Eclipse plug-in, + see the + "<ulink url='&YOCTO_DOCS_SDK_URL;#adt-eclipse'>Working Within Eclipse</ulink>" + section in the Yocto Project Application Development + and the Extensible Software Development Kit (eSDK) + manual. + </para></listitem> + <listitem><para> + <emphasis>Toaster:</emphasis> + Toaster is a web interface to the Yocto Project + OpenEmbedded build system. + Toaster allows you to configure, run, and view + information about builds. + For information on Toaster, see the + <ulink url='&YOCTO_DOCS_TOAST_URL;'>Toaster User Manual</ulink>. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='gs-production-tools'> + <title>Production Tools</title> + + <para> + The following list consists of tools that help production + related activities using the Yocto Project: + <itemizedlist> + <listitem><para> + <emphasis>Auto Upgrade Helper:</emphasis> + This utility when used in conjunction with the + <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink> + (BitBake and OE-Core) automatically generates upgrades + for recipes that are based on new versions of the + recipes published upstream. + </para></listitem> + <listitem><para> + <emphasis>Recipe Reporting System:</emphasis> + The Recipe Reporting System tracks recipe versions + available for Yocto Project. + The main purpose of the system is to help you + manage the recipes you maintain and to offer a dynamic + overview of the project. + The Recipe Reporting System is built on top of the + <ulink url="http://layers.openembedded.org/layerindex/layers/">OpenEmbedded Layer Index</ulink>, + which is a website that indexes OpenEmbedded-Core + layers. + </para></listitem> + <listitem><para> + <emphasis>Patchwork:</emphasis> + <ulink url='http://jk.ozlabs.org/projects/patchwork/'>Patchwork</ulink> + is a fork of a project originally started by + <ulink url='http://ozlabs.org/'>OzLabs</ulink>. + The project is a web-based tracking system designed + to streamline the process of bringing contributions + into a project. + The Yocto Project uses Patchwork as an organizational + tool to handle patches, which number in the thousands + for every release. + </para></listitem> + <listitem><para> + <emphasis>AutoBuilder:</emphasis> + AutoBuilder is a project that automates build tests + and quality assurance (QA). + By using the public AutoBuilder, anyone can determine + the status of the current "master" branch of Poky. + <note> + AutoBuilder is based on + <ulink url='https://buildbot.net/'>buildbot</ulink>. + </note></para> + + <para>A goal of the Yocto Project is to lead the + open source industry with a project that automates + testing and QA procedures. + In doing so, the project encourages a development + community that publishes QA and test plans, publicly + demonstrates QA and test plans, and encourages + development of tools that automate and test and QA + procedures for the benefit of the development + community.</para> + + <para>You can learn more about the AutoBuilder used + by the Yocto Project + <ulink url='&YOCTO_AB_URL;'>here</ulink>. + </para></listitem> + <listitem><para> + <emphasis>Cross-Prelink:</emphasis> + Prelinking is the process of pre-computing the load + addresses and link tables generated by the dynamic + linker as compared to doing this at runtime. + Doing this ahead of time results in performance + improvements when the application is launched and + reduced memory usage for libraries shared by many + applications.</para> + + <para>Historically, cross-prelink is a variant of + prelink, which was conceived by + <ulink url='http://people.redhat.com/jakub/prelink.pdf'>Jakub Jelínek</ulink> + a number of years ago. + Both prelink and cross-prelink are maintained in the + same repository albeit on separate branches. + By providing an emulated runtime dynamic linker + (i.e. <filename>glibc</filename>-derived + <filename>ld.so</filename> emulation), the + cross-prelink project extends the prelink software’s + ability to prelink a sysroot environment. + Additionally, the cross-prelink software enables the + ability to work in sysroot style environments.</para> + + <para>The dynamic linker determines standard load + address calculations based on a variety of factors + such as mapping addresses, library usage, and library + function conflicts. + The prelink tool uses this information, from the + dynamic linker, to determine unique load addresses + for executable and linkable format (ELF) binaries + that are shared libraries and dynamically linked. + The prelink tool modifies these ELF binaries with the + pre-computed information. + The result is faster loading and often lower memory + consumption because more of the library code can + be re-used from shared Copy-On-Write (COW) pages. + </para> + + <para>The original upstream prelink project only + supports running prelink on the end target device + due to the reliance on the target device’s dynamic + linker. + This restriction causes issues when developing a + cross-compiled system. + The cross-prelink adds a synthesized dynamic loader + that runs on the host, thus permitting cross-prelinking + without ever having to run on a read-write target + filesystem. + </para></listitem> + <listitem><para> + <emphasis>Pseudo:</emphasis> + Pseudo is the Yocto Project implementation of + <ulink url='http://man.he.net/man1/fakeroot'>fakeroot</ulink>, + which is used to run commands in an environment + that seemingly has root privileges.</para> + + <para>During a build, it can be necessary to perform + operations that require system administrator + privileges. + For example, file ownership or permissions might need + definition. + Pseudo is a tool that you can either use directly or + through the environment variable + <filename>LD_PRELOAD</filename>. + Either method allows these operations to succeed as + if system administrator privileges exist even + when they do not.</para> + + <para>You can read more about Pseudo in the + "<link linkend='fakeroot-and-pseudo'>Fakeroot and Pseudo</link>" + section. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='gs-openembedded-build-system'> + <title>Open-Embedded Build System Components</title> + + <para> + The following list consists of components associated with the + <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>: + <itemizedlist> + <listitem><para> + <emphasis>BitBake:</emphasis> + BitBake is a core component of the Yocto Project and is + used by the OpenEmbedded build system to build images. + While BitBake is key to the build system, BitBake + is maintained separately from the Yocto Project.</para> + + <para>BitBake is a generic task execution engine that + allows shell and Python tasks to be run efficiently + and in parallel while working within complex inter-task + dependency constraints. + In short, BitBake is a build engine that works + through recipes written in a specific format in order + to perform sets of tasks.</para> + + <para>You can learn more about BitBake in the + <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>. + </para></listitem> + <listitem><para> + <emphasis>OpenEmbedded-Core:</emphasis> + OpenEmbedded-Core (OE-Core) is a common layer of + metadata (i.e. recipes, classes, and associated files) + used by OpenEmbedded-derived systems, which includes + the Yocto Project. + The Yocto Project and the OpenEmbedded Project both + maintain the OpenEmbedded-Core. + You can find the OE-Core metadata in the Yocto Project + <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta'>Source Repositories</ulink>. + </para> + + <para>Historically, the Yocto Project integrated the + OE-Core metadata throughout the Yocto Project + source repository reference system (Poky). + After Yocto Project Version 1.0, the Yocto Project + and OpenEmbedded agreed to work together and share a + common core set of metadata (OE-Core), which contained + much of the functionality previously found in Poky. + This collaboration achieved a long-standing + OpenEmbedded objective for having a more tightly + controlled and quality-assured core. + The results also fit well with the Yocto Project + objective of achieving a smaller number of fully + featured tools as compared to many different ones. + </para> + + <para>Sharing a core set of metadata results in Poky + as an integration layer on top of OE-Core. + You can see that in this + <link linkend='yp-key-dev-elements'>figure</link>. + The Yocto Project combines various components such as + BitBake, OE-Core, script “glue”, and documentation + for its build system. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='gs-reference-distribution-poky'> + <title>Reference Distribution (Poky)</title> + + <para> + Poky is the Yocto Project reference distribution. + It contains the + <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>Open-Embedded build system</ulink> + (BitBake and OE-Core) as well as a set of metadata to get you + started building your own distribution. + See the + <link linkend='what-is-the-yocto-project'>figure</link> in + "What is the Yocto Project?" section for an illustration + that shows Poky and its relationship with other parts of the + Yocto Project.</para> + + <para>To use the Yocto Project tools and components, you + can download (<filename>clone</filename>) Poky and use it + to bootstrap your own distribution. + <note> + Poky does not contain binary files. + It is a working example of how to build your own custom + Linux distribution from source. + </note> + You can read more about Poky in the + "<link linkend='reference-embedded-distribution'>Reference Embedded Distribution (Poky)</link>" + section. + </para> + </section> + + <section id='gs-packages-for-finished-targets'> + <title>Packages for Finished Targets</title> + + <para> + The following lists components associated with packages + for finished targets: + <itemizedlist> + <listitem><para> + <emphasis>Matchbox:</emphasis> + Matchbox is an Open Source, base environment for the + X Window System running on non-desktop, embedded + platforms such as handhelds, set-top boxes, kiosks, + and anything else for which screen space, input + mechanisms, or system resources are limited.</para> + + <para>Matchbox consists of a number of interchangeable + and optional applications that you can tailor to a + specific, non-desktop platform to enhance usability + in constrained environments.</para> + + <para>You can find the Matchbox source in the Yocto + Project + <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>. + </para></listitem> + <listitem><para> + <emphasis>Opkg</emphasis> + Open PacKaGe management (opkg) is a lightweight + package management system based on the itsy package + (ipkg) management system. + Opkg is written in C and resembles Advanced Package + Tool (APT) and Debian Package (dpkg) in operation. + </para> + + <para>Opkg is intended for use on embedded Linux + devices and is used in this capacity in the + <ulink url='http://www.openembedded.org/wiki/Main_Page'>OpenEmbedded</ulink> + and + <ulink url='https://openwrt.org/'>OpenWrt</ulink> + projects, as well as the Yocto Project. + <note> + As best it can, opkg maintains backwards + compatibility with ipkg and conforms to a subset + of Debian’s policy manual regarding control files. + </note> + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='gs-archived-components'> + <title>Archived Components</title> + + <para> + The Build Appliance is a virtual machine image that enables + you to build and boot a custom embedded Linux image with + the Yocto Project using a non-Linux development system. + </para> + + <para> + Historically, the Build Appliance was the second of three + methods by which you could use the Yocto Project on a system + that was not native to Linux. + <orderedlist> + <listitem><para> + <emphasis>Hob:</emphasis> + Hob, which is now deprecated and is no longer available + since the 2.1 release of the Yocto Project provided + a rudimentary, GUI-based interface to the Yocto + Project. + Toaster has fully replaced Hob. + </para></listitem> + <listitem><para> + <emphasis>Build Appliance:</emphasis> + Post Hob, the Build Appliance became available. + It was never recommended that you use the Build + Appliance as a day-to-day production development + environment with the Yocto Project. + Build Appliance was useful as a way to try out + development in the Yocto Project environment. + </para></listitem> + <listitem><para> + <emphasis>CROPS:</emphasis> + The final and best solution available now for + developing using the Yocto Project on a system + not native to Linux is with + <link linkend='gs-crops-overview'>CROPS</link>. + </para></listitem> + </orderedlist> + </para> + </section> + </section> + + <section id='gs-development-methods'> + <title>Development Methods</title> + + <para> + The Yocto Project development environment usually involves a + <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>Build Host</ulink> + and target hardware. + You use the Build Host to build images and develop applications, + while you use the target hardware to test deployed software. + </para> + + <para> + This section provides an introduction to the choices or + development methods you have when setting up your Build Host. + Depending on the your particular workflow preference and the + type of operating system your Build Host runs, several choices + exist that allow you to use the Yocto Project. + <note> + For additional detail about the Yocto Project development + environment, see the + "<link linkend='overview-development-environment'>The Yocto Project Development Environment</link>" + chapter. + </note> + <itemizedlist> + <listitem><para> + <emphasis>Native Linux Host:</emphasis> + By far the best option for a Build Host. + A system running Linux as its native operating system + allows you to develop software by directly using the + <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink> + tool. + You can accomplish all aspects of development from a + familiar shell of a supported Linux distribution.</para> + + <para>For information on how to set up a Build Host on + a system running Linux as its native operating system, + see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-a-native-linux-host'>Setting Up a Native Linux Host</ulink>" + section in the Yocto Project Development Tasks Manual. + </para></listitem> + <listitem><para> + <emphasis>CROss PlatformS (CROPS):</emphasis> + Typically, you use + <ulink url='https://git.yoctoproject.org/cgit/cgit.cgi/crops/about/'>CROPS</ulink>, + which leverages + <ulink url='https://www.docker.com/'>Docker Containers</ulink>, + to set up a Build Host that is not running Linux (e.g. + <trademark class='registered'>Microsoft</trademark> + <trademark class='trademark'>Windows</trademark> + or + <trademark class='registered'>macOS</trademark>). + <note> + You can, however, use CROPS on a Linux-based system. + </note> + CROPS is an open source, cross-platform development + framework that provides an easily managed, extensible + environment for building binaries targeted for a variety + of architectures on Windows, macOS, or Linux hosts. + Once the Build Host is set up using CROPS, you can prepare + a shell environment to mimic that of a shell being used + on a system natively running Linux.</para> + + <para>For information on how to set up a Build Host with + CROPS, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-to-use-crops'>Setting Up to Use CROss PlatformS (CROPS)</ulink>" + section in the Yocto Project Development Tasks Manual. + </para></listitem> + <listitem><para> + <emphasis>Toaster:</emphasis> + Regardless of what your Build Host is running, you can + use Toaster to develop software using the Yocto Project. + Toaster is a web interface to the Yocto Project's + <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>Open-Embedded build system</ulink>. + The interface enables you to configure and run your + builds. + Information about builds is collected and stored in a + database. + You can use Toaster to configure and start builds on + multiple remote build servers.</para> + + <para>For information about and how to use Toaster, + see the + <ulink url='&YOCTO_DOCS_TOAST_URL;'>Toaster User Manual</ulink>. + </para></listitem> + <listitem><para> + <emphasis><trademark class='trade'>Eclipse</trademark> IDE:</emphasis> + If your Build Host supports and runs the popular + Eclipse IDE, you can install the Yocto Project Eclipse + plug-in and use the Yocto Project to develop software. + The plug-in integrates the Yocto Project functionality + into Eclipse development practices.</para> + + <para>For information about how to install and use the + Yocto Project Eclipse plug-in, see the + "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-eclipse-project'>Developing Applications Using Eclipse</ulink>" + chapter in the Yocto Project Application Development and + the Extensible Software Development Kit (eSDK) Manual. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='reference-embedded-distribution'> + <title>Reference Embedded Distribution (Poky)</title> + + <para> + "Poky", which is pronounced <emphasis>Pock</emphasis>-ee, is the + name of the Yocto Project's reference distribution or Reference OS + Kit. + Poky contains the + <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded Build System</ulink> + (<ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink> and + <ulink url='&YOCTO_DOCS_REF_URL;#oe-core'>OpenEmbedded-Core</ulink>) + as well as a set of + <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>metadata</ulink> to get + you started building your own distro. + In other words, Poky is a base specification of the functionality + needed for a typical embedded system as well as the components + from the Yocto Project that allow you to build a distribution into + a usable binary image. + </para> + + <para> + Poky is a combined repository of BitBake, OpenEmbedded-Core + (which is found in <filename>meta</filename>), + <filename>meta-poky</filename>, + <filename>meta-yocto-bsp</filename>, and documentation provided + all together and known to work well together. + You can view these items that make up the Poky repository in the + <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/'>Source Repositories</ulink>. + <note> + If you are interested in all the contents of the + <filename>poky</filename> Git repository, see the + "<ulink url='&YOCTO_DOCS_REF_URL;#structure-core'>Top-Level Core Components</ulink>" + section in the Yocto Project Reference Manual. + </note> + </para> + + <para id='gs-poky-reference-distribution'> + The following figure illustrates what generally comprises Poky: + <imagedata fileref="figures/poky-reference-distribution.png" format="PNG" align='center' width="8in"/> + <itemizedlist> + <listitem><para> + BitBake is a task executor and scheduler that is the heart of + the OpenEmbedded build system. + </para></listitem> + <listitem><para> + <filename>meta-poky</filename>, which is Poky-specific + metadata. + </para></listitem> + <listitem><para> + <filename>meta-yocto-bsp</filename>, which are Yocto + Project-specific Board Support Packages (BSPs). + </para></listitem> + <listitem><para> + OpenEmbedded-Core (OE-Core) metadata, which includes + shared configurations, global variable definitions, + shared classes, packaging, and recipes. + Classes define the encapsulation and inheritance of build + logic. + Recipes are the logical units of software and images + to be built. + </para></listitem> + <listitem><para> + Documentation, which contains the Yocto Project source + files used to make the set of user manuals. + </para></listitem> + </itemizedlist> + <note> + While Poky is a "complete" distribution specification and is + tested and put through QA, you cannot use it as a product + "out of the box" in its current form. + </note> + </para> + + <para> + To use the Yocto Project tools, you can use Git to clone (download) + the Poky repository then use your local copy of the reference + distribution to bootstrap your own distribution. + <note> + Poky does not contain binary files. + It is a working example of how to build your own custom Linux distribution + from source. + </note> + </para> + + <para> + Poky has a regular, well established, six-month release cycle + under its own version. + Major releases occur at the same time major releases (point + releases) occur for the Yocto Project, which are typically in the + Spring and Fall. + For more information on the Yocto Project release schedule and + cadence, see the + "<ulink url='&YOCTO_DOCS_REF_URL;#ref-release-process'>Yocto Project Releases and the Stable Release Process</ulink>" + chapter in the Yocto Project Reference Manual. + </para> + + <para> + Much has been said about Poky being a "default configuration." + A default configuration provides a starting image footprint. + You can use Poky out of the box to create an image ranging from a + shell-accessible minimal image all the way up to a Linux + Standard Base-compliant image that uses a GNOME Mobile and + Embedded (GMAE) based reference user interface called Sato. + </para> + + <para> + One of the most powerful properties of Poky is that every aspect + of a build is controlled by the metadata. + You can use metadata to augment these base image types by + adding metadata + <link linkend='the-yocto-project-layer-model'>layers</link> + that extend functionality. + These layers can provide, for example, an additional software + stack for an image type, add a board support package (BSP) for + additional hardware, or even create a new image type. + </para> + + <para> + Metadata is loosely grouped into configuration files or package + recipes. + A recipe is a collection of non-executable metadata used by + BitBake to set variables or define additional build-time tasks. + A recipe contains fields such as the recipe description, the recipe + version, the license of the package and the upstream source + repository. + A recipe might also indicate that the build process uses autotools, + make, distutils or any other build process, in which case the basic + functionality can be defined by the classes it inherits from + the OE-Core layer's class definitions in + <filename>./meta/classes</filename>. + Within a recipe you can also define additional tasks as well as + task prerequisites. + Recipe syntax through BitBake also supports both + <filename>_prepend</filename> and <filename>_append</filename> + operators as a method of extending task functionality. + These operators inject code into the beginning or end of a task. + For information on these BitBake operators, see the + "<ulink url='&YOCTO_DOCS_BB_URL;#appending-and-prepending-override-style-syntax'>Appending and Prepending (Override Style Syntax)</ulink>" + section in the BitBake User's Manual. + </para> + </section> + + <section id='openembedded-build-system-workflow'> + <title>The OpenEmbedded Build System Workflow</title> + + <para> + The + <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink> + uses a "workflow" to accomplish image and SDK generation. + The following figure overviews that workflow: + <imagedata fileref="figures/YP-flow-diagram.png" + format="PNG" align='center' width="8in"/> + Following is a brief summary of the "workflow": + <orderedlist> + <listitem><para> + Developers specify architecture, policies, patches and + configuration details. + </para></listitem> + <listitem><para> + The build system fetches and downloads the source code + from the specified location. + The build system supports standard methods such as tarballs + or source code repositories systems such as Git. + </para></listitem> + <listitem><para> + Once source code is downloaded, the build system extracts + the sources into a local work area where patches are + applied and common steps for configuring and compiling + the software are run. + </para></listitem> + <listitem><para> + The build system then installs the software into a + temporary staging area where the binary package format you + select (DEB, RPM, or IPK) is used to roll up the software. + </para></listitem> + <listitem><para> + Different QA and sanity checks run throughout entire + build process. + </para></listitem> + <listitem><para> + After the binaries are created, the build system + generates a binary package feed that is used to create + the final root file image. + </para></listitem> + <listitem><para> + The build system generates the file system image and a + customized Extensible SDK (eSDSK) for application + development in parallel. + </para></listitem> + </orderedlist> + </para> + + <para> + For a very detailed look at this workflow, see the + "<link linkend='openembedded-build-system-build-concepts'>OpenEmbedded Build System Concepts</link>" + section. + </para> + </section> + + + <section id='some-basic-terms'> + <title>Some Basic Terms</title> + + <para> + It helps to understand some basic fundamental terms when + learning the Yocto Project. + Although a list of terms exists in the + "<ulink url='&YOCTO_DOCS_REF_URL;#ref-terms'>Yocto Project Terms</ulink>" + section of the Yocto Project Reference Manual, this section + provides the definitions of some terms helpful for getting started: + <itemizedlist> + <listitem><para> + <emphasis>Configuration Files:</emphasis> + Files that hold global definitions of variables, + user-defined variables, and hardware configuration + information. + These files tell the + <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>Open-Embedded build system</ulink> + what to build and what to put into the image to support a + particular platform. + </para></listitem> + <listitem><para> + <emphasis>Extensible Software Development Kit (eSDK):</emphasis> + A custom SDK for application developers. + This eSDK allows developers to incorporate their library + and programming changes back into the image to make + their code available to other application developers. + For information on the eSDK, see the + <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink> + manual. + </para></listitem> + <listitem><para> + <emphasis>Layer:</emphasis> + A collection of related recipes. + Layers allow you to consolidate related metadata to + customize your build. + Layers also isolate information used when building + for multiple architectures. + Layers are hierarchical in their ability to override + previous specifications. + You can include any number of available layers from the + Yocto Project and customize the build by adding your + layers after them. + You can search the Layer Index for layers used within + Yocto Project.</para> + + <para>For more detailed information on layers, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" + section in the Yocto Project Development Tasks Manual. + 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> + <emphasis>Metadata:</emphasis> + A key element of the Yocto Project is the Metadata that + is used to construct a Linux distribution and is contained + in the files that the OpenEmbedded build system parses + when building an image. + In general, Metadata includes recipes, configuration + files, and other information that refers to the build + instructions themselves, as well as the data used to + control what things get built and the effects of the + build. + Metadata also includes commands and data used to + indicate what versions of software are used, from + where they are obtained, and changes or additions to the + software itself (patches or auxiliary files) that + are used to fix bugs or customize the software for use + in a particular situation. + OpenEmbedded-Core is an important set of validated + metadata. + </para></listitem> + <listitem><para id='gs-term-openembedded-build-system'> + <emphasis>OpenEmbedded Build System:</emphasis> + The terms "BitBake" and "build system" are sometimes + used for the OpenEmbedded Build System.</para> + + <para>BitBake is a task scheduler and execution engine + that parses instructions (i.e. recipes) and configuration + data. + After a parsing phase, BitBake creates a dependency tree + to order the compilation, schedules the compilation of + the included code, and finally executes the building + of the specified custom Linux image (distribution). + BitBake is similar to the <filename>make</filename> + tool.</para> + + <para>During a build process, the build system tracks + dependencies and performs a native or cross-compilation + of the package. + As a first step in a cross-build setup, the framework + attempts to create a cross-compiler toolchain + (i.e. Extensible SDK) suited for the target platform. + </para></listitem> + <listitem><para> + <emphasis>OpenEmbedded-Core (OE-Core):</emphasis> + OE-Core is metadata comprised of foundation recipes, + classes, and associated files that are meant to be + common among many different OpenEmbedded-derived systems, + including the Yocto Project. + OE-Core is a curated subset of an original repository + developed by the OpenEmbedded community that has been + pared down into a smaller, core set of continuously + validated recipes. + The result is a tightly controlled and quality-assured + core set of recipes.</para> + + <para>You can see the Metadata in the + <filename>meta</filename> directory of the Yocto Project + <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi'>Source Repositories</ulink>. + </para></listitem> + <listitem><para> + <emphasis>Packages:</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_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>" + section in the Yocto Project Reference Manual 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. <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>, + <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>, + and + <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>). + </para></listitem> + <listitem><para> + <emphasis>Poky:</emphasis> + Poky is a reference embedded distribution and a reference + test configuration. + Poky provides the following: + <itemizedlist> + <listitem><para> + A base-level functional distro used to illustrate + how to customize a distribution. + </para></listitem> + <listitem><para> + A means by which to test the Yocto Project + components (i.e. Poky is used to validate + the Yocto Project). + </para></listitem> + <listitem><para> + A vehicle through which you can download + the Yocto Project. + </para></listitem> + </itemizedlist> + Poky is not a product level distro. + Rather, it is a good starting point for customization. + <note> + Poky is an integration layer on top of OE-Core. + </note> + </para></listitem> + <listitem><para> + <emphasis>Recipe:</emphasis> + The most common form of metadata. + A recipe contains a list of settings and tasks + (i.e. instructions) for building packages that are then + used to build the binary image. + A recipe describes where you get source code and which + patches to apply. + Recipes describe dependencies for libraries or for other + recipes as well as configuration and compilation options. + Related recipes are consolidated into a layer. + </para></listitem> + </itemizedlist> + </para> + </section> +</chapter> +<!-- +vim: expandtab tw=80 ts=4 +--> |
