summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--documentation/ref-manual/ref-classes.xml152
1 files changed, 71 insertions, 81 deletions
diff --git a/documentation/ref-manual/ref-classes.xml b/documentation/ref-manual/ref-classes.xml
index d80fd77f9f..e3d7544c02 100644
--- a/documentation/ref-manual/ref-classes.xml
+++ b/documentation/ref-manual/ref-classes.xml
@@ -179,7 +179,7 @@
179 <title>Pkg-config - <filename>pkgconfig.bbclass</filename></title> 179 <title>Pkg-config - <filename>pkgconfig.bbclass</filename></title>
180 180
181 <para> 181 <para>
182 <filename>pkg-config</filename> provides a standard way to get 182 <filename>pkg-config</filename> provides a standard way to get
183 header and library information. 183 header and library information.
184 This class aims to smooth integration of 184 This class aims to smooth integration of
185 <filename>pkg-config</filename> into libraries that use it. 185 <filename>pkg-config</filename> into libraries that use it.
@@ -198,7 +198,7 @@
198 198
199 <para> 199 <para>
200 Many software licenses require that source code and other materials be 200 Many software licenses require that source code and other materials be
201 released with the binaries. 201 released with the binaries.
202 To help with that task, the following classes are provided: 202 To help with that task, the following classes are provided:
203 <itemizedlist> 203 <itemizedlist>
204 <listitem><filename>archive-original-sources.bbclass</filename></listitem> 204 <listitem><filename>archive-original-sources.bbclass</filename></listitem>
@@ -515,47 +515,47 @@
515 since <filename>pkg-config</filename> itself adds the correct sysroot prefix 515 since <filename>pkg-config</filename> itself adds the correct sysroot prefix
516 when the files are accessed.</para></listitem> 516 when the files are accessed.</para></listitem>
517 <listitem><para><emphasis><filename>textrel:</filename></emphasis> 517 <listitem><para><emphasis><filename>textrel:</filename></emphasis>
518 Checks for ELF binaries that contain relocations in their 518 Checks for ELF binaries that contain relocations in their
519 <filename>.text</filename> sections, which can result in a 519 <filename>.text</filename> sections, which can result in a
520 performance impact at runtime.</para></listitem> 520 performance impact at runtime.</para></listitem>
521 <listitem><para><emphasis><filename>pkgvarcheck:</filename></emphasis> 521 <listitem><para><emphasis><filename>pkgvarcheck:</filename></emphasis>
522 Checks through the variables 522 Checks through the variables
523 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>, 523 <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>,
524 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>, 524 <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
525 <link linkend='var-RSUGGESTS'><filename>RSUGGESTS</filename></link>, 525 <link linkend='var-RSUGGESTS'><filename>RSUGGESTS</filename></link>,
526 <link linkend='var-RCONFLICTS'><filename>RCONFLICTS</filename></link>, 526 <link linkend='var-RCONFLICTS'><filename>RCONFLICTS</filename></link>,
527 <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>, 527 <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>,
528 <link linkend='var-RREPLACES'><filename>RREPLACES</filename></link>, 528 <link linkend='var-RREPLACES'><filename>RREPLACES</filename></link>,
529 <link linkend='var-FILES'><filename>FILES</filename></link>, 529 <link linkend='var-FILES'><filename>FILES</filename></link>,
530 <link linkend='var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></link>, 530 <link linkend='var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></link>,
531 <filename>pkg_preinst</filename>, 531 <filename>pkg_preinst</filename>,
532 <filename>pkg_postinst</filename>, 532 <filename>pkg_postinst</filename>,
533 <filename>pkg_prerm</filename> 533 <filename>pkg_prerm</filename>
534 and <filename>pkg_postrm</filename>, and reports if there are 534 and <filename>pkg_postrm</filename>, and reports if there are
535 variable sets that are not package-specific. 535 variable sets that are not package-specific.
536 Using these variables without a package suffix is bad practice, 536 Using these variables without a package suffix is bad practice,
537 and might unnecessarily complicate dependencies of other packages 537 and might unnecessarily complicate dependencies of other packages
538 within the same recipe or have other unintended consequences. 538 within the same recipe or have other unintended consequences.
539 </para></listitem> 539 </para></listitem>
540 <listitem><para><emphasis><filename>xorg-driver-abi:</filename></emphasis> 540 <listitem><para><emphasis><filename>xorg-driver-abi:</filename></emphasis>
541 Checks that all packages containing Xorg drivers have ABI 541 Checks that all packages containing Xorg drivers have ABI
542 dependencies. 542 dependencies.
543 The <filename>xserver-xorg</filename> recipe provides driver 543 The <filename>xserver-xorg</filename> recipe provides driver
544 ABI names. 544 ABI names.
545 All drivers should depend on the ABI versions that they have 545 All drivers should depend on the ABI versions that they have
546 been built against. 546 been built against.
547 Driver recipes that include 547 Driver recipes that include
548 <filename>xorg-driver-input.inc</filename> 548 <filename>xorg-driver-input.inc</filename>
549 or <filename>xorg-driver-video.inc</filename> will 549 or <filename>xorg-driver-video.inc</filename> will
550 automatically get these versions. 550 automatically get these versions.
551 Consequently, you should only need to explicitly add 551 Consequently, you should only need to explicitly add
552 dependencies to binary driver recipes. 552 dependencies to binary driver recipes.
553 </para></listitem> 553 </para></listitem>
554 <listitem><para><emphasis><filename>libexec:</filename></emphasis> 554 <listitem><para><emphasis><filename>libexec:</filename></emphasis>
555 Checks if a package contains files in 555 Checks if a package contains files in
556 <filename>/usr/libexec</filename>. 556 <filename>/usr/libexec</filename>.
557 This check is not performed if the 557 This check is not performed if the
558 <filename>libexecdir</filename> variable has been set 558 <filename>libexecdir</filename> variable has been set
559 explicitly to <filename>/usr/libexec</filename>. 559 explicitly to <filename>/usr/libexec</filename>.
560 </para></listitem> 560 </para></listitem>
561 <listitem><para><emphasis><filename>staticdev:</filename></emphasis> 561 <listitem><para><emphasis><filename>staticdev:</filename></emphasis>
@@ -575,21 +575,21 @@
575 </itemizedlist> 575 </itemizedlist>
576 </para> 576 </para>
577 <note> 577 <note>
578 You can use the <filename>WARN_QA</filename> and 578 You can use the <filename>WARN_QA</filename> and
579 <filename>ERROR_QA</filename> variables to control the behavior of 579 <filename>ERROR_QA</filename> variables to control the behavior of
580 these checks at the global level (i.e. in your custom distro 580 these checks at the global level (i.e. in your custom distro
581 configuration). 581 configuration).
582 However, to skip one or more checks in recipes, you should use 582 However, to skip one or more checks in recipes, you should use
583 <link linkend='var-INSANE_SKIP'><filename>INSANE_SKIP</filename></link>. 583 <link linkend='var-INSANE_SKIP'><filename>INSANE_SKIP</filename></link>.
584 For example, to skip the check for symbolic link 584 For example, to skip the check for symbolic link
585 <filename>.so</filename> files in the main package of a recipe, 585 <filename>.so</filename> files in the main package of a recipe,
586 add the following to the recipe. 586 add the following to the recipe.
587 You need to realize that the package name override, in this example 587 You need to realize that the package name override, in this example
588 <filename>${PN}</filename>, must be used: 588 <filename>${PN}</filename>, must be used:
589 <literallayout class='monospaced'> 589 <literallayout class='monospaced'>
590 INSANE_SKIP_${PN} += "dev-so" 590 INSANE_SKIP_${PN} += "dev-so"
591 </literallayout> 591 </literallayout>
592 Please keep in mind that the QA checks exist in order to detect real 592 Please keep in mind that the QA checks exist in order to detect real
593 or potential problems in the packaged output. 593 or potential problems in the packaged output.
594 So exercise caution when disabling these checks. 594 So exercise caution when disabling these checks.
595 </note> 595 </note>
@@ -599,28 +599,28 @@
599 <title>Removing Work Files During the Build - <filename>rm_work.bbclass</filename></title> 599 <title>Removing Work Files During the Build - <filename>rm_work.bbclass</filename></title>
600 600
601 <para> 601 <para>
602 The OpenEmbedded build system can use a substantial amount of disk 602 The OpenEmbedded build system can use a substantial amount of disk
603 space during the build process. 603 space during the build process.
604 A portion of this space is the work files under the 604 A portion of this space is the work files under the
605 <filename>${TMPDIR}/work</filename> directory for each recipe. 605 <filename>${TMPDIR}/work</filename> directory for each recipe.
606 Once the build system generates the packages for a recipe, the work 606 Once the build system generates the packages for a recipe, the work
607 files for that recipe are no longer needed. 607 files for that recipe are no longer needed.
608 However, by default, the build system preserves these files 608 However, by default, the build system preserves these files
609 for inspection and possible debugging purposes. 609 for inspection and possible debugging purposes.
610 If you would rather have these files deleted to save disk space 610 If you would rather have these files deleted to save disk space
611 as the build progresses, you can enable <filename>rm_work</filename> 611 as the build progresses, you can enable <filename>rm_work</filename>
612 by adding the following to your <filename>local.conf</filename> file, 612 by adding the following to your <filename>local.conf</filename> file,
613 which is found in the 613 which is found in the
614 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. 614 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
615 <literallayout class='monospaced'> 615 <literallayout class='monospaced'>
616 INHERIT += "rm_work" 616 INHERIT += "rm_work"
617 </literallayout> 617 </literallayout>
618 If you are modifying and building source code out of the work directory 618 If you are modifying and building source code out of the work directory
619 for a recipe, enabling <filename>rm_work</filename> will potentially 619 for a recipe, enabling <filename>rm_work</filename> will potentially
620 result in your changes to the source being lost. 620 result in your changes to the source being lost.
621 To exclude some recipes from having their work directories deleted by 621 To exclude some recipes from having their work directories deleted by
622 <filename>rm_work</filename>, you can add the names of the recipe or 622 <filename>rm_work</filename>, you can add the names of the recipe or
623 recipes you are working on to the <filename>RM_WORK_EXCLUDE</filename> 623 recipes you are working on to the <filename>RM_WORK_EXCLUDE</filename>
624 variable, which can also be set in your <filename>local.conf</filename> 624 variable, which can also be set in your <filename>local.conf</filename>
625 file. 625 file.
626 Here is an example: 626 Here is an example:
@@ -677,28 +677,37 @@
677</section> 677</section>
678 678
679<section id='ref-classes-externalsrc'> 679<section id='ref-classes-externalsrc'>
680 <title>Using External Source - <filename>externalsrc.bbclass</filename></title> 680 <title><filename>externalsrc.bbclass</filename></title>
681 681
682 <para> 682 <para>
683 You can use this class to build software from source code that is external to the 683 You can use this class to build software from source code that is
684 OpenEmbedded build system. 684 external to the OpenEmbedded build system.
685 In other words, your source code resides in an external tree outside of the Yocto Project. 685 Building software from an external source tree means that the build
686 Building software from an external source tree means that the normal fetch, unpack, and 686 system's normal fetch, unpack, and patch process is not used.
687 patch process is not used.
688 </para> 687 </para>
689 688
690 <para> 689 <para>
691 To use the class, you need to define the 690 By default, the OpenEmbedded build system uses the
692 <link linkend='var-S'><filename>S</filename></link> variable to point to the directory that contains the source files. 691 <link linkend='var-S'><filename>S</filename></link> and
693 You also need to have your recipe inherit the <filename>externalsrc.bbclass</filename> class. 692 <link linkend='var-B'><filename>B</filename></link> variables to
693 locate unpacked recipe source code and to build it, respectively.
694 When your recipe inherits <filename>externalsrc.bbclass</filename>,
695 you use the
696 <link linkend='var-EXTERNALSRC'><filename>EXTERNALSRC</filename></link>
697 and
698 <link linkend='var-EXTERNALSRC_BUILD'><filename>EXTERNALSRC_BUILD</filename></link>
699 variables to ultimately define <filename>S</filename> and
700 <filename>B</filename>.
694 </para> 701 </para>
695 702
696 <para> 703 <para>
697 This class expects the source code to support recipe builds that use the 704 By default, this class expects the source code to support recipe builds
698 <link linkend='var-B'><filename>B</filename></link> variable to point to the directory in 705 that use the <link linkend='var-B'><filename>B</filename></link>
699 which the OpenEmbedded build system places the generated objects built from the recipes. 706 variable to point to the directory in which the OpenEmbedded build
700 By default, the <filename>B</filename> directory is set to the following, which is separate from the 707 system places the generated objects built from the recipes.
701 Source Directory (<filename>S</filename>): 708 By default, the <filename>B</filename> directory is set to the
709 following, which is separate from the source directory
710 (<filename>S</filename>):
702 <literallayout class='monospaced'> 711 <literallayout class='monospaced'>
703 ${WORKDIR}/${BPN}/{PV}/ 712 ${WORKDIR}/${BPN}/{PV}/
704 </literallayout> 713 </literallayout>
@@ -706,36 +715,17 @@
706 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>, 715 <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>,
707 <link linkend='var-BPN'><filename>BPN</filename></link>, 716 <link linkend='var-BPN'><filename>BPN</filename></link>,
708 <link linkend='var-PV'><filename>PV</filename></link>, 717 <link linkend='var-PV'><filename>PV</filename></link>,
709 <link linkend='var-S'><filename>S</filename></link>, and
710 <link linkend='var-B'><filename>B</filename></link> for more information.
711 </para> 718 </para>
712 719
713 <para> 720 <para>
714 You can build object files in the external tree by setting the 721 For more information on
715 <filename>B</filename> variable equal to <filename>"${S}"</filename>. 722 <filename>externalsrc.bbclass</filename>, see the comments in
716 However, this practice does not work well if you use the source for more than one variant 723 <filename>meta/classes/externalsrc.bbclass</filename> in the
717 (i.e., "natives" such as <filename>quilt-native</filename>, 724 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
718 or "crosses" such as <filename>gcc-cross</filename>). 725 For information on how to use <filename>externalsrc.bbclass</filename>,
719 So, be sure there are no "native", "cross", or "multilib" variants of the recipe. 726 see the
720 </para> 727 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building Software from an External Source</ulink>"
721 728 section in the Yocto Project Development Manual.
722 <para>
723 If you do want to build different variants of a recipe, you can use the
724 <link linkend='var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link> variable.
725 When you do, the <link linkend='var-B'><filename>B</filename></link> variable must support the
726 recipe's ability to build variants in different working directories.
727 Most Autotools-based recipes support separating these directories.
728 The OpenEmbedded build system defaults to using separate directories for <filename>gcc</filename>
729 and some kernel recipes.
730 Alternatively, you can make sure that separate recipes exist that each
731 use the <filename>BBCLASSEXTEND</filename> variable to build each variant.
732 The separate recipes can inherit a single target recipe.
733 </para>
734
735 <para>
736 For information on how to use this class, see the
737 "<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building
738 Software from an External Source</ulink>" section in the Yocto Project Development Manual.
739 </para> 729 </para>
740</section> 730</section>
741 731