summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--documentation/ref-manual/ref-classes.xml286
1 files changed, 271 insertions, 15 deletions
diff --git a/documentation/ref-manual/ref-classes.xml b/documentation/ref-manual/ref-classes.xml
index 30d0e5de06..daedf8becc 100644
--- a/documentation/ref-manual/ref-classes.xml
+++ b/documentation/ref-manual/ref-classes.xml
@@ -111,7 +111,9 @@
111 <para> 111 <para>
112 The <filename>autoconf</filename>, <filename>automake</filename>, 112 The <filename>autoconf</filename>, <filename>automake</filename>,
113 and <filename>libtool</filename> bring standardization. 113 and <filename>libtool</filename> bring standardization.
114 This class defines a set of tasks (configure, compile etc.) that 114 This class defines a set of tasks (e.g.
115 <filename>configure</filename>, <filename>compile</filename> and
116 so forth) that
115 work for all Autotooled packages. 117 work for all Autotooled packages.
116 It should usually be enough to define a few standard variables 118 It should usually be enough to define a few standard variables
117 and then simply <filename>inherit autotools</filename>. 119 and then simply <filename>inherit autotools</filename>.
@@ -133,8 +135,8 @@
133 </para> 135 </para>
134 136
135 <para> 137 <para>
136 It's useful to have some idea of how the tasks defined by this class work 138 It's useful to have some idea of how the tasks defined by this class
137 and what they do behind the scenes. 139 work and what they do behind the scenes.
138 <itemizedlist> 140 <itemizedlist>
139 <listitem><para><link linkend='ref-tasks-configure'><filename>do_configure</filename></link> - 141 <listitem><para><link linkend='ref-tasks-configure'><filename>do_configure</filename></link> -
140 Regenerates the 142 Regenerates the
@@ -157,6 +159,68 @@
157 </para> 159 </para>
158</section> 160</section>
159 161
162<section id='ref-classes-autotools-stage'>
163 <title><filename>autotools_stage.bbclass</filename></title>
164
165 <para>
166 The <filename>autotools_stage</filename> class supports Autotooled
167 packages.
168 </para>
169
170 <para>
171 The <filename>autoconf</filename>,
172 <filename>automake</filename>, and <filename>libtool</filename>
173 bring standardization.
174 This class defines a set of tasks
175 (e.g. <filename>configure</filename>, <filename>compile</filename>
176 and so forth) that work for all Autotooled packages.
177 It is usually enough to define a few standard variables and then
178 simply inherit <filename>autotools</filename>.
179 This class can also work with software that emulates Autotools.
180 For more information, see the
181 "<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-autotooled-package'>Autotooled Package</ulink>"
182 section in the Yocto Project Development Manual.
183 </para>
184
185 <para>
186 By default, the <filename>autotools-stage</filename> class uses
187 out-of-tree builds
188 (<link linkend='var-B'><filename>B</filename></link> <filename>!=</filename>
189 <link linkend='var-S'><filename>S</filename></link>).
190 If the software being built by a recipe does not support
191 using out-of-tree builds, you should have the recipe inherit the
192 <link linkend='ref-classes-autotools-brokensep'><filename>autotools-brokensep</filename></link>
193 class.
194 </para>
195
196 <para>
197 It is useful to have some idea of how the tasks defined by this
198 class work and what they do behind the scenes.
199 <itemizedlist>
200 <listitem><para><link linkend='ref-tasks-configure'><filename>do_configure</filename></link> -
201 Regenerates the configure script (using
202 <filename>autoreconf</filename>) and then launches it
203 with a standard set of arguments used during cross-compilation.
204 You can pass additional parameters to
205 <filename>configure</filename> through the
206 <filename><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link></filename> variable.
207 </para></listitem>
208 <listitem><para><link linkend='ref-tasks-compile'><filename>do_compile</filename></link> -
209 Runs <filename>make</filename> with arguments that specify
210 the compiler and linker.
211 You can pass additional arguments through the
212 <filename><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></filename>
213 variable.
214 </para></listitem>
215 <listitem><para><link linkend='ref-tasks-install'><filename>do_install</filename></link> -
216 Runs <filename>make install</filename> and passes in
217 <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename>
218 as <filename>DESTDIR</filename>.
219 </para></listitem>
220 </itemizedlist>
221 </para>
222</section>
223
160<section id='ref-classes-autotools-brokensep'> 224<section id='ref-classes-autotools-brokensep'>
161 <title><filename>autotools-brokensep.bbclass</filename></title> 225 <title><filename>autotools-brokensep.bbclass</filename></title>
162 226
@@ -560,10 +624,10 @@
560</section> 624</section>
561 625
562<section id='ref-classes-cpan'> 626<section id='ref-classes-cpan'>
563 <title><filename>cpan.bbclass</filename></title> 627 <title><filename>cpan*.bbclass</filename></title>
564 628
565 <para> 629 <para>
566 The <filename>cpan</filename> class supports Perl modules. 630 The <filename>cpan*</filename> classes support Perl modules.
567 </para> 631 </para>
568 632
569 <para> 633 <para>
@@ -582,6 +646,8 @@
582 using <filename>cpan_build.bbclass</filename> in their recipes. 646 using <filename>cpan_build.bbclass</filename> in their recipes.
583 </para></listitem> 647 </para></listitem>
584 </itemizedlist> 648 </itemizedlist>
649 Both build methods inherit the <filename>cpan-base</filename> class
650 for basic Perl support.
585 </para> 651 </para>
586</section> 652</section>
587 653
@@ -725,10 +791,10 @@
725</section> 791</section>
726 792
727<section id='ref-classes-distutils'> 793<section id='ref-classes-distutils'>
728 <title><filename>distutils.bbclass</filename></title> 794 <title><filename>distutils-*.bbclass</filename></title>
729 795
730 <para> 796 <para>
731 The <filename>distutils</filename> class supports recipes for Python 797 The <filename>distutils-*</filename> classes support recipes for Python
732 version 2.x extensions, which are simple. 798 version 2.x extensions, which are simple.
733 These recipes usually only need to point to the source's archive and 799 These recipes usually only need to point to the source's archive and
734 then inherit the proper class. 800 then inherit the proper class.
@@ -736,12 +802,12 @@
736 module authors used. 802 module authors used.
737 <itemizedlist> 803 <itemizedlist>
738 <listitem><para>Extensions that use an Autotools-based build system 804 <listitem><para>Extensions that use an Autotools-based build system
739 require Autotools and 805 require Autotools and the classes based on
740 <filename>distutils</filename>-based classes in their recipes. 806 <filename>distutils</filename> in their recipes.
741 </para></listitem> 807 </para></listitem>
742 <listitem><para>Extensions that use build systems based on 808 <listitem><para>Extensions that use build systems based on
743 <filename>distutils</filename> require 809 <filename>distutils</filename> require
744 the <filename>distutils</filename> class in their recipes. 810 the <filename>distutils-*</filename> classes in their recipes.
745 </para></listitem> 811 </para></listitem>
746 <listitem><para>Extensions that use build systems based on 812 <listitem><para>Extensions that use build systems based on
747 <filename>setuptools</filename> require the 813 <filename>setuptools</filename> require the
@@ -749,18 +815,23 @@
749 class in their recipes. 815 class in their recipes.
750 </para></listitem> 816 </para></listitem>
751 </itemizedlist> 817 </itemizedlist>
818 The <filename>distutils-common-base</filename> class is required by
819 some of the <filename>distutils-*</filename> classes to provide common
820 Python2 support.
821 The <filename>distutils-tools</filename> class supports recipes for
822 additional "distutils" tools.
752 </para> 823 </para>
753</section> 824</section>
754 825
755<section id='ref-classes-distutils3'> 826<section id='ref-classes-distutils3'>
756 <title><filename>distutils3.bbclass</filename></title> 827 <title><filename>distutils3*.bbclass</filename></title>
757 828
758 <para> 829 <para>
759 The <filename>distutils3</filename> class supports recipes for Python 830 The <filename>distutils3</filename> class supports recipes for Python
760 version 3.x extensions, which are simple. 831 version 3.x extensions, which are simple.
761 These recipes usually only need to point to the source's archive and 832 These recipes usually only need to point to the source's archive and
762 then inherit the proper class. 833 then inherit the proper class.
763 Building is split into two methods depending on which method the 834 Building is split into three methods depending on which method the
764 module authors used. 835 module authors used.
765 <itemizedlist> 836 <itemizedlist>
766 <listitem><para>Extensions that use an Autotools-based build system 837 <listitem><para>Extensions that use an Autotools-based build system
@@ -777,6 +848,14 @@
777 class in their recipes. 848 class in their recipes.
778 </para></listitem> 849 </para></listitem>
779 </itemizedlist> 850 </itemizedlist>
851 The <filename>distutils3*</filename> classes either inherit their
852 corresponding <filename>distutils*</filename> class or replicate them
853 using a Python3 version instead (e.g.
854 <filename>distutils3-base</filename> inherits
855 <filename>distutils-common-base</filename>, which is the same as
856 <filename>distutils-base</filename> but inherits
857 <filename>python3native</filename> instead of
858 <filename>pythonnative</filename>).
780 </para> 859 </para>
781</section> 860</section>
782 861
@@ -908,6 +987,19 @@
908 </para> 987 </para>
909</section> 988</section>
910 989
990<section id='ref-classes-fs-uuid'>
991 <title><filename>fs-uuid.bbclass</filename></title>
992
993 <para>
994 The <filename>fs-uuid</filename> class extracts UUID from
995 <filename>${</filename><link linkend='var-ROOTFS'><filename>ROOTFS</filename></link><filename>}</filename>,
996 which must have been built by the time that this function gets called.
997 The <filename>fs-uuid</filename> class only works on
998 <filename>ext</filename> file systems and depends on
999 <filename>tune2fs</filename>.
1000 </para>
1001</section>
1002
911<section id='ref-classes-gconf'> 1003<section id='ref-classes-gconf'>
912 <title><filename>gconf.bbclass</filename></title> 1004 <title><filename>gconf.bbclass</filename></title>
913 1005
@@ -1258,6 +1350,15 @@
1258 </para> 1350 </para>
1259</section> 1351</section>
1260 1352
1353<section id='ref-classes-image-buildinfo'>
1354 <title><filename>image-buildinfo.bbclass</filename></title>
1355
1356 <para>
1357 The <filename>image-buildinfo</filename> class writes information
1358 to the target filesystem on <filename>/etc/build</filename>.
1359 </para>
1360</section>
1361
1261<section id='ref-classes-image_types'> 1362<section id='ref-classes-image_types'>
1262 <title><filename>image_types.bbclass</filename></title> 1363 <title><filename>image_types.bbclass</filename></title>
1263 1364
@@ -1371,6 +1472,15 @@
1371 </para> 1472 </para>
1372</section> 1473</section>
1373 1474
1475<section id='ref-classes-image-vm'>
1476 <title><filename>image-vm.bbclass</filename></title>
1477
1478 <para>
1479 The <filename>image-vm</filename> class supports building VM
1480 images.
1481 </para>
1482</section>
1483
1374<section id='ref-classes-image-vmdk'> 1484<section id='ref-classes-image-vmdk'>
1375 <title><filename>image-vmdk.bbclass</filename></title> 1485 <title><filename>image-vmdk.bbclass</filename></title>
1376 1486
@@ -1871,6 +1981,25 @@
1871 </para> 1981 </para>
1872</section> 1982</section>
1873 1983
1984<section id='ref-classes-kernel-fitimage'>
1985 <title><filename>kernel-fitimage.bbclass</filename></title>
1986
1987 <para>
1988 The <filename>kernel-fitimage</filename> class provides support to
1989 pack zImages.
1990 </para>
1991</section>
1992
1993<section id='ref-classes-kernel-grub'>
1994 <title><filename>kernel-grub.bbclass</filename></title>
1995
1996 <para>
1997 The <filename>kernel-grub</filename> class updates the boot area and
1998 the boot menu with the kernel as the priority boot mechanism while
1999 installing a RPM to update the kernel on a deployed target.
2000 </para>
2001</section>
2002
1874<section id='ref-classes-kernel-module-split'> 2003<section id='ref-classes-kernel-module-split'>
1875 <title><filename>kernel-module-split.bbclass</filename></title> 2004 <title><filename>kernel-module-split.bbclass</filename></title>
1876 2005
@@ -1881,6 +2010,24 @@
1881 </para> 2010 </para>
1882</section> 2011</section>
1883 2012
2013<section id='ref-classes-kernel-uboot'>
2014 <title><filename>kernel-uboot.bbclass</filename></title>
2015
2016 <para>
2017 The <filename>kernel-uboot</filename> class provides support for
2018 building from vmlinux-style kernel sources.
2019 </para>
2020</section>
2021
2022<section id='ref-classes-kernel-uimage'>
2023 <title><filename>kernel-uimage.bbclass</filename></title>
2024
2025 <para>
2026 The <filename>kernel-uimage</filename> class provides support to
2027 pack uImage.
2028 </para>
2029</section>
2030
1884<section id='ref-classes-kernel-yocto'> 2031<section id='ref-classes-kernel-yocto'>
1885 <title><filename>kernel-yocto.bbclass</filename></title> 2032 <title><filename>kernel-yocto.bbclass</filename></title>
1886 2033
@@ -1891,6 +2038,15 @@
1891 </para> 2038 </para>
1892</section> 2039</section>
1893 2040
2041<section id='ref-classes-kernelsrc'>
2042 <title><filename>kernelsrc.bbclass</filename></title>
2043
2044 <para>
2045 The <filename>kernelsrc</filename> class sets the Linux kernel
2046 source and version.
2047 </para>
2048</section>
2049
1894<section id='ref-classes-lib_package'> 2050<section id='ref-classes-lib_package'>
1895 <title><filename>lib_package.bbclass</filename></title> 2051 <title><filename>lib_package.bbclass</filename></title>
1896 2052
@@ -1905,6 +2061,25 @@
1905 </para> 2061 </para>
1906</section> 2062</section>
1907 2063
2064<section id='ref-classes-libc*'>
2065 <title><filename>libc*.bbclass</filename></title>
2066
2067 <para>
2068 The <filename>libc*</filename> classes support recipes that build
2069 packages with <filename>libc</filename>:
2070 <itemizedlist>
2071 <listitem><para>The <filename>libc-common</filename> class
2072 provides common support for building with
2073 <filename>libc</filename>.
2074 </para></listitem>
2075 <listitem><para>The <filename>libc-package</filename> class
2076 supports packaging up <filename>glibc</filename> and
2077 <filename>eglibc</filename>.
2078 </para></listitem>
2079 </itemizedlist>
2080 </para>
2081</section>
2082
1908<section id='ref-classes-license'> 2083<section id='ref-classes-license'>
1909 <title><filename>license.bbclass</filename></title> 2084 <title><filename>license.bbclass</filename></title>
1910 2085
@@ -1984,6 +2159,15 @@
1984 </para> 2159 </para>
1985</section> 2160</section>
1986 2161
2162<section id='ref-classes-migrate_localcount'>
2163 <title><filename>migrate_localcount.bbclass</filename></title>
2164
2165 <para>
2166 The <filename>migrate_localcount</filename> class verifies a recipe's
2167 localcount data and increments it appropriately.
2168 </para>
2169</section>
2170
1987<section id='ref-classes-mime'> 2171<section id='ref-classes-mime'>
1988 <title><filename>mime.bbclass</filename></title> 2172 <title><filename>mime.bbclass</filename></title>
1989 2173
@@ -2549,6 +2733,9 @@
2549 Supports creation of the SDK given the opkg (IPK format) 2733 Supports creation of the SDK given the opkg (IPK format)
2550 package manager. 2734 package manager.
2551 </para></listitem> 2735 </para></listitem>
2736 <listitem><para><emphasis><filename>populate_sdk_ext</filename>:</emphasis>
2737 Supports extensible SDK creation under all package managers.
2738 </para></listitem>
2552 </itemizedlist> 2739 </itemizedlist>
2553 </para> 2740 </para>
2554 2741
@@ -2705,6 +2892,16 @@
2705 </para> 2892 </para>
2706</section> 2893</section>
2707 2894
2895<section id='ref-classes-python3native'>
2896 <title><filename>python3native.bbclass</filename></title>
2897
2898 <para>
2899 The <filename>python3native</filename> class supports using the
2900 native version of Python 3 built by the build system rather than
2901 support of the version provided by the build host.
2902 </para>
2903</section>
2904
2708<section id='ref-classes-pythonnative'> 2905<section id='ref-classes-pythonnative'>
2709 <title><filename>pythonnative.bbclass</filename></title> 2906 <title><filename>pythonnative.bbclass</filename></title>
2710 2907
@@ -2786,6 +2983,16 @@
2786 </para> 2983 </para>
2787</section> 2984</section>
2788 2985
2986<section id='ref-classes-recipe_sanity'>
2987 <title><filename>recipe_sanity.bbclass</filename></title>
2988
2989 <para>
2990 The <filename>recipe_sanity</filename> class checks for the presence
2991 of any host system recipe prerequisites that might affect the
2992 build (e.g. variables that are set or software that is present).
2993 </para>
2994</section>
2995
2789<section id='ref-classes-relocatable'> 2996<section id='ref-classes-relocatable'>
2790 <title><filename>relocatable.bbclass</filename></title> 2997 <title><filename>relocatable.bbclass</filename></title>
2791 2998
@@ -2961,6 +3168,16 @@
2961 </para> 3168 </para>
2962</section> 3169</section>
2963 3170
3171<section id='ref-classes-sign_rpm'>
3172 <title><filename>sign_rpm.bbclass</filename></title>
3173
3174 <para>
3175 The <filename>sign_rpm</filename> class
3176 The <filename>sign_rpm</filename> class supports generating signed
3177 RPM packages.
3178 </para>
3179</section>
3180
2964<section id='ref-classes-sip'> 3181<section id='ref-classes-sip'>
2965 <title><filename>sip.bbclass</filename></title> 3182 <title><filename>sip.bbclass</filename></title>
2966 3183
@@ -3219,6 +3436,40 @@
3219 </para> 3436 </para>
3220</section> 3437</section>
3221 3438
3439<section id='ref-classes-testimage*'>
3440 <title><filename>testimage*.bbclass</filename></title>
3441
3442 <para>
3443 The <filename>testimage*</filename> classes support running
3444 automated tests against images using QEMU and on actual hardware.
3445 The classes handle loading the tests and starting the image.
3446 To use the classes, you need to perform steps to set up the
3447 environment.
3448 </para>
3449
3450 <para>
3451 The tests are commands that run on the target system over
3452 <filename>ssh</filename>.
3453 Each test is written in Python and makes use of the
3454 <filename>unittest</filename> module.
3455 </para>
3456
3457 <para>
3458 The <filename>testimage.bbclass</filename> runs tests on an image
3459 when called using the following:
3460 <literallayout class='monospaced'>
3461 $ bitbake -c testimage <replaceable>image</replaceable>
3462 </literallayout>
3463 Tests run automatically on an image after the image is constructed
3464 (i.e.
3465 <link linkend='var-TEST_IMAGE'><filename>TEST_IMAGE</filename></link>
3466 must be set to "1").
3467 For information on how to enable, run, and create new tests, see the
3468 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
3469 section in the Yocto Project Development Manual.
3470 </para>
3471</section>
3472
3222<section id='ref-classes-texinfo'> 3473<section id='ref-classes-texinfo'>
3223 <title><filename>texinfo.bbclass</filename></title> 3474 <title><filename>texinfo.bbclass</filename></title>
3224 3475
@@ -3398,10 +3649,10 @@
3398</section> 3649</section>
3399 3650
3400<section id='ref-classes-useradd'> 3651<section id='ref-classes-useradd'>
3401 <title><filename>useradd.bbclass</filename></title> 3652 <title><filename>useradd*.bbclass</filename></title>
3402 3653
3403 <para> 3654 <para>
3404 The <filename>useradd</filename> class supports the addition of users 3655 The <filename>useradd*</filename> classes support the addition of users
3405 or groups for usage by the package on the target. 3656 or groups for usage by the package on the target.
3406 For example, if you have packages that contain system services that 3657 For example, if you have packages that contain system services that
3407 should be run under their own user or group, you can use this class to 3658 should be run under their own user or group, you can use this class to
@@ -3415,7 +3666,12 @@
3415 </para> 3666 </para>
3416 3667
3417 <para> 3668 <para>
3418 The <filename>useradd</filename> class supports the 3669 The <filename>useradd_base</filename> class provides basic
3670 functionality for user or groups settings.
3671 </para>
3672
3673 <para>
3674 The <filename>useradd*</filename> classes support the
3419 <link linkend='var-USERADD_PACKAGES'><filename>USERADD_PACKAGES</filename></link>, 3675 <link linkend='var-USERADD_PACKAGES'><filename>USERADD_PACKAGES</filename></link>,
3420 <link linkend='var-USERADD_PARAM'><filename>USERADD_PARAM</filename></link>, 3676 <link linkend='var-USERADD_PARAM'><filename>USERADD_PARAM</filename></link>,
3421 <link linkend='var-GROUPADD_PARAM'><filename>GROUPADD_PARAM</filename></link>, 3677 <link linkend='var-GROUPADD_PARAM'><filename>GROUPADD_PARAM</filename></link>,