summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2017-06-13 16:14:51 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2017-06-22 09:16:42 +0100
commit45b16e35b606cfd2c4ab7f89ebe91e43995acb2a (patch)
tree0b0399cb502f85ab8f85ddd4bbe07614071ae08e /documentation/dev-manual
parentdccca9af475effc9389844f2a9a0466c035569ce (diff)
downloadpoky-45b16e35b606cfd2c4ab7f89ebe91e43995acb2a.tar.gz
documentation: Fixed links to "bitbake-term"
Fixes [YOCTO #11630] Moving the "Yocto Project Terms" section from the dev-manual to the ref-manual. Doing so caused all the links to the id "bitbake-term" to break. These had to be individually fixed. Discovered two unresolved references that were a consequence of moving that section to the ref-manual. These were fixed as well. (From yocto-docs rev: 829ca6b64562f00a69f3956e9636c7edaa90ce16) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r--documentation/dev-manual/dev-manual-newbie.xml346
-rw-r--r--documentation/dev-manual/dev-manual-start.xml3
2 files changed, 2 insertions, 347 deletions
diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml
index 00b8c44801..350c6e49a8 100644
--- a/documentation/dev-manual/dev-manual-newbie.xml
+++ b/documentation/dev-manual/dev-manual-newbie.xml
@@ -490,352 +490,6 @@
490 </para> 490 </para>
491</section> 491</section>
492 492
493<section id='yocto-project-terms'>
494 <title>Yocto Project Terms</title>
495
496 <para>
497 Following is a list of terms and definitions users new to the Yocto Project development
498 environment might find helpful.
499 While some of these terms are universal, the list includes them just in case:
500 <itemizedlist>
501 <listitem><para><emphasis>Append Files:</emphasis> Files that append build information to
502 a recipe file.
503 Append files are known as BitBake append files and <filename>.bbappend</filename> files.
504 The OpenEmbedded build system expects every append file to have a corresponding
505 recipe (<filename>.bb</filename>) file.
506 Furthermore, the append file and corresponding recipe file
507 must use the same root filename.
508 The filenames can differ only in the file type suffix used (e.g.
509 <filename>formfactor_0.0.bb</filename> and <filename>formfactor_0.0.bbappend</filename>).
510 </para>
511 <para>Information in append files extends or overrides the
512 information in the similarly-named recipe file.
513 For an example of an append file in use, see the
514 "<link linkend='using-bbappend-files'>Using .bbappend Files</link>" section.
515 <note>
516 Append files can also use wildcard patterns in their version numbers
517 so they can be applied to more than one version of the underlying recipe file.
518 </note>
519 </para></listitem>
520 <listitem><para id='bitbake-term'><emphasis>BitBake:</emphasis>
521 The task executor and scheduler used by the OpenEmbedded build
522 system to build images.
523 For more information on BitBake, see the
524 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
525 </para></listitem>
526 <listitem>
527 <para id='build-directory'><emphasis>Build Directory:</emphasis>
528 This term refers to the area used by the OpenEmbedded build
529 system for builds.
530 The area is created when you <filename>source</filename> the
531 setup environment script that is found in the Source Directory
532 (i.e. <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
533 or
534 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>).
535 The <ulink url='&YOCTO_DOCS_REF_URL;#var-TOPDIR'><filename>TOPDIR</filename></ulink>
536 variable points to the Build Directory.</para>
537
538 <para>
539 You have a lot of flexibility when creating the Build
540 Directory.
541 Following are some examples that show how to create the
542 directory.
543 The examples assume your
544 <link linkend='source-directory'>Source Directory</link> is
545 named <filename>poky</filename>:
546 <itemizedlist>
547 <listitem><para>Create the Build Directory inside your
548 Source Directory and let the name of the Build
549 Directory default to <filename>build</filename>:
550 <literallayout class='monospaced'>
551 $ cd $HOME/poky
552 $ source &OE_INIT_FILE;
553 </literallayout></para></listitem>
554 <listitem><para>Create the Build Directory inside your
555 home directory and specifically name it
556 <filename>test-builds</filename>:
557 <literallayout class='monospaced'>
558 $ cd $HOME
559 $ source poky/&OE_INIT_FILE; test-builds
560 </literallayout></para></listitem>
561 <listitem><para>
562 Provide a directory path and
563 specifically name the Build Directory.
564 Any intermediate folders in the pathname must
565 exist.
566 This next example creates a Build Directory named
567 <filename>YP-&POKYVERSION;</filename>
568 in your home directory within the existing
569 directory <filename>mybuilds</filename>:
570 <literallayout class='monospaced'>
571 $cd $HOME
572 $ source $HOME/poky/&OE_INIT_FILE; $HOME/mybuilds/YP-&POKYVERSION;
573 </literallayout></para></listitem>
574 </itemizedlist>
575 <note>
576 By default, the Build Directory contains
577 <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>,
578 which is a temporary directory the build system uses for
579 its work.
580 <filename>TMPDIR</filename> cannot be under NFS.
581 Thus, by default, the Build Directory cannot be under NFS.
582 However, if you need the Build Directory to be under NFS,
583 you can set this up by setting <filename>TMPDIR</filename>
584 in your <filename>local.conf</filename> file
585 to use a local drive.
586 Doing so effectively separates <filename>TMPDIR</filename>
587 from <filename>TOPDIR</filename>, which is the Build
588 Directory.
589 </note>
590 </para></listitem>
591 <listitem><para><emphasis>Classes:</emphasis> Files that provide for logic encapsulation
592 and inheritance so that commonly used patterns can be defined once and then easily used
593 in multiple recipes.
594 For reference information on the Yocto Project classes, see the
595 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes'>Classes</ulink>" chapter of the
596 Yocto Project Reference Manual.
597 Class files end with the <filename>.bbclass</filename> filename extension.
598 </para></listitem>
599 <listitem><para><emphasis>Configuration File:</emphasis>
600 Configuration information in various <filename>.conf</filename>
601 files provides global definitions of variables.
602 The <filename>conf/local.conf</filename> configuration file in
603 the
604 <link linkend='build-directory'>Build Directory</link>
605 contains user-defined variables that affect every build.
606 The <filename>meta-poky/conf/distro/poky.conf</filename>
607 configuration file defines Yocto "distro" configuration
608 variables used only when building with this policy.
609 Machine configuration files, which
610 are located throughout the
611 <link linkend='source-directory'>Source Directory</link>, define
612 variables for specific hardware and are only used when building
613 for that target (e.g. the
614 <filename>machine/beaglebone.conf</filename> configuration
615 file defines variables for the Texas Instruments ARM Cortex-A8
616 development board).
617 Configuration files end with a <filename>.conf</filename>
618 filename extension.
619 </para></listitem>
620 <listitem><para id='cross-development-toolchain'>
621 <emphasis>Cross-Development Toolchain:</emphasis>
622 In general, a cross-development toolchain is a collection of
623 software development tools and utilities that run on one
624 architecture and allow you to develop software for a
625 different, or targeted, architecture.
626 These toolchains contain cross-compilers, linkers, and
627 debuggers that are specific to the target architecture.
628 </para>
629
630 <para>The Yocto Project supports two different cross-development
631 toolchains:
632 <itemizedlist>
633 <listitem><para>A toolchain only used by and within
634 BitBake when building an image for a target
635 architecture.</para></listitem>
636 <listitem><para>A relocatable toolchain used outside of
637 BitBake by developers when developing applications
638 that will run on a targeted device.
639 </para></listitem>
640 </itemizedlist>
641 </para>
642
643 <para>
644 Creation of these toolchains is simple and automated.
645 For information on toolchain concepts as they apply to the
646 Yocto Project, see the
647 "<ulink url='&YOCTO_DOCS_REF_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>"
648 section in the Yocto Project Reference Manual.
649 You can also find more information on using the
650 relocatable toolchain in the
651 <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>.
652 </para></listitem>
653 <listitem><para><emphasis>Image:</emphasis>
654 An image is an artifact of the BitBake build process given
655 a collection of recipes and related Metadata.
656 Images are the binary output that run on specific hardware or
657 QEMU and are used for specific use-cases.
658 For a list of the supported image types that the Yocto Project provides, see the
659 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
660 chapter in the Yocto Project Reference Manual.</para></listitem>
661 <listitem><para id='layer'><emphasis>Layer:</emphasis> A collection of recipes representing the core,
662 a BSP, or an application stack.
663 For a discussion specifically on BSP Layers, see the
664 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
665 section in the Yocto Project Board Support Packages (BSP)
666 Developer's Guide.</para></listitem>
667 <listitem><para id='metadata'><emphasis>Metadata:</emphasis>
668 The files that BitBake parses when building an image.
669 In general, Metadata includes recipes, classes, and
670 configuration files.
671 In the context of the kernel ("kernel Metadata"),
672 it refers to Metadata in the <filename>meta</filename>
673 branches of the kernel source Git repositories.
674 </para></listitem>
675 <listitem><para id='oe-core'><emphasis>OE-Core:</emphasis> A core set of Metadata originating
676 with OpenEmbedded (OE) that is shared between OE and the Yocto Project.
677 This Metadata is found in the <filename>meta</filename> directory of the
678 <link linkend='source-directory'>Source Directory</link>.</para></listitem>
679 <listitem><para id='build-system-term'><emphasis>OpenEmbedded Build System:</emphasis>
680 The build system specific to the Yocto Project.
681 The OpenEmbedded build system is based on another project known
682 as "Poky", which uses
683 <link linkend='bitbake-term'>BitBake</link> as the task
684 executor.
685 Throughout the Yocto Project documentation set, the
686 OpenEmbedded build system is sometimes referred to simply
687 as "the build system".
688 If other build systems, such as a host or target build system
689 are referenced, the documentation clearly states the
690 difference.
691 <note>
692 For some historical information about Poky, see the
693 <link linkend='poky'>Poky</link> term.
694 </note>
695 </para></listitem>
696 <listitem><para><emphasis>Package:</emphasis>
697 In the context of the Yocto Project, this term refers to a
698 recipe's packaged output produced by BitBake (i.e. a
699 "baked recipe").
700 A package is generally the compiled binaries produced from the
701 recipe's sources.
702 You "bake" something by running it through BitBake.</para>
703 <para>It is worth noting that the term "package" can, in general, have subtle
704 meanings. For example, the packages referred to in the
705 "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Build Host Packages</ulink>" section are
706 compiled binaries that, when installed, add functionality to your Linux
707 distribution.</para>
708 <para>Another point worth noting is that historically within the Yocto Project,
709 recipes were referred to as packages - thus, the existence of several BitBake
710 variables that are seemingly mis-named,
711 (e.g. <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>,
712 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>, and
713 <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>).
714 </para></listitem>
715 <listitem><para><emphasis>Package Groups:</emphasis>
716 Arbitrary groups of software Recipes.
717 You use package groups to hold recipes that, when built,
718 usually accomplish a single task.
719 For example, a package group could contain the recipes for a
720 company’s proprietary or value-add software.
721 Or, the package group could contain the recipes that enable
722 graphics.
723 A package group is really just another recipe.
724 Because package group files are recipes, they end with the
725 <filename>.bb</filename> filename extension.</para></listitem>
726 <listitem><para id='poky'><emphasis>Poky:</emphasis>
727 The term "poky" can mean several things.
728 In its most general sense, it is an open-source
729 project that was initially developed by OpenedHand.
730 With OpenedHand, poky was developed off of the existing
731 OpenEmbedded build system becoming a commercially
732 supportable build system for embedded Linux.
733 After Intel Corporation acquired OpenedHand, the
734 project poky became the basis for the Yocto Project's
735 build system.</para>
736 <para>Within the Yocto Project source repositories,
737 <filename>poky</filename> exists as a separate Git
738 repository you can clone to yield a local copy on your
739 host system.
740 Thus, "poky" can refer to the local copy of the Source
741 Directory used for development within the Yocto
742 Project.</para>
743 <para>Finally, "poky" can refer to the default
744 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
745 (i.e. distribution) created when you use the Yocto
746 Project in conjunction with the
747 <filename>poky</filename> repository to build an image.
748 </para></listitem>
749 <listitem><para><emphasis>Recipe:</emphasis>
750 A set of instructions for building packages.
751 A recipe describes where you get source code, which patches
752 to apply, how to configure the source, how to compile it and so on.
753 Recipes also describe dependencies for libraries or for other
754 recipes.
755 Recipes represent the logical unit of execution, the software
756 to build, the images to build, and use the
757 <filename>.bb</filename> file extension.
758 </para></listitem>
759 <listitem>
760 <para id='source-directory'><emphasis>Source Directory:</emphasis>
761 This term refers to the directory structure created as a result
762 of creating a local copy of the <filename>poky</filename> Git
763 repository <filename>git://git.yoctoproject.org/poky</filename>
764 or expanding a released <filename>poky</filename> tarball.
765 <note>
766 Creating a local copy of the <filename>poky</filename>
767 Git repository is the recommended method for setting up
768 your Source Directory.
769 </note>
770 Sometimes you might hear the term "poky directory" used to refer
771 to this directory structure.
772 <note>
773 The OpenEmbedded build system does not support file or
774 directory names that contain spaces.
775 Be sure that the Source Directory you use does not contain
776 these types of names.
777 </note></para>
778
779 <para>The Source Directory contains BitBake, Documentation,
780 Metadata and other files that all support the Yocto Project.
781 Consequently, you must have the Source Directory in place on
782 your development system in order to do any development using
783 the Yocto Project.</para>
784
785 <para>When you create a local copy of the Git repository, you
786 can name the repository anything you like.
787 Throughout much of the documentation, "poky"
788 is used as the name of the top-level folder of the local copy of
789 the poky Git repository.
790 So, for example, cloning the <filename>poky</filename> Git
791 repository results in a local Git repository whose top-level
792 folder is also named "poky".</para>
793
794 <para>While it is not recommended that you use tarball expansion
795 to set up the Source Directory, if you do, the top-level
796 directory name of the Source Directory is derived from the
797 Yocto Project release tarball.
798 For example, downloading and unpacking
799 <filename>&YOCTO_POKY_TARBALL;</filename> results in a
800 Source Directory whose root folder is named
801 <filename>&YOCTO_POKY;</filename>.</para>
802
803 <para>It is important to understand the differences between the
804 Source Directory created by unpacking a released tarball as
805 compared to cloning
806 <filename>git://git.yoctoproject.org/poky</filename>.
807 When you unpack a tarball, you have an exact copy of the files
808 based on the time of release - a fixed release point.
809 Any changes you make to your local files in the Source Directory
810 are on top of the release and will remain local only.
811 On the other hand, when you clone the <filename>poky</filename>
812 Git repository, you have an active development repository with
813 access to the upstream repository's branches and tags.
814 In this case, any local changes you make to the local
815 Source Directory can be later applied to active development
816 branches of the upstream <filename>poky</filename> Git
817 repository.</para>
818
819 <para>For more information on concepts related to Git
820 repositories, branches, and tags, see the
821 "<link linkend='repositories-tags-and-branches'>Repositories, Tags, and Branches</link>"
822 section.</para></listitem>
823 <listitem><para><emphasis>Task:</emphasis>
824 A unit of execution for BitBake (e.g.
825 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile</filename></ulink>,
826 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>do_fetch</filename></ulink>,
827 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-patch'><filename>do_patch</filename></ulink>,
828 and so forth).
829 </para></listitem>
830 <listitem><para><emphasis>Upstream:</emphasis> A reference to source code or repositories
831 that are not local to the development system but located in a master area that is controlled
832 by the maintainer of the source code.
833 For example, in order for a developer to work on a particular piece of code, they need to
834 first get a copy of it from an "upstream" source.</para></listitem>
835 </itemizedlist>
836 </para>
837</section>
838
839<section id='licensing'> 493<section id='licensing'>
840 <title>Licensing</title> 494 <title>Licensing</title>
841 495
diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml
index b8527f670a..0e335e28fc 100644
--- a/documentation/dev-manual/dev-manual-start.xml
+++ b/documentation/dev-manual/dev-manual-start.xml
@@ -34,7 +34,8 @@
34 34
35 <para> 35 <para>
36 You can use the OpenEmbedded build system, which uses 36 You can use the OpenEmbedded build system, which uses
37 <link linkend='bitbake-term'>BitBake</link>, to develop complete Linux 37 <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>,
38 to develop complete Linux
38 images and associated user-space applications for architectures based 39 images and associated user-space applications for architectures based
39 on ARM, MIPS, PowerPC, x86 and x86-64. 40 on ARM, MIPS, PowerPC, x86 and x86-64.
40 <note> 41 <note>
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2026-02-13 12:30:59 +0000