summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2014-10-14 06:57:45 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2014-10-18 16:15:28 +0200
commit8eb706a41b040cf1397c2ebe5517c40031f4d1fb (patch)
treee712abfb9878b9ab803b7c862799b769b682f631 /documentation/ref-manual
parent323929d1ee5d18da7aebf1e536706f00f65f4f35 (diff)
downloadpoky-8eb706a41b040cf1397c2ebe5517c40031f4d1fb.tar.gz
ref-manual, dev-manual: Applied migration review edits.
Applied the full set of first draft revision edits for the new migration section for 1.7. Comments from Paul Eggleton. (From yocto-docs rev: 90586addbc719ecaf7c768b267adf0e988e27b74) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/ref-manual')
-rw-r--r--documentation/ref-manual/migration.xml85
-rw-r--r--documentation/ref-manual/ref-classes.xml22
-rw-r--r--documentation/ref-manual/ref-variables.xml83
-rw-r--r--documentation/ref-manual/usingpoky.xml2
4 files changed, 73 insertions, 119 deletions
diff --git a/documentation/ref-manual/migration.xml b/documentation/ref-manual/migration.xml
index 864c489251..dd8c3e00cc 100644
--- a/documentation/ref-manual/migration.xml
+++ b/documentation/ref-manual/migration.xml
@@ -1710,17 +1710,19 @@
1710 class changes occurred: 1710 class changes occurred:
1711 <itemizedlist> 1711 <itemizedlist>
1712 <listitem><para><emphasis> 1712 <listitem><para><emphasis>
1713 A separate build directory in Autotools recipes is 1713 A separate build directory is now used by default:</emphasis>
1714 handled:</emphasis>
1715 The <filename>autotools</filename> class has been changed 1714 The <filename>autotools</filename> class has been changed
1716 to use a directory for building 1715 to use a directory for building
1717 (<link linkend='var-B'><filename>B</filename></link>), 1716 (<link linkend='var-B'><filename>B</filename></link>),
1718 which is separate from the source directory 1717 which is separate from the source directory
1719 (<link linkend='var-S'><filename>S</filename></link>). 1718 (<link linkend='var-S'><filename>S</filename></link>).
1720 If the software being built is already capable of 1719 This is commonly referred to as
1720 <filename>B != S</filename>, or an out-of-tree build.</para>
1721 <para>If the software being built is already capable of
1721 building in a directory separate from the source, you 1722 building in a directory separate from the source, you
1722 do not need to do anything. 1723 do not need to do anything.
1723 However, if this capability does not exist, you will 1724 However, if the software is not capable of being built
1725 in this manner, you will
1724 need to either patch the software so that it can build 1726 need to either patch the software so that it can build
1725 separately, or you will need to change the recipe to 1727 separately, or you will need to change the recipe to
1726 inherit the 1728 inherit the
@@ -1728,25 +1730,24 @@
1728 class instead of the <filename>autotools</filename> class. 1730 class instead of the <filename>autotools</filename> class.
1729 </para></listitem> 1731 </para></listitem>
1730 <listitem><para><emphasis> 1732 <listitem><para><emphasis>
1731 Handle "foreign":</emphasis> 1733 The <filename>&dash;&dash;foreign</filename> option is
1732 The <filename>--foreign</filename> option is no longer 1734 no longer passed to <filename>automake</filename> when
1733 passed to <filename>automake</filename> when running 1735 running <filename>autoconf</filename>:</emphasis>
1734 <filename>autoreconf</filename>.
1735 This option tells <filename>automake</filename> that a 1736 This option tells <filename>automake</filename> that a
1736 particular software package does not follow the GNU 1737 particular software package does not follow the GNU
1737 standards and therefore should not be expected 1738 standards and therefore should not be expected
1738 to distribute certain files such as 1739 to distribute certain files such as
1739 <filename>ChangeLog</filename>, 1740 <filename>ChangeLog</filename>,
1740 <filename>AUTHORS</filename>, and so forth. 1741 <filename>AUTHORS</filename>, and so forth.
1741 The majority of upstream software packages already tell 1742 Because the majority of upstream software packages already
1742 <filename>automake</filename> these packages are foreign 1743 tell <filename>automake</filename> to enable foreign mode
1743 and thus this option is mostly superfluous. 1744 themselves, the option is mostly superfluous.
1744 However, some recipes will need patches for this change. 1745 However, some recipes will need patches for this change.
1745 You can easily make the change by patching 1746 You can easily make the change by patching
1746 <filename>configure.ac</filename> so that it passes 1747 <filename>configure.ac</filename> so that it passes
1747 "foreign" to <filename>AM_INIT_AUTOMAKE()</filename>. 1748 "foreign" to <filename>AM_INIT_AUTOMAKE()</filename>.
1748 See 1749 See
1749 <ulink url='http://cgit.openembedded.org/openembedded-core/commit/?id=01943188f85ce6411717fb5bf702d609f55813f2'></ulink> 1750 <ulink url='http://cgit.openembedded.org/openembedded-core/commit/?id=01943188f85ce6411717fb5bf702d609f55813f2'>this commit</ulink>
1750 for an example showing how to make the patch. 1751 for an example showing how to make the patch.
1751 </para></listitem> 1752 </para></listitem>
1752 </itemizedlist> 1753 </itemizedlist>
@@ -1757,12 +1758,12 @@
1757 <title>Binary Configuration Scripts Disabled</title> 1758 <title>Binary Configuration Scripts Disabled</title>
1758 1759
1759 <para> 1760 <para>
1760 Some of the core recipes that previously packaged binary 1761 Some of the core recipes that package binary configuration scripts
1761 configuration scripts now disable the scripts instead due to the 1762 now disable the scripts instead due to the
1762 scripts previously requiring error-prone path substitution. 1763 scripts previously requiring error-prone path substitution.
1763 Software that links against these libraries using these scripts 1764 Software that links against these libraries using these scripts
1764 should use the much more robust 1765 should use the much more robust <filename>pkg-config</filename>
1765 <filename>pkg-config</filename> instead. 1766 instead.
1766 The list of recipes changed in this version (and their 1767 The list of recipes changed in this version (and their
1767 configuration scripts) is as follows: 1768 configuration scripts) is as follows:
1768 <literallayout class='monospaced'> 1769 <literallayout class='monospaced'>
@@ -1787,12 +1788,10 @@
1787 pth (pth-config) 1788 pth (pth-config)
1788 taglib (taglib-config) 1789 taglib (taglib-config)
1789 </literallayout> 1790 </literallayout>
1790 <note> 1791 Additionally, support for <filename>pkg-config</filename> has been
1791 Support for <filename>pkg-config</filename> has been added to 1792 added to some recipes in the previous list in the rare cases
1792 some recipes in the previous list in the rare cases 1793 where the upstream software package does not already provide
1793 where the upstream software package does not already provide 1794 it.
1794 it.
1795 </note>
1796 </para> 1795 </para>
1797 </section> 1796 </section>
1798 1797
@@ -1811,15 +1810,15 @@
1811 </para> 1810 </para>
1812 1811
1813 <para> 1812 <para>
1814 <filename>glibc 2.20</filename> also minimally requires version 1813 <filename>glibc 2.20</filename> requires version 2.6.32 or greater
1815 2.6.32 of the Linux kernel. 1814 of the Linux kernel.
1816 Thus, older kernels will no longer be usable in conjunction with it. 1815 Thus, older kernels will no longer be usable in conjunction with it.
1817 </para> 1816 </para>
1818 1817
1819 <para> 1818 <para>
1820 For full details on the changes in <filename>glibc 2.20</filename>, 1819 For full details on the changes in <filename>glibc 2.20</filename>,
1821 see the upstream release notes at 1820 see the upstream release notes
1822 <ulink url='https://sourceware.org/ml/libc-alpha/2014-09/msg00088.html'></ulink>. 1821 <ulink url='https://sourceware.org/ml/libc-alpha/2014-09/msg00088.html'>here</ulink>.
1823 </para> 1822 </para>
1824 </section> 1823 </section>
1825 1824
@@ -1829,33 +1828,25 @@
1829 <para> 1828 <para>
1830 The 1829 The
1831 <link linkend='var-module_autoload'><filename>module_autoload_*</filename></link> 1830 <link linkend='var-module_autoload'><filename>module_autoload_*</filename></link>
1832 and 1831 variable is now deprecated and a new
1833 <link linkend='var-module_conf'><filename>module_conf_*</filename></link>
1834 variables have been replaced with the variables
1835 <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link> 1832 <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link>
1836 and 1833 variable should be used instead.
1837 <link linkend='var-KERNEL_MODULE_PROBECONF'><filename>KERNEL_MODULE_PROBECONF</filename></link>, 1834 Also,
1838 respectively. 1835 <link linkend='var-module_conf'><filename>module_conf_*</filename></link>
1839 These variables no longer require you to specify the module name 1836 must now be used in conjunction with a new
1837 <link linkend='var-KERNEL_MODULE_PROBECONF'><filename>KERNEL_MODULE_PROBECONF</filename></link>
1838 variable.
1839 The new variables no longer require you to specify the module name
1840 as part of the variable name. 1840 as part of the variable name.
1841 This change not only simplifies usage but also allows the values 1841 This change not only simplifies usage but also allows the values
1842 of these variables to be appropriately incorporated into task 1842 of these variables to be appropriately incorporated into task
1843 signatures and thus trigger the appropriate tasks to re-execute 1843 signatures and thus trigger the appropriate tasks to re-execute
1844 when changed. 1844 when changed.
1845 You should replace any references to 1845 You should replace any references to
1846 <filename>module_autoload_*</filename> or 1846 <filename>module_autoload_*</filename> with
1847 <filename>module_conf_*</filename> with the new variables. 1847 <filename>KERNEL_MODULE_AUTOLOAD</filename>, and add any modules
1848 <note> 1848 for which <filename>module_conf_*</filename> is specified to
1849 While it is recommended that you replace occurrences of the 1849 <filename>KERNEL_MODULE_PROBECONF</filename>.
1850 <filename>module_conf_*</filename> variable with the
1851 <filename>KERNEL_MODULE_PROBECONF</filename> variable, the
1852 OpenEmbedded build system still recognizes the
1853 <filename>module_conf_*</filename> variable.
1854 However, you must be sure that any module name used in the
1855 override with the <filename>module_conf</filename> variable
1856 is included in the <filename>KERNEL_MODULE_PROBECONF</filename>
1857 variable.
1858 </note>
1859 </para> 1850 </para>
1860 1851
1861 <para> 1852 <para>
@@ -1863,7 +1854,7 @@
1863 <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link> 1854 <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link>
1864 and 1855 and
1865 <link linkend='var-KERNEL_MODULE_PROBECONF'><filename>KERNEL_MODULE_PROBECONF</filename></link> 1856 <link linkend='var-KERNEL_MODULE_PROBECONF'><filename>KERNEL_MODULE_PROBECONF</filename></link>
1866 descriptions in the variable's glossary. 1857 variables.
1867 </para> 1858 </para>
1868 </section> 1859 </section>
1869 1860
diff --git a/documentation/ref-manual/ref-classes.xml b/documentation/ref-manual/ref-classes.xml
index 3e7662e146..1b01ef61c9 100644
--- a/documentation/ref-manual/ref-classes.xml
+++ b/documentation/ref-manual/ref-classes.xml
@@ -102,6 +102,17 @@
102 </para> 102 </para>
103 103
104 <para> 104 <para>
105 By default, the <filename>autotools</filename> class supports
106 out-of-tree builds
107 (<link linkend='var-B'><filename>B</filename></link> <filename>!=</filename>
108 <link linkend='var-S'><filename>S</filename></link>).
109 If your recipes do not support out-of-tree builds, you should
110 have them inherit the
111 <link linkend='ref-classes-autotools-brokensep'><filename>autotools-brokensep</filename></link>
112 class.
113 </para>
114
115 <para>
105 It's useful to have some idea of how the tasks defined by this class work 116 It's useful to have some idea of how the tasks defined by this class work
106 and what they do behind the scenes. 117 and what they do behind the scenes.
107 <itemizedlist> 118 <itemizedlist>
@@ -123,17 +134,6 @@
123 </para></listitem> 134 </para></listitem>
124 </itemizedlist> 135 </itemizedlist>
125 </para> 136 </para>
126
127 <note>
128 It is planned for future Yocto Project releases that by default, the
129 <filename>autotools</filename> class supports out-of-tree builds
130 (<link linkend='var-B'><filename>B</filename></link> !=
131 <link linkend='var-S'><filename>S</filename></link>).
132 If your recipes do not support out-of-tree builds, you should
133 have them inherit the
134 <link linkend='ref-classes-autotools-brokensep'><filename>autotools-brokensep</filename></link>
135 class.
136 </note>
137</section> 137</section>
138 138
139<section id='ref-classes-autotools-brokensep'> 139<section id='ref-classes-autotools-brokensep'>
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index 1cff5bdfaa..aadae01ac4 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -4458,7 +4458,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
4458 <para> 4458 <para>
4459 Specify it as follows: 4459 Specify it as follows:
4460 <literallayout class='monospaced'> 4460 <literallayout class='monospaced'>
4461 KERNEL_MODULE_AUTOLOAD = "modname1 modname2 modname3" 4461 KERNEL_MODULE_AUTOLOAD += "modname1 modname2 modname3"
4462 </literallayout> 4462 </literallayout>
4463 </para> 4463 </para>
4464 4464
@@ -4470,7 +4470,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
4470 The modules appear one-per-line in the file. 4470 The modules appear one-per-line in the file.
4471 Here is an example of the most common use case: 4471 Here is an example of the most common use case:
4472 <literallayout class='monospaced'> 4472 <literallayout class='monospaced'>
4473 KERNEL_MODULE_AUTOLOAD = "modname" 4473 KERNEL_MODULE_AUTOLOAD += "modname"
4474 </literallayout> 4474 </literallayout>
4475 </para> 4475 </para>
4476 4476
@@ -4487,58 +4487,14 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
4487 <glossentry id='var-KERNEL_MODULE_PROBECONF'><glossterm>KERNEL_MODULE_PROBECONF</glossterm> 4487 <glossentry id='var-KERNEL_MODULE_PROBECONF'><glossterm>KERNEL_MODULE_PROBECONF</glossterm>
4488 <glossdef> 4488 <glossdef>
4489 <para> 4489 <para>
4490 Specifies 4490 Provides a list of modules for which the OpenEmbedded
4491 <ulink url='http://linux.die.net/man/5/modprobe.d'><filename>modprobe.d</filename></ulink> 4491 build system expects to find
4492 syntax lines for inclusion in the 4492 <link linkend='var-module_conf'><filename>module_conf_&lt;modname&gt;</filename></link>
4493 <filename>/etc/modprobe.d/modname.conf</filename> file. 4493 values that specify configuration for each of the modules.
4494 <note> 4494 For information on how to provide those module
4495 The <filename>KERNEL_MODULE_PROBECONF</filename> 4495 configurations, see the
4496 variable behaves the same as the 4496 <link linkend='var-module_conf'><filename>module_conf_*</filename></link>
4497 <link linkend='var-module_conf'><filename>module_conf</filename></link> 4497 variable.
4498 variable with the exception of not having to use a
4499 module name override.
4500 </note>
4501 </para>
4502
4503 <para>
4504 You can use the
4505 <filename>KERNEL_MODULE_PROBECONF</filename> variable
4506 anywhere it can be recognized by the kernel recipe or
4507 an out-of-tree kernel module recipe (e.g. a machine
4508 configuration file, a distribution configuration file, an
4509 append file for the recipe, or the recipe itself).
4510 </para>
4511
4512 <para>
4513 Here is the general syntax:
4514 <literallayout class='monospaced'>
4515 KERNEL_MODULE_PROBECONF = "&lt;modprobe.d syntax&gt;"
4516 </literallayout>
4517 </para>
4518
4519 <para>
4520 Run <filename>man modprobe.d</filename> in the shell to
4521 find out more information on the exact syntax
4522 you want to provide with <filename>KERNEL_MODULE_PROBECONF</filename>.
4523 </para>
4524
4525 <para>
4526 Including <filename>KERNEL_MODULE_PROBECONF</filename> causes
4527 the OpenEmbedded build system to populate the
4528 <filename>/etc/modprobe.d/modname.conf</filename>
4529 file with <filename>modprobe.d</filename> syntax lines.
4530 Here is an example that adds the options
4531 <filename>arg1</filename> and <filename>arg2</filename>
4532 to a module named <filename>mymodule</filename>:
4533 <literallayout class='monospaced'>
4534 KERNEL_MODULE_PROBECONF = "options mymodule arg1=val1 arg2=val2"
4535 </literallayout>
4536 </para>
4537
4538 <para>
4539 For information on how to specify kernel modules to
4540 auto-load on boot, see the
4541 <filename>KERNEL_MODULE_AUTOLOAD</filename> variable.
4542 </para> 4498 </para>
4543 </glossdef> 4499 </glossdef>
4544 </glossentry> 4500 </glossentry>
@@ -5410,12 +5366,19 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
5410 <para> 5366 <para>
5411 This variable has been replaced by the 5367 This variable has been replaced by the
5412 <filename>KERNEL_MODULE_AUTOLOAD</filename> variable. 5368 <filename>KERNEL_MODULE_AUTOLOAD</filename> variable.
5413 You should replace all occurrences of the 5369 You should replace all occurrences of
5414 <filename>module_autoload</filename> variable with 5370 <filename>module_autoload</filename> with additions to
5415 <filename>KERNEL_MODULE_AUTOLOAD</filename> variables. 5371 <filename>KERNEL_MODULE_AUTOLOAD</filename>, for example:
5372 <literallayout class='monospaced'>
5373 module_autoload_rfcomm = "rfcomm"
5374 </literallayout>
5375 should now be replaced with:
5376 <literallayout class='monospaced'>
5377 KERNEL_MODULE_AUTOLOAD += "rfcomm"
5378 </literallayout>
5416 See the 5379 See the
5417 <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link> 5380 <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link>
5418 variable for a description of the variable. 5381 variable for more information.
5419 </para> 5382 </para>
5420 </glossdef> 5383 </glossdef>
5421 </glossentry> 5384 </glossentry>
@@ -5437,7 +5400,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
5437 recipe, or the recipe itself). 5400 recipe, or the recipe itself).
5438 If you use this variable, you must also be sure to list 5401 If you use this variable, you must also be sure to list
5439 the module name in the 5402 the module name in the
5440 <link linkend='var-KERNEL_MODULE_PROBECONF'><filename>KERNEL_MODULE_PROBECONF</filename></link> 5403 <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link>
5441 variable. 5404 variable.
5442 </para> 5405 </para>
5443 5406
@@ -5471,7 +5434,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
5471 <para> 5434 <para>
5472 For information on how to specify kernel modules to 5435 For information on how to specify kernel modules to
5473 auto-load on boot, see the 5436 auto-load on boot, see the
5474 <link linkend='var-module_autoload'><filename>module_autoload</filename></link> 5437 <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link>
5475 variable. 5438 variable.
5476 </para> 5439 </para>
5477 </glossdef> 5440 </glossdef>
diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml
index 5a6a4068a7..283fb725ac 100644
--- a/documentation/ref-manual/usingpoky.xml
+++ b/documentation/ref-manual/usingpoky.xml
@@ -540,7 +540,7 @@
540 540
541 <para> 541 <para>
542 Build history information is kept in 542 Build history information is kept in
543 <filename>$</filename><link linkend='var-TOPDIR'><filename>TOPDIR</filename></link><filename>/buildhistory</filename> 543 <filename>${</filename><link linkend='var-TOPDIR'><filename>TOPDIR</filename></link><filename>}/buildhistory</filename>
544 in the Build Directory as defined by the 544 in the Build Directory as defined by the
545 <link linkend='var-BUILDHISTORY_DIR'><filename>BUILDHISTORY_DIR</filename></link> 545 <link linkend='var-BUILDHISTORY_DIR'><filename>BUILDHISTORY_DIR</filename></link>
546 variable. 546 variable.