summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2015-10-13 10:00:54 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2015-10-21 23:06:34 +0100
commit2fe38094657df6564e4f548d376d86678e57b768 (patch)
tree16bc161406e76a465966d9d642d4ad071976605e /documentation/ref-manual
parent359b7fb639d5fa11baba0b3257b7e410d34d4d4b (diff)
downloadpoky-2fe38094657df6564e4f548d376d86678e57b768.tar.gz
ref-manual, dev-manual: Applied feedback to edit several classes
Fixes [YOCTO #8298] Updated several classes with feedback from Jose Lamego of Intel. The feedback fixed some class groupings so that previously isolated classes could be bundled under common classes (e.g. autotools*.bbclass). I scrubbed the cross-references for cases where a particular class became "undocumented." The cross-references now point to the bundled class entry in the ref-manual. (From yocto-docs rev: 07a533cb41ad26d202f4e303f2dbc7d7bf26e076) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/ref-manual')
-rw-r--r--documentation/ref-manual/closer-look.xml2
-rw-r--r--documentation/ref-manual/migration.xml12
-rw-r--r--documentation/ref-manual/ref-classes.xml183
-rw-r--r--documentation/ref-manual/ref-variables.xml4
4 files changed, 59 insertions, 142 deletions
diff --git a/documentation/ref-manual/closer-look.xml b/documentation/ref-manual/closer-look.xml
index 27f674ae2f..45dcd9b3cf 100644
--- a/documentation/ref-manual/closer-look.xml
+++ b/documentation/ref-manual/closer-look.xml
@@ -1059,7 +1059,7 @@
1059 the root filesystem image that lists out, line-by-line, the 1059 the root filesystem image that lists out, line-by-line, the
1060 installed packages. 1060 installed packages.
1061 This manifest file is useful for the 1061 This manifest file is useful for the
1062 <link linkend='ref-classes-testimage'><filename>testimage</filename></link> 1062 <link linkend='ref-classes-testimage*'><filename>testimage</filename></link>
1063 class, for example, to determine whether or not to run 1063 class, for example, to determine whether or not to run
1064 specific tests. 1064 specific tests.
1065 See the 1065 See the
diff --git a/documentation/ref-manual/migration.xml b/documentation/ref-manual/migration.xml
index dc75eb827b..4d798bc283 100644
--- a/documentation/ref-manual/migration.xml
+++ b/documentation/ref-manual/migration.xml
@@ -980,7 +980,7 @@
980 <para> 980 <para>
981 A new automated image testing framework has been added 981 A new automated image testing framework has been added
982 through the 982 through the
983 <link linkend='ref-classes-testimage'><filename>testimage*.bbclass</filename></link> 983 <link linkend='ref-classes-testimage*'><filename>testimage.bbclass</filename></link>
984 class. 984 class.
985 This framework replaces the older 985 This framework replaces the older
986 <filename>imagetest-qemu</filename> framework. 986 <filename>imagetest-qemu</filename> framework.
@@ -1485,8 +1485,9 @@
1485 Recipes building Autotools-based 1485 Recipes building Autotools-based
1486 software that fails to build with a separate build directory 1486 software that fails to build with a separate build directory
1487 should be changed to inherit from the 1487 should be changed to inherit from the
1488 <link linkend='ref-classes-autotools-brokensep'><filename>autotools-brokensep</filename></link> 1488 <link linkend='ref-classes-autotools'><filename>autotools-brokensep</filename></link>
1489 class instead of the <filename>autotools</filename> class. 1489 class instead of the <filename>autotools</filename> or
1490 <filename>autotools_stage</filename>classes.
1490 </para> 1491 </para>
1491 </section> 1492 </section>
1492 1493
@@ -1794,8 +1795,9 @@
1794 need to either patch the software so that it can build 1795 need to either patch the software so that it can build
1795 separately, or you will need to change the recipe to 1796 separately, or you will need to change the recipe to
1796 inherit the 1797 inherit the
1797 <link linkend='ref-classes-autotools-brokensep'><filename>autotools-brokensep</filename></link> 1798 <link linkend='ref-classes-autotools'><filename>autotools-brokensep</filename></link>
1798 class instead of the <filename>autotools</filename> class. 1799 class instead of the <filename>autotools</filename> or
1800 <filename>autotools_stage</filename> classes.
1799 </para></listitem> 1801 </para></listitem>
1800 <listitem><para><emphasis> 1802 <listitem><para><emphasis>
1801 The <filename>--foreign</filename> option is 1803 The <filename>--foreign</filename> option is
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,
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index 538936b43e..82410941c2 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -12935,7 +12935,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
12935 these tests, see the 12935 these tests, see the
12936 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>" 12936 "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
12937 section in the Yocto Project Development Manual and the 12937 section in the Yocto Project Development Manual and the
12938 "<link linkend='ref-classes-testimage'><filename>testimage.bbclass</filename></link>" 12938 "<link linkend='ref-classes-testimage*'><filename>testimage*.bbclass</filename></link>"
12939 section. 12939 section.
12940 </para> 12940 </para>
12941 </glossdef> 12941 </glossdef>
@@ -14314,7 +14314,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
14314 <filename>uid</filename> and <filename>gid</filename> 14314 <filename>uid</filename> and <filename>gid</filename>
14315 values causes the OpenEmbedded build system to employ 14315 values causes the OpenEmbedded build system to employ
14316 the 14316 the
14317 <link linkend='ref-classes-useradd-staticids'><filename>useradd-staticids</filename></link> 14317 <link linkend='ref-classes-useradd'><filename>useradd-staticids</filename></link>
14318 class. 14318 class.
14319 </note> 14319 </note>
14320 </para> 14320 </para>