summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/ref-classes.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/ref-manual/ref-classes.xml')
-rw-r--r--documentation/ref-manual/ref-classes.xml183
1 files changed, 49 insertions, 134 deletions
diff --git a/documentation/ref-manual/ref-classes.xml b/documentation/ref-manual/ref-classes.xml
index 647c67f2ba..1b7ab94801 100644
--- a/documentation/ref-manual/ref-classes.xml
+++ b/documentation/ref-manual/ref-classes.xml
@@ -101,116 +101,73 @@
101</section> 101</section>
102 102
103<section id='ref-classes-autotools'> 103<section id='ref-classes-autotools'>
104 <title><filename>autotools.bbclass</filename></title> 104 <title><filename>autotools*.bbclass</filename></title>
105 105
106 <para> 106 <para>
107 The <filename>autotools</filename> class supports Autotooled 107 The <filename>autotools*</filename> classes support Autotooled
108 packages. 108 packages.
109 </para> 109 </para>
110 110
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> packages bring standardization.
114 This class defines a set of tasks (e.g. 114 This class defines a set of tasks (e.g.
115 <filename>configure</filename>, <filename>compile</filename> and 115 <filename>configure</filename>, <filename>compile</filename> and
116 so forth) that 116 so forth) that
117 work for all Autotooled packages. 117 work for all Autotooled packages.
118 It should usually be enough to define a few standard variables 118 It should usually be enough to define a few standard variables
119 and then simply <filename>inherit autotools</filename>. 119 and then simply <filename>inherit autotools</filename>.
120 This class can also work with software that emulates Autotools. 120 These classes can also work with software that emulates Autotools.
121 For more information, see the 121 For more information, see the
122 "<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-autotooled-package'>Autotooled Package</ulink>" 122 "<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-autotooled-package'>Autotooled Package</ulink>"
123 section in the Yocto Project Development Manual. 123 section in the Yocto Project Development Manual.
124 </para> 124 </para>
125 125
126 <para> 126 <para>
127 By default, the <filename>autotools</filename> class 127 By default, the <filename>autotools*</filename> classes
128 uses out-of-tree builds 128 use out-of-tree builds (i.e.
129 <filename>autotools.bbclass</filename> and
130 <filename>autotools_stage.bbclass</filename>).
129 (<link linkend='var-B'><filename>B</filename></link> <filename>!=</filename> 131 (<link linkend='var-B'><filename>B</filename></link> <filename>!=</filename>
130 <link linkend='var-S'><filename>S</filename></link>). 132 <link linkend='var-S'><filename>S</filename></link>).
131 If the software being built by a recipe does not support
132 using out-of-tree builds, you should have the recipe inherit the
133 <link linkend='ref-classes-autotools-brokensep'><filename>autotools-brokensep</filename></link>
134 class.
135 </para>
136
137 <para>
138 It's useful to have some idea of how the tasks defined by this class
139 work and what they do behind the scenes.
140 <itemizedlist>
141 <listitem><para><link linkend='ref-tasks-configure'><filename>do_configure</filename></link> -
142 Regenerates the
143 configure script (using <filename>autoreconf</filename>) and then launches it
144 with a standard set of arguments used during cross-compilation.
145 You can pass additional parameters to <filename>configure</filename> through the
146 <filename><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link></filename> variable.
147 </para></listitem>
148 <listitem><para><link linkend='ref-tasks-compile'><filename>do_compile</filename></link> - Runs <filename>make</filename> with
149 arguments that specify the compiler and linker.
150 You can pass additional arguments through
151 the <filename><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></filename> variable.
152 </para></listitem>
153 <listitem><para><link linkend='ref-tasks-install'><filename>do_install</filename></link> - Runs <filename>make install</filename>
154 and passes in
155 <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename>
156 as <filename>DESTDIR</filename>.
157 </para></listitem>
158 </itemizedlist>
159 </para>
160</section>
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> 133 </para>
169 134
170 <para> 135 <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 136 If the software being built by a recipe does not support
191 using out-of-tree builds, you should have the recipe inherit the 137 using out-of-tree builds, you should have the recipe inherit the
192 <link linkend='ref-classes-autotools-brokensep'><filename>autotools-brokensep</filename></link> 138 <filename>autotools-brokensep</filename> class.
193 class. 139 The <filename>autotools-brokensep</filename> class behaves the same
140 as the <filename>autotools</filename> and
141 <filename>autotools_stage</filename> classes but builds with
142 <link linkend='var-B'><filename>B</filename></link> ==
143 <link linkend='var-S'><filename>S</filename></link>.
144 This method is useful when out-of-tree build support is either not
145 present or is broken.
146 <note>
147 It is recommended that out-of-tree support be fixed and used
148 if at all possible.
149 </note>
194 </para> 150 </para>
195 151
196 <para> 152 <para>
197 It is useful to have some idea of how the tasks defined by this 153 It's useful to have some idea of how the tasks defined by
198 class work and what they do behind the scenes. 154 the <filename>autotools*</filename> classes work and what they do
155 behind the scenes.
199 <itemizedlist> 156 <itemizedlist>
200 <listitem><para><link linkend='ref-tasks-configure'><filename>do_configure</filename></link> - 157 <listitem><para><link linkend='ref-tasks-configure'><filename>do_configure</filename></link> -
201 Regenerates the configure script (using 158 Regenerates the
202 <filename>autoreconf</filename>) and then launches it 159 configure script (using <filename>autoreconf</filename>) and
203 with a standard set of arguments used during cross-compilation. 160 then launches it with a standard set of arguments used during
161 cross-compilation.
204 You can pass additional parameters to 162 You can pass additional parameters to
205 <filename>configure</filename> through the 163 <filename>configure</filename> through the
206 <filename><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link></filename> variable. 164 <filename><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link></filename> variable.
207 </para></listitem> 165 </para></listitem>
208 <listitem><para><link linkend='ref-tasks-compile'><filename>do_compile</filename></link> - 166 <listitem><para><link linkend='ref-tasks-compile'><filename>do_compile</filename></link> -
209 Runs <filename>make</filename> with arguments that specify 167 Runs <filename>make</filename> with arguments that specify the
210 the compiler and linker. 168 compiler and linker.
211 You can pass additional arguments through the 169 You can pass additional arguments through
212 <filename><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></filename> 170 the <filename><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></filename> variable.
213 variable.
214 </para></listitem> 171 </para></listitem>
215 <listitem><para><link linkend='ref-tasks-install'><filename>do_install</filename></link> - 172 <listitem><para><link linkend='ref-tasks-install'><filename>do_install</filename></link> -
216 Runs <filename>make install</filename> and passes in 173 Runs <filename>make install</filename> and passes in
@@ -221,25 +178,6 @@
221 </para> 178 </para>
222</section> 179</section>
223 180
224<section id='ref-classes-autotools-brokensep'>
225 <title><filename>autotools-brokensep.bbclass</filename></title>
226
227 <para>
228 The <filename>autotools-brokensep</filename> class behaves the same
229 as the
230 <link linkend='ref-classes-autotools'><filename>autotools</filename></link>
231 class but builds with
232 <link linkend='var-B'><filename>B</filename></link> ==
233 <link linkend='var-S'><filename>S</filename></link>.
234 This method is useful when out-of-tree build support is either not
235 present or is broken.
236 <note>
237 It is recommended that out-of-tree support be fixed and used
238 if at all possible.
239 </note>
240 </para>
241</section>
242
243<section id='ref-classes-base'> 181<section id='ref-classes-base'>
244 <title><filename>base.bbclass</filename></title> 182 <title><filename>base.bbclass</filename></title>
245 183
@@ -791,10 +729,10 @@
791</section> 729</section>
792 730
793<section id='ref-classes-distutils'> 731<section id='ref-classes-distutils'>
794 <title><filename>distutils-*.bbclass</filename></title> 732 <title><filename>distutils*.bbclass</filename></title>
795 733
796 <para> 734 <para>
797 The <filename>distutils-*</filename> classes support recipes for Python 735 The <filename>distutils*</filename> classes support recipes for Python
798 version 2.x extensions, which are simple. 736 version 2.x extensions, which are simple.
799 These recipes usually only need to point to the source's archive and 737 These recipes usually only need to point to the source's archive and
800 then inherit the proper class. 738 then inherit the proper class.
@@ -807,7 +745,7 @@
807 </para></listitem> 745 </para></listitem>
808 <listitem><para>Extensions that use build systems based on 746 <listitem><para>Extensions that use build systems based on
809 <filename>distutils</filename> require 747 <filename>distutils</filename> require
810 the <filename>distutils-*</filename> classes in their recipes. 748 the <filename>distutils</filename> class in their recipes.
811 </para></listitem> 749 </para></listitem>
812 <listitem><para>Extensions that use build systems based on 750 <listitem><para>Extensions that use build systems based on
813 <filename>setuptools</filename> require the 751 <filename>setuptools</filename> require the
@@ -816,8 +754,11 @@
816 </para></listitem> 754 </para></listitem>
817 </itemizedlist> 755 </itemizedlist>
818 The <filename>distutils-common-base</filename> class is required by 756 The <filename>distutils-common-base</filename> class is required by
819 some of the <filename>distutils-*</filename> classes to provide common 757 some of the <filename>distutils*</filename> classes to provide common
820 Python2 support. 758 Python2 support.
759 </para>
760
761 <para>
821 The <filename>distutils-tools</filename> class supports recipes for 762 The <filename>distutils-tools</filename> class supports recipes for
822 additional "distutils" tools. 763 additional "distutils" tools.
823 </para> 764 </para>
@@ -827,7 +768,7 @@
827 <title><filename>distutils3*.bbclass</filename></title> 768 <title><filename>distutils3*.bbclass</filename></title>
828 769
829 <para> 770 <para>
830 The <filename>distutils3</filename> class supports recipes for Python 771 The <filename>distutils3*</filename> classes support recipes for Python
831 version 3.x extensions, which are simple. 772 version 3.x extensions, which are simple.
832 These recipes usually only need to point to the source's archive and 773 These recipes usually only need to point to the source's archive and
833 then inherit the proper class. 774 then inherit the proper class.
@@ -3174,7 +3115,6 @@
3174 <title><filename>sign_rpm.bbclass</filename></title> 3115 <title><filename>sign_rpm.bbclass</filename></title>
3175 3116
3176 <para> 3117 <para>
3177 The <filename>sign_rpm</filename> class
3178 The <filename>sign_rpm</filename> class supports generating signed 3118 The <filename>sign_rpm</filename> class supports generating signed
3179 RPM packages. 3119 RPM packages.
3180 </para> 3120 </para>
@@ -3413,31 +3353,6 @@
3413 </para> 3353 </para>
3414</section> 3354</section>
3415 3355
3416<section id='ref-classes-testimage'>
3417 <title><filename>testimage.bbclass</filename></title>
3418
3419 <para>
3420 The <filename>testimage</filename> class supports running automated
3421 tests against images using QEMU and on actual hardware.
3422 The class handles loading the tests and starting the image.
3423 </para>
3424
3425 <para>
3426 To use the class, you need to perform steps to set up the
3427 environment.
3428 The tests are commands that run on the target system over
3429 <filename>ssh</filename>.
3430 they are written in Python and make use of the
3431 <filename>unittest</filename> module.
3432 </para>
3433
3434 <para>
3435 For information on how to enable, run, and create new tests, see the
3436 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
3437 section.
3438 </para>
3439</section>
3440
3441<section id='ref-classes-testimage*'> 3356<section id='ref-classes-testimage*'>
3442 <title><filename>testimage*.bbclass</filename></title> 3357 <title><filename>testimage*.bbclass</filename></title>
3443 3358
@@ -3462,10 +3377,13 @@
3462 <literallayout class='monospaced'> 3377 <literallayout class='monospaced'>
3463 $ bitbake -c testimage <replaceable>image</replaceable> 3378 $ bitbake -c testimage <replaceable>image</replaceable>
3464 </literallayout> 3379 </literallayout>
3465 Tests run automatically on an image after the image is constructed 3380 The <filename>testimage-auto</filename> class runs tests on an image
3466 (i.e. 3381 after the image is constructed (i.e.
3467 <link linkend='var-TEST_IMAGE'><filename>TEST_IMAGE</filename></link> 3382 <link linkend='var-TEST_IMAGE'><filename>TEST_IMAGE</filename></link>
3468 must be set to "1"). 3383 must be set to "1").
3384 </para>
3385
3386 <para>
3469 For information on how to enable, run, and create new tests, see the 3387 For information on how to enable, run, and create new tests, see the
3470 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>" 3388 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
3471 section in the Yocto Project Development Manual. 3389 section in the Yocto Project Development Manual.
@@ -3657,14 +3575,14 @@
3657 The <filename>useradd*</filename> classes support the addition of users 3575 The <filename>useradd*</filename> classes support the addition of users
3658 or groups for usage by the package on the target. 3576 or groups for usage by the package on the target.
3659 For example, if you have packages that contain system services that 3577 For example, if you have packages that contain system services that
3660 should be run under their own user or group, you can use this class to 3578 should be run under their own user or group, you can use these classes
3661 enable creation of the user or group. 3579 to enable creation of the user or group.
3662 The <filename>meta-skeleton/recipes-skeleton/useradd/useradd-example.bb</filename> 3580 The <filename>meta-skeleton/recipes-skeleton/useradd/useradd-example.bb</filename>
3663 recipe in the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> 3581 recipe in the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
3664 provides a simple example that shows how to add three 3582 provides a simple example that shows how to add three
3665 users and groups to two packages. 3583 users and groups to two packages.
3666 See the <filename>useradd-example.bb</filename> recipe for more 3584 See the <filename>useradd-example.bb</filename> recipe for more
3667 information on how to use this class. 3585 information on how to use these classes.
3668 </para> 3586 </para>
3669 3587
3670 <para> 3588 <para>
@@ -3681,10 +3599,6 @@
3681 <link linkend='var-GROUPMEMS_PARAM'><filename>GROUPMEMS_PARAM</filename></link> 3599 <link linkend='var-GROUPMEMS_PARAM'><filename>GROUPMEMS_PARAM</filename></link>
3682 variables. 3600 variables.
3683 </para> 3601 </para>
3684</section>
3685
3686<section id='ref-classes-useradd-staticids'>
3687 <title><filename>useradd-staticids.bbclass</filename></title>
3688 3602
3689 <para> 3603 <para>
3690 The <filename>useradd-staticids</filename> class supports the addition 3604 The <filename>useradd-staticids</filename> class supports the addition
@@ -3728,7 +3642,8 @@
3728 </para> 3642 </para>
3729 3643
3730 <note><title>Notes</title> 3644 <note><title>Notes</title>
3731 You do not use this class directly. 3645 You do not use the <filename>useradd-staticids</filename>
3646 class directly.
3732 You either enable or disable the class by setting the 3647 You either enable or disable the class by setting the
3733 <filename>USERADDEXTENSION</filename> variable. 3648 <filename>USERADDEXTENSION</filename> variable.
3734 If you enable or disable the class in a configured system, 3649 If you enable or disable the class in a configured system,