summaryrefslogtreecommitdiffstats
path: root/documentation/poky-ref-manual/ref-variables.xml
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2011-09-28 09:11:01 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2011-10-04 14:01:39 +0100
commit66ddb69916b4b927918d0becb7de1a86460a292b (patch)
tree8627911a3396329db1ba0213cf850abca0ac4730 /documentation/poky-ref-manual/ref-variables.xml
parentde1dcde413d2b07ea9b3a8e7b5409f2a94f63847 (diff)
downloadpoky-66ddb69916b4b927918d0becb7de1a86460a292b.tar.gz
documentation/poky-ref-manual/ref-variables.xml: Variables updated
This is the second pass for re-documenting RDEPENDS, RRECOMMENDS, MACHINE_ESSENTIALS_EXTRA_RDEPENDS, MACHINE_ESSENTIALS_EXTRA_RRECOMMENDS, MACHINE_EXTRA_RDEPENDS, and MACHINE_EXTRA_RRECOMMENDS. These variables are in dire need of better explanations and examples. (From yocto-docs rev: cc60bd4c50c7b19209dae06307aec26e962cf476) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/poky-ref-manual/ref-variables.xml')
-rw-r--r--documentation/poky-ref-manual/ref-variables.xml175
1 files changed, 91 insertions, 84 deletions
diff --git a/documentation/poky-ref-manual/ref-variables.xml b/documentation/poky-ref-manual/ref-variables.xml
index 3e176f1963..15bbcee896 100644
--- a/documentation/poky-ref-manual/ref-variables.xml
+++ b/documentation/poky-ref-manual/ref-variables.xml
@@ -666,23 +666,27 @@
666 <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</glossterm> 666 <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</glossterm>
667 <glossdef> 667 <glossdef>
668 <para> 668 <para>
669 A list of packages that must be installed as part of the package being 669 A list of required packages to install as part of the package being
670 built in order for the 670 built.
671 resulting image to boot on the system. 671 The build process depends on these packages being present.
672 The machine depends on these items - without them it will not boot. 672 Furthermore, because this is a "machine essential" variable, the list of
673 If a package in this list cannot be found during the build, the build 673 packages are essential for the machine to boot.
674 will not complete. 674 The impact of this variable affects images based on <filename>task-core-boot</filename>,
675 Some examples of these machine essentials are flash, screen, keyboard, mouse, 675 including the <filename>core-image-minimal</filename> image.
676 or touchscreen drivers (depending on the machine). 676 </para>
677 <para>
678 This variable is similar to the
679 <link linkend='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</link>
680 variable with the exception that the package being built has a build
681 dependency on the variable's list of packages.
682 In other words, the image will not build if a file in this list is not found.
677 </para> 683 </para>
678 <para> 684 <para>
679 For example, suppose you are building a runtime package that depends 685 For example, suppose you are building a runtime package that depends
680 on a mouse driver. 686 on a certain disk driver.
681 In this case, you would use the following 687 In this case, you would use the following:
682 <filename>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</filename>
683 statement:
684 <literallayout class='monospaced'> 688 <literallayout class='monospaced'>
685 MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "&lt;mouse_driver&gt;" 689 MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "&lt;disk_driver&gt;"
686 </literallayout> 690 </literallayout>
687 </para> 691 </para>
688 </glossdef> 692 </glossdef>
@@ -691,38 +695,45 @@
691 <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</glossterm> 695 <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</glossterm>
692 <glossdef> 696 <glossdef>
693 <para> 697 <para>
694 A list of packages that must be installed as part of the package being 698 A list of recommended packages to install as part of the package being
695 built in order for the 699 built.
696 resulting image to boot on the system. 700 The build process does not depend on these packages being present.
697 The machine depends on these items - without them it will not boot. 701 Furthermore, because this is a "machine essential" variable, the list of
698 If a package in this list cannot be found during the build, the build 702 packages are essential for the machine to boot.
699 will not complete. 703 The impact of this variable affects images based on <filename>task-core-boot</filename>,
704 including the <filename>core-image-minimal</filename> image.
700 </para> 705 </para>
701 <para> 706 <para>
702 This variable is similar to the 707 This variable is similar to the
703 <link linkend='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</link> 708 <link linkend='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</link>
704 with the exception that the package being built does not have a build 709 variable with the exception that the package being built does not have a build
705 dependency on the variable's list of packages. 710 dependency on the variable's list of packages.
711 In other words, the image will build if a file in this list is not found.
712 However, because this is one of the "essential" variables, the resulting image
713 might not boot on the machine.
714 Or, if the machine does boot using the image, the machine might not be fully
715 functional.
706 </para> 716 </para>
707 <para> 717 <para>
708 Someone help me out here... How can this list be "recommended" yet part 718 Consider an example where you have a custom kernel with a disk driver
709 of the machine essential list? 719 built into the kernel itself, rather than using the driver built as a module.
710 Seems to me that anything that is machine essential pretty much needs to 720 If you include the package that has the driver module as part of
711 be there. 721 the variable's list, the
712 The rest of this section needs an appropriate example. 722 build process will not find that package.
723 However, because these packages are "recommends" packages, the build will
724 not fail due to the missing package.
725 Not accounting for any other problems, the custom kernel would still boot the machine.
713 </para> 726 </para>
714 <para> 727 <para>
715 Some examples of these machine essentials are flash, screen, keyboard, mouse, 728 Some example packages of these machine essentials are flash, screen, keyboard, mouse,
716 or touchscreen drivers (depending on the machine). 729 or touchscreen drivers (depending on the machine).
717 </para> 730 </para>
718 <para> 731 <para>
719 For example, suppose you are building a runtime package that depends 732 For example, suppose you are building a runtime package that depends
720 on a mouse driver. 733 on a mouse driver.
721 In this case, you would use the following 734 In this case, you would use the following:
722 <filename>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</filename>
723 statement:
724 <literallayout class='monospaced'> 735 <literallayout class='monospaced'>
725 MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "&lt;mouse_driver&gt;" 736 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "&lt;mouse_driver&gt;"
726 </literallayout> 737 </literallayout>
727 </para> 738 </para>
728 </glossdef> 739 </glossdef>
@@ -731,30 +742,32 @@
731 <glossentry id='var-MACHINE_EXTRA_RDEPENDS'><glossterm>MACHINE_EXTRA_RDEPENDS</glossterm> 742 <glossentry id='var-MACHINE_EXTRA_RDEPENDS'><glossterm>MACHINE_EXTRA_RDEPENDS</glossterm>
732 <glossdef> 743 <glossdef>
733 <para> 744 <para>
734 A list of packages that should be installed as part of the package 745 A list of optional but non-machine essential packages to install as
735 being built in order for the 746 part of the package being built.
736 resulting image to boot on the system and achieve full functionality. 747 Even though these packages are not essential for the machine to boot,
737 Although the machine does not need these items in order to boot, if you want the 748 the build process depends on them being present.
738 extra functionality they provide the package being built depends on them 749 The impact of this variable affects all images based on
739 being there. 750 <filename>task-base</filename>, which does not include the
740 If a package in this list cannot be found during the build, the build 751 <filename>core-image-minimal</filename> or <filename>core-image-basic</filename>
741 will not complete. 752 images.
742 </para> 753 </para>
743 <para> 754 <para>
744 I need a real-world example here.... 755 This variable is similar to the
745 </para> 756 <link linkend='var-MACHINE_EXTRA_RRECOMMENDS'>MACHINE_EXTRA_RRECOMMENDS</link>
746 <para> 757 variable with the exception that the package being built has a build
747 An example of a machine extra is a WiFi driver. 758 dependency on the variable's list of packages.
748 The machine may or may not have a WiFi card. 759 In other words, the image will not build if a file in this list is not found.
749 If it does, the package with the driver needs to be present for the card to work.
750 However, if the machine does not have a WiFi card, the machine will still boot.
751 </para> 760 </para>
752 <para> 761 <para>
753 For example, suppose you are building a runtime package that depends 762 An example is a machine that might or might not have a WiFi card.
754 on a WiFi driver. 763 The package containing the WiFi support is not essential for the
755 In this case, you would use the following 764 machine to boot the image.
756 <filename>MACHINE_EXTRA_RDEPENDS</filename> 765 If it is not there, the machine will boot but not be able to use the
757 statement: 766 WiFi functionality.
767 However, if you include the package with the WiFi support as part of the
768 variable's package list, the build
769 process depends on finding the package.
770 In this case, you would use the following:
758 <literallayout class='monospaced'> 771 <literallayout class='monospaced'>
759 MACHINE_EXTRA_RDEPENDS += "&lt;wifi_driver&gt;" 772 MACHINE_EXTRA_RDEPENDS += "&lt;wifi_driver&gt;"
760 </literallayout> 773 </literallayout>
@@ -765,38 +778,35 @@
765 <glossentry id='var-MACHINE_EXTRA_RRECOMMENDS'><glossterm>MACHINE_EXTRA_RRECOMMENDS</glossterm> 778 <glossentry id='var-MACHINE_EXTRA_RRECOMMENDS'><glossterm>MACHINE_EXTRA_RRECOMMENDS</glossterm>
766 <glossdef> 779 <glossdef>
767 <para> 780 <para>
768 A list of packages that should be installed as part of the package 781 A list of optional but non-machine essential packages to install as
769 being built in order for the 782 part of the package being built.
770 machine to boot and achieve full functionality. 783 The package being built has no build dependency on the list of packages
771 Although the machine does not need these items in order to boot, if you want the 784 with this variable.
772 extra functionality they provide the package being built should include 785 The impact of this variable affects only images based on
773 them. 786 <filename>task-base</filename>, which does not include the
787 <filename>core-image-minimal</filename> or <filename>core-image-basic</filename>
788 images.
774 </para> 789 </para>
775 <para> 790 <para>
776 This variable is similar to the 791 This variable is similar to the
777 <link linkend='var-MACHINE_EXTRA_RDEPENDS'>MACHINE_EXTRA_RDEPENDS</link> 792 <link linkend='var-MACHINE_EXTRA_RDEPENDS'>MACHINE_EXTRA_RDEPENDS</link>
778 with the exception that the package being built does not have a build 793 variable with the exception that the package being built does not have a build
779 dependency on the variable's list of packages. 794 dependency on the variable's list of packages.
780 If a package in this list cannot be found during the build, the build 795 In other words, the image will build if a file in this list is not found.
781 will still continue.
782 </para> 796 </para>
783 <para> 797 <para>
784 I need a real-world example to use here please.... 798 An example is a machine that might or might not have a WiFi card.
785 </para> 799 The package containing the WiFi support is not essential for the
786 <para> 800 machine to boot the image.
787 An example of a machine extra is a WiFi driver. 801 If it is not there, the machine will boot but not be able to use the
788 The machine may or may not have a WiFi card. 802 WiFi functionality.
789 If it does, the package with the driver needs to be present for the card to work. 803 You are free to either include or not include the
790 However, if the machine does not have a WiFi card, the machine will still boot. 804 the package with the WiFi support as part of the
791 </para> 805 variable's package list, the build
792 <para> 806 process does not depend on finding the package.
793 For example, suppose you are building a runtime package that depends 807 If you include the package, you would use the following:
794 on a WiFi driver.
795 In this case, you would use the following
796 <filename>MACHINE_EXTRA_RDEPENDS</filename>
797 statement:
798 <literallayout class='monospaced'> 808 <literallayout class='monospaced'>
799 MACHINE_EXTRA_RDEPENDS += "&lt;wifi_driver&gt;" 809 MACHINE_EXTRA_RRECOMMENDS += "&lt;wifi_driver&gt;"
800 </literallayout> 810 </literallayout>
801 </para> 811 </para>
802 </glossdef> 812 </glossdef>
@@ -1015,9 +1025,9 @@
1015 <glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm> 1025 <glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm>
1016 <glossdef> 1026 <glossdef>
1017 <para> 1027 <para>
1018 A list of packages that must be installed alongside a package being 1028 A list of packages that must be installed as part of a package being built.
1019 built because the package being build has runtime dependencies on 1029 The package being built has a runtime dependency on the packages in the
1020 them. 1030 variable's list.
1021 In other words, in order for the package being built to run correctly, 1031 In other words, in order for the package being built to run correctly,
1022 it depends on these listed packages. 1032 it depends on these listed packages.
1023 If a package in this list cannot be found during the build, the build 1033 If a package in this list cannot be found during the build, the build
@@ -1072,13 +1082,13 @@
1072 A list of packages that extend the usability of a package being 1082 A list of packages that extend the usability of a package being
1073 built. 1083 built.
1074 The package being built does not depend on this list of packages in 1084 The package being built does not depend on this list of packages in
1075 order to successfully built, but needs them for the extended usability. 1085 order to successfully build, but needs them for the extended usability.
1076 To specify runtime dependencies for packages, see the 1086 To specify runtime dependencies for packages, see the
1077 <link linkend='var-RDEPENDS'>RDEPENDS</link> variable. 1087 <link linkend='var-RDEPENDS'>RDEPENDS</link> variable.
1078 </para> 1088 </para>
1079 <para> 1089 <para>
1080 The Yocto Project build process automatically installs the list of packages 1090 The Yocto Project build process automatically installs the list of packages
1081 as part of the build package. 1091 as part of the built package.
1082 However, you can remove them later if you want. 1092 However, you can remove them later if you want.
1083 If, during the build, a package from the list cannot be found, the build 1093 If, during the build, a package from the list cannot be found, the build
1084 process continues without an error. 1094 process continues without an error.
@@ -1090,8 +1100,7 @@
1090 whose usability is being extended. 1100 whose usability is being extended.
1091 For example, suppose you are building a development package that is extended 1101 For example, suppose you are building a development package that is extended
1092 to support wireless functionality. 1102 to support wireless functionality.
1093 In this case, you would use the following <filename>RRECOMMENDS</filename> 1103 In this case, you would use the following:
1094 statement:
1095 <literallayout class='monospaced'> 1104 <literallayout class='monospaced'>
1096 RRECOMMENDS_${PN}-dev += "&lt;wireless_package_name&gt;" 1105 RRECOMMENDS_${PN}-dev += "&lt;wireless_package_name&gt;"
1097 </literallayout> 1106 </literallayout>
@@ -1099,8 +1108,6 @@
1099 appear as it would in the 1108 appear as it would in the
1100 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename> namespace before any 1109 <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename> namespace before any
1101 renaming of the output package by classes like <filename>debian.bbclass</filename>. 1110 renaming of the output package by classes like <filename>debian.bbclass</filename>.
1102 Also, you would provide the actual name of the package that supports the wireless
1103 capabilities.
1104 </para> 1111 </para>
1105 </glossdef> 1112 </glossdef>
1106 </glossentry> 1113 </glossentry>