sysmo-bts
/
generic-poky
9
0
Fork 0
Code Pull Requests Releases Activity

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>
This commit is contained in:
Scott Rifenbark 2015-10-13 10:00:54 -07:00 committed by Richard Purdie
parent 359b7fb639
commit 2fe3809465
5 changed files with 71 additions and 154 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
documentation/dev-manual/dev-manual-common-tasks.xml
View File

@ -8583,7 +8583,7 @@
</literallayout></para></listitem> </literallayout></para></listitem>
<listitem><para><emphasis>Manually running tests:</emphasis> <listitem><para><emphasis>Manually running tests:</emphasis>
To manually run the tests, first globally inherit the To manually run the tests, first globally inherit the
<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-testimage'><filename>testimage</filename></ulink> <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-testimage*'><filename>testimage</filename></ulink>
class by editing your <filename>local.conf</filename> class by editing your <filename>local.conf</filename>
file: file:
<literallayout class='monospaced'> <literallayout class='monospaced'>

2
documentation/ref-manual/closer-look.xml
View File

@ -1059,7 +1059,7 @@
the root filesystem image that lists out, line-by-line, the the root filesystem image that lists out, line-by-line, the
installed packages. installed packages.
This manifest file is useful for the This manifest file is useful for the
<link linkend='ref-classes-testimage'><filename>testimage</filename></link> <link linkend='ref-classes-testimage*'><filename>testimage</filename></link>
class, for example, to determine whether or not to run class, for example, to determine whether or not to run
specific tests. specific tests.
See the See the

12
documentation/ref-manual/migration.xml
View File

@ -980,7 +980,7 @@
<para> <para>
A new automated image testing framework has been added A new automated image testing framework has been added
through the through the
<link linkend='ref-classes-testimage'><filename>testimage*.bbclass</filename></link> <link linkend='ref-classes-testimage*'><filename>testimage.bbclass</filename></link>
class. class.
This framework replaces the older This framework replaces the older
<filename>imagetest-qemu</filename> framework. <filename>imagetest-qemu</filename> framework.
@ -1485,8 +1485,9 @@
Recipes building Autotools-based Recipes building Autotools-based
software that fails to build with a separate build directory software that fails to build with a separate build directory
should be changed to inherit from the should be changed to inherit from the
<link linkend='ref-classes-autotools-brokensep'><filename>autotools-brokensep</filename></link> <link linkend='ref-classes-autotools'><filename>autotools-brokensep</filename></link>
class instead of the <filename>autotools</filename> class. class instead of the <filename>autotools</filename> or
<filename>autotools_stage</filename>classes.
</para> </para>
</section> </section>
@ -1794,8 +1795,9 @@
need to either patch the software so that it can build need to either patch the software so that it can build
separately, or you will need to change the recipe to separately, or you will need to change the recipe to
inherit the inherit the
<link linkend='ref-classes-autotools-brokensep'><filename>autotools-brokensep</filename></link> <link linkend='ref-classes-autotools'><filename>autotools-brokensep</filename></link>
class instead of the <filename>autotools</filename> class. class instead of the <filename>autotools</filename> or
<filename>autotools_stage</filename> classes.
</para></listitem> </para></listitem>
<listitem><para><emphasis> <listitem><para><emphasis>
The <filename>--foreign</filename> option is The <filename>--foreign</filename> option is

205
documentation/ref-manual/ref-classes.xml
View File

@ -101,134 +101,44 @@
</section> </section>
<section id='ref-classes-autotools'> <section id='ref-classes-autotools'>
<title><filename>autotools.bbclass</filename></title> <title><filename>autotools*.bbclass</filename></title>
<para> <para>
The <filename>autotools</filename> class supports Autotooled The <filename>autotools*</filename> classes support Autotooled
packages. packages.
</para> </para>
<para> <para>
The <filename>autoconf</filename>, <filename>automake</filename>, The <filename>autoconf</filename>, <filename>automake</filename>,
and <filename>libtool</filename> bring standardization. and <filename>libtool</filename> packages bring standardization.
This class defines a set of tasks (e.g. This class defines a set of tasks (e.g.
<filename>configure</filename>, <filename>compile</filename> and <filename>configure</filename>, <filename>compile</filename> and
so forth) that so forth) that
work for all Autotooled packages. work for all Autotooled packages.
It should usually be enough to define a few standard variables It should usually be enough to define a few standard variables
and then simply <filename>inherit autotools</filename>. and then simply <filename>inherit autotools</filename>.
This class can also work with software that emulates Autotools. These classes can also work with software that emulates Autotools.
For more information, see the For more information, see the
"<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-autotooled-package'>Autotooled Package</ulink>" "<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-autotooled-package'>Autotooled Package</ulink>"
section in the Yocto Project Development Manual. section in the Yocto Project Development Manual.
</para> </para>
<para> <para>
By default, the <filename>autotools</filename> class By default, the <filename>autotools*</filename> classes
uses out-of-tree builds use out-of-tree builds (i.e.
<filename>autotools.bbclass</filename> and
<filename>autotools_stage.bbclass</filename>).
(<link linkend='var-B'><filename>B</filename></link> <filename>!=</filename> (<link linkend='var-B'><filename>B</filename></link> <filename>!=</filename>
<link linkend='var-S'><filename>S</filename></link>). <link linkend='var-S'><filename>S</filename></link>).
</para>
<para>
If the software being built by a recipe does not support If the software being built by a recipe does not support
using out-of-tree builds, you should have the recipe inherit the using out-of-tree builds, you should have the recipe inherit the
<link linkend='ref-classes-autotools-brokensep'><filename>autotools-brokensep</filename></link> <filename>autotools-brokensep</filename> class.
class.
</para>
<para>
It's useful to have some idea of how the tasks defined by this class
work and what they do behind the scenes.
<itemizedlist>
<listitem><para><link linkend='ref-tasks-configure'><filename>do_configure</filename></link> -
Regenerates the
configure script (using <filename>autoreconf</filename>) and then launches it
with a standard set of arguments used during cross-compilation.
You can pass additional parameters to <filename>configure</filename> through the
<filename><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link></filename> variable.
</para></listitem>
<listitem><para><link linkend='ref-tasks-compile'><filename>do_compile</filename></link> - Runs <filename>make</filename> with
arguments that specify the compiler and linker.
You can pass additional arguments through
the <filename><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></filename> variable.
</para></listitem>
<listitem><para><link linkend='ref-tasks-install'><filename>do_install</filename></link> - Runs <filename>make install</filename>
and passes in
<filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename>
as <filename>DESTDIR</filename>.
</para></listitem>
</itemizedlist>
</para>
</section>
<section id='ref-classes-autotools-stage'>
<title><filename>autotools_stage.bbclass</filename></title>
<para>
The <filename>autotools_stage</filename> class supports Autotooled
packages.
</para>
<para>
The <filename>autoconf</filename>,
<filename>automake</filename>, and <filename>libtool</filename>
bring standardization.
This class defines a set of tasks
(e.g. <filename>configure</filename>, <filename>compile</filename>
and so forth) that work for all Autotooled packages.
It is usually enough to define a few standard variables and then
simply inherit <filename>autotools</filename>.
This class can also work with software that emulates Autotools.
For more information, see the
"<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-autotooled-package'>Autotooled Package</ulink>"
section in the Yocto Project Development Manual.
</para>
<para>
By default, the <filename>autotools-stage</filename> class uses
out-of-tree builds
(<link linkend='var-B'><filename>B</filename></link> <filename>!=</filename>
<link linkend='var-S'><filename>S</filename></link>).
If the software being built by a recipe does not support
using out-of-tree builds, you should have the recipe inherit the
<link linkend='ref-classes-autotools-brokensep'><filename>autotools-brokensep</filename></link>
class.
</para>
<para>
It is useful to have some idea of how the tasks defined by this
class work and what they do behind the scenes.
<itemizedlist>
<listitem><para><link linkend='ref-tasks-configure'><filename>do_configure</filename></link> -
Regenerates the configure script (using
<filename>autoreconf</filename>) and then launches it
with a standard set of arguments used during cross-compilation.
You can pass additional parameters to
<filename>configure</filename> through the
<filename><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link></filename> variable.
</para></listitem>
<listitem><para><link linkend='ref-tasks-compile'><filename>do_compile</filename></link> -
Runs <filename>make</filename> with arguments that specify
the compiler and linker.
You can pass additional arguments through the
<filename><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></filename>
variable.
</para></listitem>
<listitem><para><link linkend='ref-tasks-install'><filename>do_install</filename></link> -
Runs <filename>make install</filename> and passes in
<filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename>
as <filename>DESTDIR</filename>.
</para></listitem>
</itemizedlist>
</para>
</section>
<section id='ref-classes-autotools-brokensep'>
<title><filename>autotools-brokensep.bbclass</filename></title>
<para>
The <filename>autotools-brokensep</filename> class behaves the same The <filename>autotools-brokensep</filename> class behaves the same
as the as the <filename>autotools</filename> and
<link linkend='ref-classes-autotools'><filename>autotools</filename></link> <filename>autotools_stage</filename> classes but builds with
class but builds with
<link linkend='var-B'><filename>B</filename></link> == <link linkend='var-B'><filename>B</filename></link> ==
<link linkend='var-S'><filename>S</filename></link>. <link linkend='var-S'><filename>S</filename></link>.
This method is useful when out-of-tree build support is either not This method is useful when out-of-tree build support is either not
@ -238,6 +148,34 @@
if at all possible. if at all possible.
</note> </note>
</para> </para>
<para>
It's useful to have some idea of how the tasks defined by
the <filename>autotools*</filename> classes work and what they do
behind the scenes.
<itemizedlist>
<listitem><para><link linkend='ref-tasks-configure'><filename>do_configure</filename></link> -
Regenerates the
configure script (using <filename>autoreconf</filename>) and
then launches it with a standard set of arguments used during
cross-compilation.
You can pass additional parameters to
<filename>configure</filename> through the
<filename><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link></filename> variable.
</para></listitem>
<listitem><para><link linkend='ref-tasks-compile'><filename>do_compile</filename></link> -
Runs <filename>make</filename> with arguments that specify the
compiler and linker.
You can pass additional arguments through
the <filename><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></filename> variable.
</para></listitem>
<listitem><para><link linkend='ref-tasks-install'><filename>do_install</filename></link> -
Runs <filename>make install</filename> and passes in
<filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename>
as <filename>DESTDIR</filename>.
</para></listitem>
</itemizedlist>
</para>
</section> </section>
<section id='ref-classes-base'> <section id='ref-classes-base'>
@ -791,10 +729,10 @@
</section> </section>
<section id='ref-classes-distutils'> <section id='ref-classes-distutils'>
<title><filename>distutils-*.bbclass</filename></title> <title><filename>distutils*.bbclass</filename></title>
<para> <para>
The <filename>distutils-*</filename> classes support recipes for Python The <filename>distutils*</filename> classes support recipes for Python
version 2.x extensions, which are simple. version 2.x extensions, which are simple.
These recipes usually only need to point to the source's archive and These recipes usually only need to point to the source's archive and
then inherit the proper class. then inherit the proper class.
@ -807,7 +745,7 @@
</para></listitem> </para></listitem>
<listitem><para>Extensions that use build systems based on <listitem><para>Extensions that use build systems based on
<filename>distutils</filename> require <filename>distutils</filename> require
the <filename>distutils-*</filename> classes in their recipes. the <filename>distutils</filename> class in their recipes.
</para></listitem> </para></listitem>
<listitem><para>Extensions that use build systems based on <listitem><para>Extensions that use build systems based on
<filename>setuptools</filename> require the <filename>setuptools</filename> require the
@ -816,8 +754,11 @@
</para></listitem> </para></listitem>
</itemizedlist> </itemizedlist>
The <filename>distutils-common-base</filename> class is required by The <filename>distutils-common-base</filename> class is required by
some of the <filename>distutils-*</filename> classes to provide common some of the <filename>distutils*</filename> classes to provide common
Python2 support. Python2 support.
</para>
<para>
The <filename>distutils-tools</filename> class supports recipes for The <filename>distutils-tools</filename> class supports recipes for
additional "distutils" tools. additional "distutils" tools.
</para> </para>
@ -827,7 +768,7 @@
<title><filename>distutils3*.bbclass</filename></title> <title><filename>distutils3*.bbclass</filename></title>
<para> <para>
The <filename>distutils3</filename> class supports recipes for Python The <filename>distutils3*</filename> classes support recipes for Python
version 3.x extensions, which are simple. version 3.x extensions, which are simple.
These recipes usually only need to point to the source's archive and These recipes usually only need to point to the source's archive and
then inherit the proper class. then inherit the proper class.
@ -3174,7 +3115,6 @@
<title><filename>sign_rpm.bbclass</filename></title> <title><filename>sign_rpm.bbclass</filename></title>
<para> <para>
The <filename>sign_rpm</filename> class
The <filename>sign_rpm</filename> class supports generating signed The <filename>sign_rpm</filename> class supports generating signed
RPM packages. RPM packages.
</para> </para>
@ -3413,31 +3353,6 @@
</para> </para>
</section> </section>
<section id='ref-classes-testimage'>
<title><filename>testimage.bbclass</filename></title>
<para>
The <filename>testimage</filename> class supports running automated
tests against images using QEMU and on actual hardware.
The class handles loading the tests and starting the image.
</para>
<para>
To use the class, you need to perform steps to set up the
environment.
The tests are commands that run on the target system over
<filename>ssh</filename>.
they are written in Python and make use of the
<filename>unittest</filename> module.
</para>
<para>
For information on how to enable, run, and create new tests, see the
"<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
section.
</para>
</section>
<section id='ref-classes-testimage*'> <section id='ref-classes-testimage*'>
<title><filename>testimage*.bbclass</filename></title> <title><filename>testimage*.bbclass</filename></title>
@ -3462,10 +3377,13 @@
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ bitbake -c testimage <replaceable>image</replaceable> $ bitbake -c testimage <replaceable>image</replaceable>
</literallayout> </literallayout>
Tests run automatically on an image after the image is constructed The <filename>testimage-auto</filename> class runs tests on an image
(i.e. after the image is constructed (i.e.
<link linkend='var-TEST_IMAGE'><filename>TEST_IMAGE</filename></link> <link linkend='var-TEST_IMAGE'><filename>TEST_IMAGE</filename></link>
must be set to "1"). must be set to "1").
</para>
<para>
For information on how to enable, run, and create new tests, see the For information on how to enable, run, and create new tests, see the
"<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>" "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
section in the Yocto Project Development Manual. section in the Yocto Project Development Manual.
@ -3657,14 +3575,14 @@
The <filename>useradd*</filename> classes support the addition of users The <filename>useradd*</filename> classes support the addition of users
or groups for usage by the package on the target. or groups for usage by the package on the target.
For example, if you have packages that contain system services that For example, if you have packages that contain system services that
should be run under their own user or group, you can use this class to should be run under their own user or group, you can use these classes
enable creation of the user or group. to enable creation of the user or group.
The <filename>meta-skeleton/recipes-skeleton/useradd/useradd-example.bb</filename> The <filename>meta-skeleton/recipes-skeleton/useradd/useradd-example.bb</filename>
recipe in the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> recipe in the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
provides a simple example that shows how to add three provides a simple example that shows how to add three
users and groups to two packages. users and groups to two packages.
See the <filename>useradd-example.bb</filename> recipe for more See the <filename>useradd-example.bb</filename> recipe for more
information on how to use this class. information on how to use these classes.
</para> </para>
<para> <para>
@ -3681,10 +3599,6 @@
<link linkend='var-GROUPMEMS_PARAM'><filename>GROUPMEMS_PARAM</filename></link> <link linkend='var-GROUPMEMS_PARAM'><filename>GROUPMEMS_PARAM</filename></link>
variables. variables.
</para> </para>
</section>
<section id='ref-classes-useradd-staticids'>
<title><filename>useradd-staticids.bbclass</filename></title>
<para> <para>
The <filename>useradd-staticids</filename> class supports the addition The <filename>useradd-staticids</filename> class supports the addition
@ -3728,7 +3642,8 @@
</para> </para>
<note><title>Notes</title> <note><title>Notes</title>
You do not use this class directly. You do not use the <filename>useradd-staticids</filename>
class directly.
You either enable or disable the class by setting the You either enable or disable the class by setting the
<filename>USERADDEXTENSION</filename> variable. <filename>USERADDEXTENSION</filename> variable.
If you enable or disable the class in a configured system, If you enable or disable the class in a configured system,

4
documentation/ref-manual/ref-variables.xml
View File

@ -12935,7 +12935,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
these tests, see the these tests, see the
"<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>" "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
section in the Yocto Project Development Manual and the section in the Yocto Project Development Manual and the
"<link linkend='ref-classes-testimage'><filename>testimage.bbclass</filename></link>" "<link linkend='ref-classes-testimage*'><filename>testimage*.bbclass</filename></link>"
section. section.
</para> </para>
</glossdef> </glossdef>
@ -14314,7 +14314,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
<filename>uid</filename> and <filename>gid</filename> <filename>uid</filename> and <filename>gid</filename>
values causes the OpenEmbedded build system to employ values causes the OpenEmbedded build system to employ
the the
<link linkend='ref-classes-useradd-staticids'><filename>useradd-staticids</filename></link> <link linkend='ref-classes-useradd'><filename>useradd-staticids</filename></link>
class. class.
</note> </note>
</para> </para>