summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2018-02-14 14:50:06 -0800
committerRichard Purdie <richard.purdie@linuxfoundation.org>2018-03-03 08:35:24 +0000
commit324da6588514813ba1adf93a8b04c797336cbe32 (patch)
treef1e5069580abd4d3c716ab22d715ed7c0b629808
parent8ec37c0811a57f779896ccdaf8d7f3f66f81f3bb (diff)
downloadpoky-324da6588514813ba1adf93a8b04c797336cbe32.tar.gz
getting-started: Created Components and Tools section
New content that leverages off the same information from the new website. (From yocto-docs rev: 1d5bf1501a1d0efe388dc5f4a7f741a272c6301c) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r--documentation/getting-started/getting-started-yp-intro.xml455
1 files changed, 449 insertions, 6 deletions
diff --git a/documentation/getting-started/getting-started-yp-intro.xml b/documentation/getting-started/getting-started-yp-intro.xml
index c160c1cf62..45c4b9ffdc 100644
--- a/documentation/getting-started/getting-started-yp-intro.xml
+++ b/documentation/getting-started/getting-started-yp-intro.xml
@@ -32,12 +32,9 @@
32 maintained and scaled. 32 maintained and scaled.
33 </para> 33 </para>
34 34
35 <mediaobject> 35 <para id='yp-key-dev-elements'>
36 <imageobject> 36 <imagedata fileref="figures/key-dev-elements.png" format="PNG" align='center' width="8in"/>
37 <imagedata fileref="figures/key-dev-elements.png" 37 </para>
38 format="PNG" align='center' width="8in"/>
39 </imageobject>
40 </mediaobject>
41 38
42 <para> 39 <para>
43 For further introductory information on the Yocto Project, you 40 For further introductory information on the Yocto Project, you
@@ -387,6 +384,452 @@
387 <section id='components-and-tools'> 384 <section id='components-and-tools'>
388 <title>Components and Tools</title> 385 <title>Components and Tools</title>
389 386
387 <para>
388 The Yocto Project employs a collection of components and
389 tools used by the project itself, by project developers,
390 and by those using the Yocto Project.
391 These components and tools are open source projects and
392 metadata that are separate from the reference distribution
393 (Poky) and the OpenEmbedded build system.
394 Most of the components and tools are downloaded separately.
395 </para>
396
397 <para>
398 This section provides brief overviews of the components and
399 tools associated with the Yocto Project.
400 </para>
401
402 <section id='gs-development-tools'>
403 <title>Development Tools</title>
404
405 <para>
406 The following list consists of tools that help you develop
407 images and applications using the Yocto Project:
408 <itemizedlist>
409 <listitem><para id='gs-crops-overview'>
410 <emphasis>CROPS:</emphasis>
411 <ulink url='https://git.yoctoproject.org/cgit/cgit.cgi/crops/about/'>CROPS</ulink>
412 is an open source, cross-platform development framework
413 that leverages
414 <ulink url='https://www.docker.com/'>Docker Containers</ulink>.
415 CROPS provides an easily managed, extensible environment
416 that allows you to build binaries for a variety of
417 architectures on Windows, Linux and Mac OS X hosts.
418 </para></listitem>
419 <listitem><para>
420 <emphasis><filename>devtool</filename>:</emphasis>
421 This command-line tool is available as part of the
422 extensible SDK (eSDK) and is its cornerstone.
423 You can use <filename>devtool</filename> to help build,
424 test, and package software within the eSDK.
425 You can use the tool to optionally integrate what you
426 build into an image built by the OpenEmbedded build
427 system.</para>
428
429 <para>The <filename>devtool</filename> command employs
430 a number of sub-commands that allow you to add, modify,
431 and upgrade recipes.
432 As with the OpenEmbedded build system, “recipes”
433 represent software packages within
434 <filename>devtool</filename>.
435 When you use <filename>devtool add</filename>, a recipe
436 is automatically created.
437 When you use <filename>devtool modify</filename>, the
438 specified existing recipe is used in order to determine
439 where to get the source code and how to patch it.
440 In both cases, an environment is set up so that when
441 you build the recipe a source tree that is under your
442 control is used in order to allow you to make changes
443 to the source as desired.
444 By default, both new recipes and the source go into
445 a “workspace” directory under the eSDK.
446 The <filename>devtool upgrade</filename> command
447 updates an existing recipe so that you can build it
448 for an updated set of source files.</para>
449
450 <para>You can read about the
451 <filename>devtool</filename> workflow in the Yocto
452 Project Application Development and Extensible
453 Software Development Kit (eSDK) Manual in the
454 "<ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'>Using <filename>devtool</filename> in Your SDK Workflow'</ulink>"
455 section.
456 </para></listitem>
457 <listitem><para>
458 <emphasis>Extensible Software Development Kit (eSDK):</emphasis>
459 The eSDK provides a cross-development toolchain and
460 libraries tailored to the contents of a specific image.
461 The eSDK makes it easy to add new applications and
462 libraries to an image, modify the source for an
463 existing component, test changes on the target
464 hardware, and integrate into the rest of the
465 OpenEmbedded build system.
466 The eSDK gives you a toolchain experience supplemented
467 with the powerful set of <filename>devtool</filename>
468 commands tailored for the Yocto Project environment.
469 </para>
470
471 <para>For information on the eSDK, see the
472 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and Extensible Software Development Kit (eSDK) Manual</ulink>.
473 </para></listitem>
474 <listitem><para>
475 <emphasis><trademark class='trade'>Eclipse</trademark> IDE Plug-in:</emphasis>
476 This plug-in enables you to use the popular Eclipse
477 Integrated Development Environment (IDE), which allows
478 for development using the Yocto Project all within the
479 Eclipse IDE.
480 You can work within Eclipse to cross-compile, deploy,
481 and execute your output into a QEMU emulation session
482 as well as onto actual target hardware.</para>
483
484 <para>The environment also supports performance
485 enhancing tools that allow you to perform remote
486 profiling, tracing, collection of power data,
487 collection of latency data, and collection of
488 performance data.</para>
489
490 <para>Once you enable the plug-in, standard Eclipse
491 functions automatically use the cross-toolchain
492 and target system libraries.
493 You can build applications using any of these
494 libraries.</para>
495
496 <para>For more information on the Eclipse plug-in,
497 see the
498 "<ulink url='&YOCTO_DOCS_SDK_URL;#adt-eclipse'>Working Within Eclipse</ulink>"
499 section in the Yocto Project Application Development
500 and the Extensible Software Development Kit (eSDK)
501 manual.
502 </para></listitem>
503 <listitem><para>
504 <emphasis>Toaster:</emphasis>
505 Toaster is a web interface to the Yocto Project
506 OpenEmbedded build system.
507 Toaster allows you to configure, run, and view
508 information about builds.
509 </para></listitem>
510 </itemizedlist>
511 </para>
512 </section>
513
514 <section id='gs-production-tools'>
515 <title>Production Tools</title>
516
517 <para>
518 The following list consists of tools that help production
519 related activities using the Yocto Project:
520 <itemizedlist>
521 <listitem><para>
522 <emphasis>Auto Upgrade Helper:</emphasis>
523 This utility when used in conjunction with the
524 OpenEmbedded build system (BitBake and OE-Core)
525 automatically generates upgrades for recipes that
526 are based on new versions of the recipes published
527 upstream.
528 </para></listitem>
529 <listitem><para>
530 <emphasis>Recipe Reporting System:</emphasis>
531 The Recipe Reporting System tracks recipe versions
532 available for Yocto Project.
533 The main purpose of the system is to help you
534 manage the recipes you maintain and to offer a dynamic
535 overview of the project.
536 The Recipe Reporting System tracks is built on top
537 the of OpenEmbedded Metadata Index, which is a website
538 that indexes layers for the OpenEmbedded build system.
539 </para></listitem>
540 <listitem><para>
541 <emphasis>Patchwork:</emphasis>
542 <ulink url='http://jk.ozlabs.org/projects/patchwork/'>Patchwork</ulink>
543 is a fork of a project originally started by
544 <ulink url='http://ozlabs.org/'>OzLabs</ulink>.
545 The project is a web-based tracking system designed
546 to streamline the process of bringing contributions
547 into a project.
548 The Yocto Project uses Patchwork as an organizational
549 tool to handle patches, which number in the thousands
550 for every release.
551 </para></listitem>
552 <listitem><para>
553 <emphasis>AutoBuilder:</emphasis>
554 AutoBuilder is a project that automates build tests
555 and quality assurance (QA).
556 By using the public AutoBuilder, anyone can determine
557 the status of the current "master" branch of Poky.
558 </para>
559
560 <para>A goal of the Yocto Project is to lead the
561 open source industry with a project that automates
562 testing and QA procedures.
563 In doing so, the project encourages a development
564 community that publishes QA and test plans, publicly
565 demonstrates QA and test plans, and encourages
566 development of tools that automate and test and QA
567 procedures for the benefit of the development
568 community.</para>
569
570 <para>You can learn more about the AutoBuilder used
571 by the Yocto Project
572 <ulink url='&YOCTO_AB_URL;'>here</ulink>.
573 </para></listitem>
574 <listitem><para>
575 <emphasis>Cross-Prelink:</emphasis>
576 Prelinking is the process of pre-computing the load
577 addresses and link tables generated by the dynamic
578 linker as compared to doing this at runtime.
579 Doing this ahead of time results in performance
580 improvements when the application is launched and
581 reduced memory usage for libraries shared by many
582 applications.</para>
583
584 <para>Historically, cross-prelink is a variant of
585 prelink, which was conceived by
586 <ulink url='http://people.redhat.com/jakub/prelink.pdf'>Jakub Jel&iacute;nek</ulink>
587 a number of years ago.
588 Both prelink and cross-prelink are maintained in the
589 same repository albeit on separate branches.
590 By providing an emulated runtime dynamic linker
591 (i.e. <filename>glibc</filename>-derived
592 <filename>ld.so</filename> emulation), the
593 cross-prelink project extends the prelink software’s
594 ability to prelink a sysroot environment.
595 Additionally, the cross-prelink software enables the
596 ability to work in sysroot style environments.</para>
597
598 <para>The dynamic linker determines standard load
599 address calculations based on a variety of factors
600 such as mapping addresses, library usage, and library
601 function conflicts.
602 The prelink tool uses this information, from the
603 dynamic linker, to determine unique load addresses
604 for executable and linkable format (ELF) binaries
605 that are shared libraries and dynamically linked.
606 The prelink tool modifies these ELF binaries with the
607 pre-computed information.
608 The result is faster loading and often lower memory
609 consumption because more of the library code can
610 be re-used from shared Copy-On-Write (COW) pages.
611 </para>
612
613 <para>The original upstream prelink project only
614 supports running prelink on the end target device
615 due to the reliance on the target device’s dynamic
616 linker.
617 This restriction causes issues when developing a
618 cross-compiled system.
619 The cross-prelink adds a synthesized dynamic loader
620 that runs on the host, thus permitting cross-prelinking
621 without ever having to run on a read-write target
622 filesystem.
623 </para></listitem>
624 <listitem><para>
625 <emphasis>Pseudo:</emphasis>
626 Pseudo is the Yocto Project implementation of
627 <ulink url='http://man.he.net/man1/fakeroot'>fakeroot</ulink>,
628 which is used to run commands in an environment
629 that seemingly has root privileges.</para>
630
631 <para>During a build, it can be necessary to perform
632 operations that require system administrator
633 privileges.
634 For example, file ownership or permissions might need
635 definition.
636 Pseudo is a tool that you can either use directly or
637 through the environment variable
638 <filename>LD_PRELOAD</filename>.
639 Either method allows these operations to succeed as
640 if system administrator privileges exist even
641 when they do not.</para>
642
643 <para>You can read more about Pseudo in the
644 "<ulink url='&YOCTO_DOCS_CM_URL;#fakeroot-and-pseudo'>Fakeroot and Pseudo</ulink>"
645 section of the Yocto Project Concepts Manual.
646 </para></listitem>
647 </itemizedlist>
648 </para>
649 </section>
650
651 <section id='gs-openembedded-build-system'>
652 <title>Open-Embedded Build System Components</title>
653
654 <para>
655 The following list consists of components associated with the
656 Open-Embedded build system:
657 <itemizedlist>
658 <listitem><para>
659 <emphasis>BitBake:</emphasis>
660 BitBake is a core component of the Yocto Project and is
661 used by the OpenEmbedded build system to build images.
662 While BitBake is key to the build system, BitBake
663 is maintained separately from the Yocto Project.</para>
664
665 <para>BitBake is a generic task execution engine that
666 allows shell and Python tasks to be run efficiently
667 and in parallel while working within complex inter-task
668 dependency constraints.
669 In short, BitBake is a build engine that works
670 through recipes written in a specific format in order
671 to perform sets of tasks.</para>
672
673 <para>You can learn more about BitBake in the
674 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
675 </para></listitem>
676 <listitem><para>
677 <emphasis>Openembedded Core:</emphasis>
678 OpenEmbedded Core (OE-Core) is a common layer of
679 metadata (i.e. recipes, classes, and associated files)
680 used by OpenEmbedded-derived systems, which includes
681 the Yocto Project.
682 The Yocto Project and the OpenEmbedded Project both
683 maintain the OpenEmbedded Core.
684 You can find the OE-Core metadata in the Yocto
685 Project
686 <ulink url='&YOCTO_DOCS_GS_URL;#source-repositories'>Source Repositories</ulink>
687 <ulink url='https://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta'>here</ulink>.
688 </para>
689
690 <para>Historically, the Yocto Project integrated the
691 OE-Core metadata throughout the Yocto Project
692 source repository reference system (Poky).
693 After Yocto Project Version 1.0, the Yocto Project
694 and OpenEmbedded agreed to work together and share a
695 common core set of metadata (OE-Core), which contained
696 much of the functionality previously found in Poky.
697 This collaboration achieved a long-standing
698 OpenEmbedded objective for having a more tightly
699 controlled and quality-assured core.
700 The results also fit well with the Yocto Project
701 objective of achieving a smaller number of fully
702 featured tools as compared to many different ones.
703 </para>
704
705 <para>Sharing a core set of metadata results in Poky
706 as an integration layer on top of OE-Core.
707 You can see that in this
708 <link linkend='yp-key-dev-elements'>figure</link>.
709 The Yocto Project combines various components such as
710 BitBake, OE-Core, script “glue”, and documentation
711 for its build system.
712 </para></listitem>
713 </itemizedlist>
714 </para>
715 </section>
716
717 <section id='gs-reference-distribution-poky'>
718 <title>Reference Distribution (Poky)</title>
719
720 <para>
721 Poky is the Yocto Project reference distribution.
722 It contains the OpenEmbedded build system (BitBake and OE-Core)
723 as well as a set of metadata to get you started building your
724 own distribution.
725 See the
726 <link linkend='what-is-the-yocto-project'>figure</link> in
727 "What is the Yocto Project?" section for an illustration
728 that shows Poky and its relationship with other parts of the
729 Yocto Project.</para>
730
731 <para>To use the Yocto Project tools and components, you
732 can download (<filename>clone</filename>) Poky and use it
733 to bootstrap your own distribution.
734 <note>
735 Poky does not contain binary files.
736 It is a working example of how to build your own custom
737 Linux distribution from source.
738 </note>
739 </para>
740 </section>
741
742 <section id='gs-packages-for-finished-targets'>
743 <title>Packages for Finished Targets</title>
744
745 <para>
746 The following lists components associated with packages
747 for finished targets:
748 <itemizedlist>
749 <listitem><para>
750 <emphasis>Matchbox:</emphasis>
751 Matchbox is an Open Source, base environment for the
752 X Window System running on non-desktop, embedded
753 platforms such as handhelds, set-top boxes, kiosks,
754 and anything else for which screen space, input
755 mechanisms, or system resources are limited.</para>
756
757 <para>Matchbox consists of a number of interchangeable
758 and optional applications that you can tailor to a
759 specific, non-desktop platform to enhance usability
760 in constrained environments.</para>
761
762 <para>You can find the Matchbox source in its
763 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi'>repository</ulink>
764 listed in the Yocto Project
765 <ulink url='&YOCTO_DOCS_GS_URL;#source-repositories'>Source Repositories</ulink>.
766 </para></listitem>
767 <listitem><para>
768 <emphasis>Opkg</emphasis>
769 Open PacKaGe management (opkg) is a lightweight
770 package management system based on the itsy package
771 (ipkg) management system.
772 Opkg is written in C and resembles Advanced Package
773 Tool (APT) and Debian Package (dpkg) in operation.
774 </para>
775
776 <para>Opkg is intended for use on embedded Linux
777 devices and is used in this capacity in the
778 <ulink url='http://www.openembedded.org/wiki/Main_Page'>OpenEmbedded</ulink>
779 and
780 <ulink url='https://openwrt.org/'>OpenWrt</ulink>
781 projects, as well as the Yocto Project.
782 <note>
783 As best it can, opkg maintains backwards
784 compatibility with ipkg and conforms to a subset
785 of Debian’s policy manual regarding control files.
786 </note>
787 </para></listitem>
788 </itemizedlist>
789 </para>
790 </section>
791
792 <section id='gs-archived-components'>
793 <title>Archived Components</title>
794
795 <para>
796 The Build Appliance is a virtual machine image that enables
797 you to build and boot a custom embedded Linux image with
798 the Yocto Project using a non-Linux development system.
799 </para>
800
801 <para>
802 Historically, the Build Appliance was the second of three
803 methods by which you could use the Yocto Project on a system
804 that was not native to Linux.
805 <orderedlist>
806 <listitem><para>
807 <emphasis>Hob:</emphasis>
808 Hob, which is now deprecated and is no longer available
809 since the 2.1 release of the Yocto Project provided
810 a rudimentary, GUI-based interface to the Yocto
811 Project.
812 Toaster has fully replaced Hob.
813 </para></listitem>
814 <listitem><para>
815 <emphasis>Build Appliance:</emphasis>
816 Post Hob, the Build Appliance became available.
817 It was never recommended that you use the Build
818 Appliance as a day-to-day production development
819 environment with the Yocto Project.
820 Build Appliance was useful as a way to try out
821 development in the Yocto Project environment.
822 </para></listitem>
823 <listitem><para>
824 <emphasis>CROPS:</emphasis>
825 The final and best solution available now for
826 developing using the Yocto Project on a system
827 not native to Linux is with
828 <link linkend='gs-crops-overview'>CROPS</link>.
829 </para></listitem>
830 </orderedlist>
831 </para>
832 </section>
390 </section> 833 </section>
391 834
392 <section id='the-development-environment'> 835 <section id='the-development-environment'>