diff options
| author | Brad Bishop <bradleyb@fuzziesquirrel.com> | 2018-02-01 18:27:11 +0300 |
|---|---|---|
| committer | Brad Bishop <bradleyb@fuzziesquirrel.com> | 2018-03-13 05:51:39 +0300 |
| commit | 6e60e8b2b2bab889379b380a28a167a0edd9d1d3 (patch) | |
| tree | f12f54d5ba8e74e67e5fad3651a1e125bb8f4191 /import-layers/yocto-poky/documentation/ref-manual | |
| parent | 509842add85b53e13164c1569a1fd43d5b8d91c5 (diff) | |
| download | openbmc-6e60e8b2b2bab889379b380a28a167a0edd9d1d3.tar.xz | |
Yocto 2.3
Move OpenBMC to Yocto 2.3(pyro).
Tested: Built and verified Witherspoon and Palmetto images
Change-Id: I50744030e771f4850afc2a93a10d3507e76d36bc
Signed-off-by: Brad Bishop <bradleyb@fuzziesquirrel.com>
Resolves: openbmc/openbmc#2461
Diffstat (limited to 'import-layers/yocto-poky/documentation/ref-manual')
16 files changed, 2221 insertions, 295 deletions
diff --git a/import-layers/yocto-poky/documentation/ref-manual/closer-look.xml b/import-layers/yocto-poky/documentation/ref-manual/closer-look.xml index b73e59ca7e..923ed21da3 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/closer-look.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/closer-look.xml @@ -867,6 +867,19 @@ <para> This step in the build process consists of three tasks: <itemizedlist> + <listitem><para> + <emphasis><link linkend='ref-tasks-prepare_recipe_sysroot'><filename>do_prepare_recipe_sysroot</filename></link>:</emphasis> + This task sets up the two sysroots in + <filename>${</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link><filename>}</filename> + (i.e. <filename>recipe-sysroot</filename> and + <filename>recipe-sysroot-native</filename>) so that + the sysroots contain the contents of the + <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link> + tasks of the recipes on which the recipe + containing the tasks depends. + A sysroot exists for both the target and for the native + binaries, which run on the host system. + </para></listitem> <listitem><para><emphasis><filename>do_configure</filename>:</emphasis> This task configures the source by enabling and disabling any build-time and configuration options for @@ -1054,7 +1067,7 @@ <para> Package installation is under control of the package manager - (e.g. smart/rpm, opkg, or apt/dpkg) regardless of whether or + (e.g. dnf/rpm, opkg, or apt/dpkg) regardless of whether or not package management is enabled for the target. At the end of the process, if package management is not enabled for the target, the package manager's data files @@ -1392,17 +1405,6 @@ relationship the function needs to be passed. The function returns a True or False value. </para> - - <para> - Once the setscene process completes, the OpenEmbedded build - system has a list of tasks that it believes it can "accelerate" - and therefore does not need to run. - There is a final function call to the function specified by the - <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_SETSCENE_VERIFY_FUNCTION2'><filename>BB_SETSCENE_VERIFY_FUNCTION2</filename></ulink> - variable that is able to require the tasks to be run that - that the OpenEmbedded build system initially was going to - skip. - </para> </section> </section> @@ -1521,23 +1523,26 @@ the environment before using the tools. </para> - <note> - <para> - The Yocto Project supports several methods by which you can - set up this cross-development environment. - These methods include downloading pre-built SDK installers - or building and installing your own SDK installer. - </para> - - <para> - For background information on cross-development toolchains - in the Yocto Project development environment, see the - "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>" - section. - For information on setting up a cross-development - environment, see the - <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-manual'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>. - </para> + <note><title>Notes</title> + <itemizedlist> + <listitem><para> + The Yocto Project supports several methods by which you can + set up this cross-development environment. + These methods include downloading pre-built SDK installers + or building and installing your own SDK installer. + </para></listitem> + <listitem><para> + For background information on cross-development toolchains + in the Yocto Project development environment, see the + "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>" + section. + </para></listitem> + <listitem><para> + For information on setting up a cross-development + environment, see the + <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>. + </para></listitem> + </itemizedlist> </note> <para> diff --git a/import-layers/yocto-poky/documentation/ref-manual/introduction.xml b/import-layers/yocto-poky/documentation/ref-manual/introduction.xml index ddf6a860eb..eec6cb34f1 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/introduction.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/introduction.xml @@ -296,7 +296,7 @@ Yocto Project documentation manuals: <literallayout class='monospaced'> $ sudo dnf install make docbook-style-dsssl docbook-style-xsl \ - docbook-dtds docbook-utils fop libxslt dblatex xmlto xsltproc + docbook-dtds docbook-utils fop libxslt dblatex xmlto </literallayout></para></listitem> <listitem><para><emphasis>OpenEmbedded Self-Test (<filename>oe-selftest</filename>):</emphasis> Packages needed if you are going to run @@ -333,7 +333,7 @@ Packages needed if you are going to build out the Yocto Project documentation manuals: <literallayout class='monospaced'> - $ sudo zypper install make fop xsltproc dblatex xmlto + $ sudo zypper install make dblatex xmlto </literallayout></para></listitem> <listitem><para><emphasis>OpenEmbedded Self-Test (<filename>oe-selftest</filename>):</emphasis> Packages needed if you are going to run @@ -351,25 +351,33 @@ <para> The following list shows the required packages by function given a supported CentOS Linux distribution: - <note> - For CentOS 6.x, some of the versions of the components - provided by the distribution are too old (e.g. Git, Python, - and tar). - It is recommended that you install the buildtools in order - to provide versions that will work with the OpenEmbedded - build system. - For information on how to install the buildtools tarball, - see the - "<link linkend='required-git-tar-and-python-versions'>Required Git, Tar, and Python Versions</link>" - section. - </note> <itemizedlist> <listitem><para><emphasis>Essentials:</emphasis> Packages needed to build an image for a headless system: <literallayout class='monospaced'> - $ sudo yum install &CENTOS_HOST_PACKAGES_ESSENTIAL; - </literallayout></para></listitem> + $ sudo yum install &CENTOS_HOST_PACKAGES_ESSENTIAL; SDL-devel xterm + </literallayout> + <note><title>Notes</title> + <itemizedlist> + <listitem><para> + Extra Packages for Enterprise Linux + (i.e. <filename>epel-release</filename>) + is a collection of packages from Fedora + built on RHEL/CentOS for easy installation + of packages not included in enterprise + Linux by default. + You need to install these packages + separately. + </para></listitem> + <listitem><para> + The <filename>makecache</filename> command + consumes additional Metadata from + <filename>epel-release</filename>. + </para></listitem> + </itemizedlist> + </note> + </para></listitem> <listitem><para><emphasis>Graphical and Eclipse Plug-In Extras:</emphasis> Packages recommended if the host system has graphics support or if you are going to use the Eclipse @@ -382,7 +390,7 @@ Yocto Project documentation manuals: <literallayout class='monospaced'> $ sudo yum install make docbook-style-dsssl docbook-style-xsl \ - docbook-dtds docbook-utils fop libxslt dblatex xmlto xsltproc + docbook-dtds docbook-utils fop libxslt dblatex xmlto </literallayout></para></listitem> <listitem><para><emphasis>OpenEmbedded Self-Test (<filename>oe-selftest</filename>):</emphasis> Packages needed if you are going to run diff --git a/import-layers/yocto-poky/documentation/ref-manual/migration.xml b/import-layers/yocto-poky/documentation/ref-manual/migration.xml index 2bdb542ec1..7ca929c140 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/migration.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/migration.xml @@ -3689,7 +3689,7 @@ $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64. by <filename>BB_SETSCENE_VERIFY_FUNCTION</filename> needed to change signature. Consequently, a new variable named - <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_SETSCENE_VERIFY_FUNCTION2'><filename>BB_SETSCENE_VERIFY_FUNCTION2</filename></ulink> + <filename>BB_SETSCENE_VERIFY_FUNCTION2</filename> has been added allowing multiple versions of BitBake to work with suitably written metadata, which includes OpenEmbedded-Core and Poky. @@ -3955,6 +3955,768 @@ $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64. </section> </section> +<section id='moving-to-the-yocto-project-2.3-release'> + <title>Moving to the Yocto Project 2.3 Release</title> + + <para> + This section provides migration information for moving to the + Yocto Project 2.3 Release from the prior release. + </para> + + <section id='migration-2.3-recipe-specific-sysroots'> + <title>Recipe-specific Sysroots</title> + + <para> + The OpenEmbedded build system now uses one sysroot per + recipe to resolve long-standing issues with configuration + script auto-detection of undeclared dependencies. + Consequently, you might find that some of your previously + written custom recipes are missing declared dependencies, + particularly those dependencies that are incidentally built + earlier in a typical build process and thus are already likely + to be present in the shared sysroot in previous releases. + </para> + + <para> + Consider the following: + <itemizedlist> + <listitem><para> + <emphasis>Declare Build-Time Dependencies:</emphasis> + Because of this new feature, you must explicitly + declare all build-time dependencies for your recipe. + If you do not declare these dependencies, they are not + populated into the sysroot for the recipe. + </para></listitem> + <listitem><para> + <emphasis>Specify Pre-Installation and Post-Installation + Native Tool Dependencies:</emphasis> + You must specifically specify any special native tool + dependencies of <filename>pkg_preinst</filename> and + <filename>pkg_postinst</filename> scripts by using the + <link linkend='var-PACKAGE_WRITE_DEPS'><filename>PACKAGE_WRITE_DEPS</filename></link> + variable. + Specifying these dependencies ensures that these tools + are available if these scripts need to be run on the + build host during the + <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link> + task.</para> + + <para>As an example, see the <filename>dbus</filename> + recipe. + You will see that this recipe has a + <filename>pkg_postinst</filename> that calls + <filename>systemctl</filename> if "systemd" is in + <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>. + In the example, + <filename>systemd-systemctl-native</filename> is added to + <filename>PACKAGE_WRITE_DEPS</filename>, which is also + conditional on "systemd" being in + <filename>DISTRO_FEATURES</filename>. + </para></listitem> + <listitem><para> + <emphasis>Examine Recipes that Use + <filename>SSTATEPOSTINSTFUNCS</filename>:</emphasis> + You need to examine any recipe that uses + <filename>SSTATEPOSTINSTFUNCS</filename> and determine + steps to take.</para> + + <para>Functions added to + <filename>SSTATEPOSTINSTFUNCS</filename> are still + called as they were in previous Yocto Project releases. + However, since a separate sysroot is now being populated + for every recipe and if existing functions being called + through <filename>SSTATEPOSTINSTFUNCS</filename> are + doing relocation, then you will need to change these + to use a post-installation script that is installed by a + function added to + <link linkend='var-SYSROOT_PREPROCESS_FUNCS'><filename>SYSROOT_PREPROCESS_FUNCS</filename></link>. + </para> + + <para>For an example, see the + <filename>pixbufcache</filename> class in + <filename>meta/classes/</filename> in the Yocto Project + <ulink url='&YOCTO_DOCS_DEV_URL;#source-repositories'>Source Repositories</ulink>. + <note> + The <filename>SSTATEPOSTINSTFUNCS</filename> variable + itself is now deprecated in favor of the + <filename>do_populate_sysroot[postfuncs]</filename> + task. + Consequently, if you do still have any function or + functions that need to be called after the sysroot + component is created for a recipe, then you would be + well advised to take steps to use a post installation + script as described previously. + Taking these steps prepares your code for when + <filename>SSTATEPOSTINSTFUNCS</filename> is + removed in a future Yocto Project release. + </note> + </para></listitem> + <listitem><para> + <emphasis>Specify the Sysroot when Using Certain + External Scripts:</emphasis> + Because the shared sysroot is now gone, the scripts + <filename>oe-find-native-sysroot</filename> and + <filename>oe-run-native</filename> have been changed such + that you need to specify which recipe's + <link linkend='var-STAGING_DIR_NATIVE'><filename>STAGING_DIR_NATIVE</filename></link> + is used. + </para></listitem> + </itemizedlist> + <note> + You can find more information on how recipe-specific sysroots + work in the + "<link linkend='ref-classes-staging'><filename>staging.bbclass</filename></link>" + section. + </note> + </para> + </section> + + <section id='migration-2.3-path-variable'> + <title><filename>PATH</filename> Variable</title> + + <para> + Within the environment used to run build tasks, the environment + variable <filename>PATH</filename> is now sanitized such that + the normal native binary paths + (<filename>/bin</filename>, <filename>/sbin</filename>, + <filename>/usr/bin</filename> and so forth) are + removed and a directory containing symbolic links linking only + to the binaries from the host mentioned in the + <link linkend='var-HOSTTOOLS'><filename>HOSTTOOLS</filename></link> + and + <link linkend='var-HOSTTOOLS_NONFATAL'><filename>HOSTTOOLS_NONFATAL</filename></link> + variables is added to <filename>PATH</filename>. + </para> + + <para> + Consequently, any native binaries provided by the host that you + need to call needs to be in one of these two variables at + the configuration level. + </para> + + <para> + Alternatively, you can add a native recipe (i.e. + <filename>-native</filename>) that provides the + binary to the recipe's + <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link> + value. + <note> + <filename>PATH</filename> is not sanitized in the same way + within <filename>devshell</filename>. + If it were, you would have difficulty running host tools for + development and debugging within the shell. + </note> + </para> + </section> + + <section id='migration-2.3-scripts'> + <title>Changes to Scripts</title> + + <para> + The following changes to scripts took place: + <itemizedlist> + <listitem><para> + <emphasis><filename>oe-find-native-sysroot</filename>:</emphasis> + The usage for the + <filename>oe-find-native-sysroot</filename> script has + changed to the following: + <literallayout class='monospaced'> + $ . oe-find-native-sysroot <replaceable>recipe</replaceable> + </literallayout> + You must now supply a recipe for + <replaceable>recipe</replaceable> as part of the command. + Prior to the Yocto Project &DISTRO; release, it was not + necessary to provide the script with the command. + </para></listitem> + <listitem><para> + <emphasis><filename>oe-run-native</filename>:</emphasis> + The usage for the + <filename>oe-run-native</filename> script has changed + to the following: + <literallayout class='monospaced'> + $ oe-run-native <replaceable>native_recipe</replaceable> <replaceable>tool</replaceable> + </literallayout> + You must supply the name of the native recipe and the tool + you want to run as part of the command. + Prior to the Yocto Project &DISTRO; release, it was not + necessary to provide the native recipe with the command. + </para></listitem> + <listitem><para> + <emphasis><filename>cleanup-workdir</filename>:</emphasis> + The <filename>cleanup-workdir</filename> script has been + removed because the script was found to be deleting + files it should not have, which lead to broken build + trees. + Rather than trying to delete portions of + <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> + and getting it wrong, it is recommended that you + delete <filename>TMPDIR</filename> and have it restored + from shared state (sstate) on subsequent builds. + </para></listitem> + <listitem><para> + <emphasis><filename>wipe-sysroot</filename>:</emphasis> + The <filename>wipe-sysroot</filename> script has been + removed as it is no longer needed with recipe-specific + sysroots. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.3-functions'> + <title>Changes to Functions</title> + + <para> + The previously deprecated + <filename>bb.data.getVar()</filename>, + <filename>bb.data.setVar()</filename>, and + related functions have been removed in favor of + <filename>d.getVar()</filename>, + <filename>d.setVar()</filename>, and so forth. + </para> + + <para> + You need to fix any references to these old functions. + </para> + </section> + + <section id='migration-2.3-bitbake-changes'> + <title>BitBake Changes</title> + + <para> + The following changes took place for BitBake: + <itemizedlist> + <listitem><para> + <emphasis>BitBake's Graphical Dependency Explorer UI Replaced:</emphasis> + BitBake's graphical dependency explorer UI + <filename>depexp</filename> was replaced by + <filename>taskexp</filename> ("Task Explorer"), which + provides a graphical way of exploring the + <filename>task-depends.dot</filename> file. + The data presented by Task Explorer is much more + accurate than the data that was presented by + <filename>depexp</filename>. + Being able to visualize the data is an often requested + feature as standard <filename>*.dot</filename> file + viewers cannot usual cope with the size of + the <filename>task-depends.dot</filename> file. + </para></listitem> + <listitem><para> + <emphasis>BitBake "-g" Output Changes:</emphasis> + The <filename>package-depends.dot</filename> and + <filename>pn-depends.dot</filename> files as previously + generated using the <filename>bitbake -g</filename> command + have been removed. + A <filename>recipe-depends.dot</filename> file + is now generated as a collapsed version of + <filename>task-depends.dot</filename> instead. + </para> + + <para>The reason for this change is because + <filename>package-depends.dot</filename> and + <filename>pn-depends.dot</filename> largely date back + to a time before task-based execution and do not take + into account task-level dependencies between recipes, + which could be misleading. + </para></listitem> + <listitem><para> + <emphasis>Mirror Variable Splitting Changes:</emphasis> + Mirror variables including + <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>, + <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>, + and + <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link> + can now separate values entirely with spaces. + Consequently, you no longer need "\\n". + BitBake looks for pairs of values, which simplifies usage. + There should be no change required to existing mirror + variable values themselves. + </para></listitem> + <listitem><para> + <emphasis>The Subversion (SVN) Fetcher Uses an "ssh" Parameter and Not an "rsh" Parameter:</emphasis> + The SVN fetcher now takes an "ssh" parameter instead of an + "rsh" parameter. + This new optional parameter is used when the "protocol" + parameter is set to "svn+ssh". + You can only use the new parameter to specify the + <filename>ssh</filename> program used by SVN. + The SVN fetcher passes the new parameter through the + <filename>SVN_SSH</filename> environment variable during + the + <link linkend='ref-tasks-fetch'><filename>do_fetch</filename></link> + task.</para> + + <para>See the + "<ulink url='&YOCTO_DOCS_BB_URL;#svn-fetcher'>Subversion (SVN) Fetcher (svn://)</ulink>" + section in the Yocto Project BitBake User Manual for + additional information. + </para></listitem> + <listitem><para> + <emphasis><filename>BB_SETSCENE_VERIFY_FUNCTION</filename> + and <filename>BB_SETSCENE_VERIFY_FUNCTION2</filename> + Removed:</emphasis> + Because the mechanism they were part of is no longer + necessary with recipe-specific sysroots, the + <filename>BB_SETSCENE_VERIFY_FUNCTION</filename> and + <filename>BB_SETSCENE_VERIFY_FUNCTION2</filename> + variables have been removed. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.3-absolute-symlinks'> + <title>Absolute Symbolic Links</title> + + <para> + Absolute symbolic links (symlinks) within staged files are no + longer permitted and now trigger an error. + Any explicit creation of symlinks can use the + <filename>lnr</filename> script, which is a replacement for + <filename>ln -r</filename>. + </para> + + <para> + If the build scripts in the software that the recipe is building + are creating a number of absolute symlinks that need to be + corrected, you can inherit + <filename>relative_symlinks</filename> within the recipe to turn + those absolute symlinks into relative symlinks. + </para> + </section> + + <section id='migration-2.3-gplv2-and-gplv3-moves'> + <title>GPLv2 Versions of GPLv3 Recipes Moved</title> + + <para> + Older GPLv2 versions of GPLv3 recipes have moved to a + separate <filename>meta-gplv2</filename> layer. + </para> + + <para> + If you use + <link linkend='var-INCOMPATIBLE_LICENSE'><filename>INCOMPATIBLE_LICENSE</filename></link> + to exclude GPLv3 or set + <link linkend='var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></link> + to substitute a GPLv2 version of a GPLv3 recipe, then you must add + the <filename>meta-gplv2</filename> layer to your configuration. + <note> + You can find <filename>meta-gplv2</filename> layer in the + OpenEmbedded layer index at + <ulink url='https://layers.openembedded.org/layerindex/branch/master/layer/meta-gplv2/'></ulink>. + </note> + </para> + + <para> + These relocated GPLv2 recipes do not receive the same level of + maintenance as other core recipes. + The recipes do not get security fixes and upstream no longer + maintains them. + In fact, the upstream community is actively hostile towards people + that use the old versions of the recipes. + Moving these recipes into a separate layer both makes the different + needs of the recipes clearer and clearly identifies the number of + these recipes. + <note> + The long-term solution might be to move to BSD-licensed + replacements of the GPLv3 components for those that need to + exclude GPLv3-licensed components from the target system. + This solution will be investigated for future Yocto + Project releases. + </note> + </para> + </section> + + <section id='migration-2.3-package-management-changes'> + <title>Package Management Changes</title> + + <para> + The following package management changes took place: + <itemizedlist> + <listitem><para> + Smart package manager is replaced by DNF package manager. + Smart has become unmaintained upstream, is not ported + to Python 3.x. + Consequently, Smart needed to be replaced. + DNF is the only feasible candidate.</para> + <para>The change in functionality is that the on-target + runtime package management from remote package feeds is + now done with a different tool that has a + different set of command-line options. + If you have scripts that call the + tool directly, or use its API, they need to be fixed.</para> + <para>For more information, see the + <ulink url='http://dnf.readthedocs.io/en/latest/'>DNF Documentation</ulink>. + </para></listitem> + <listitem><para> + Rpm 5.x is replaced with Rpm 4.x. + This is done for two major reasons: + <itemizedlist> + <listitem><para> + DNF is API-incompatible with Rpm 5.x and porting + it and maintaining the port is non-trivial. + </para></listitem> + <listitem><para> + Rpm 5.x itself has limited maintenance upstream, + and the Yocto Project is one of the very few + remaining users. + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para> + Berkeley DB 6.x is removed and Berkeley DB 5.x becomes + the default: + <itemizedlist> + <listitem><para> + Version 6.x of Berkeley DB has largely been + rejected by the open source community due to its + AGPLv3 license. + As a result, most mainstream open source projects + that require DB are still developed and tested with + DB 5.x. + </para></listitem> + <listitem><para> + In OE-core, the only thing that was requiring + DB 6.x was Rpm 5.x. + Thus, no reason exists to continue carrying DB 6.x + in OE-core. + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para> + <filename>createrepo</filename> is replaced with + <filename>createrepo_c</filename>.</para> + <para><filename>createrepo_c</filename> is the current + incarnation of the tool that generates remote repository + metadata. + It is written in C as compared to + <filename>createrepo</filename>, which is written in + Python. + <filename>createrepo_c</filename> is faster and is + maintained. + </para></listitem> + <listitem><para> + Architecture-independent RPM packages are "noarch" + instead of "all".</para> + <para>This change was made because too many places in + DNF/RPM4 stack already make that assumption. + Only the filenames and the architecture tag has changed. + Nothing else has changed in OE-core system, particularly + in the + <link linkend='ref-classes-allarch'><filename>allarch.bbclass</filename></link> + class. + </para></listitem> + <listitem><para> + Signing of remote package feeds using + <filename>PACKAGE_FEED_SIGN</filename> + is not currently supported. + This issue will be fully addressed in a future + Yocto Project release. + See <ulink url='https://bugzilla.yoctoproject.org/show_bug.cgi?id=11209'>defect 11209</ulink> + for more information on a solution to package feed + signing with RPM in the Yocto Project 2.3 release. + </para></listitem> + <listitem><para> + OPKG now uses the libsolv backend for resolving package + dependencies by default. + This is vastly superior to OPKG's internal ad-hoc solver + that was previously used. + This change does have a small impact on disk (around + 500 KB) and memory footprint. + <note> + For further details on this change, see the + <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/? +id=f4d4f99cfbc2396e49c1613a7d237b9e57f06f81'>commit message</ulink>. + </note> + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.3-removed-recipes'> + <title>Removed Recipes</title> + + <para> + The following recipes have been removed: + <itemizedlist> + <listitem><para> + <emphasis><filename>linux-yocto 4.8:</filename></emphasis> + Version 4.8 has been removed. + Versions 4.1 (LTSI), 4.4 (LTS), 4.9 (LTS/LTSI) and 4.10 + are now present. + </para></listitem> + <listitem><para> + <emphasis><filename>python-smartpm:</filename></emphasis> + Functionally replaced by <filename>dnf</filename>. + </para></listitem> + <listitem><para> + <emphasis><filename>createrepo:</filename></emphasis> + Replaced by the <filename>createrepo-c</filename> recipe. + </para></listitem> + <listitem><para> + <emphasis><filename>rpmresolve:</filename></emphasis> + No longer needed with the move to RPM 4 as RPM itself is + used instead. + </para></listitem> + <listitem><para> + <emphasis><filename>gstreamer:</filename></emphasis> + Removed the GStreamer Git version recipes as they have + been stale. + <filename>1.10.</filename><replaceable>x</replaceable> + recipes are still present. + </para></listitem> + <listitem><para> + <emphasis><filename>alsa-conf-base:</filename></emphasis> + Merged into <filename>alsa-conf</filename> since + <filename>libasound</filename> depended on both. + Essentially, no way existed to install only one of these. + </para></listitem> + <listitem><para> + <emphasis><filename>tremor:</filename></emphasis> + Moved to <filename>meta-multimedia</filename>. + Fixed-integer Vorbis decoding is not + needed by current hardware. + Thus, GStreamer's ivorbis plugin has been disabled + by default eliminating the need for the + <filename>tremor</filename> recipe in OE-Core. + </para></listitem> + <listitem><para> + <emphasis><filename>gummiboot:</filename></emphasis> + Replaced by <filename>systemd-boot</filename>. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.3-wic-changes'> + <title>Wic Changes</title> + + <para> + The following changes have been made to Wic: + <note> + For more information on Wic, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-partitioned-images'>Creating Partitioned Images</ulink>" + section in the Yocto Project Development Manual. + </note> + <itemizedlist> + <listitem><para> + <emphasis>Default Output Directory Changed:</emphasis> + Wic's default output directory is now the current directory + by default instead of the unusual + <filename>/var/tmp/wic</filename>.</para> + + <para>The "-o" and "--outdir" options remain unchanged + and are used to specify your preferred output directory + if you do not want to use the default directory. + </para></listitem> + <listitem><para> + <emphasis>fsimage Plug-in Removed:</emphasis> + The Wic fsimage plug-in has been removed as it duplicates + functionality of the rawcopy plug-in. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.3-qa-changes'> + <title>QA Changes</title> + + <para> + The following QA checks have changed: + <itemizedlist> + <listitem><para> + <emphasis><filename>unsafe-references-in-binaries</filename>:</emphasis> + The <filename>unsafe-references-in-binaries</filename> + QA check, which was disabled by default, has now been + removed. + This check was intended to detect binaries in + <filename>/bin</filename> that link to libraries in + <filename>/usr/lib</filename> and have the case where + the user has <filename>/usr</filename> on a separate + filesystem to <filename>/</filename>.</para> + + <para>The removed QA check was buggy. + Additionally, <filename>/usr</filename> residing on a + separate partition from <filename>/</filename> is now + a rare configuration. + Consequently, + <filename>unsafe-references-in-binaries</filename> was + removed. + </para></listitem> + <listitem><para> + <emphasis><filename>file-rdeps</filename>:</emphasis> + The <filename>file-rdeps</filename> QA check is now an + error by default instead of a warning. + Because it is an error instead of a warning, you need to + address missing runtime dependencies.</para> + + <para>For additional information, see the + <link linkend='ref-classes-insane'><filename>insane</filename></link> + class and the + "<link linkend='qa-errors-and-warnings'>Errors and Warnings</link>" + section. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.3-miscellaneous-changes'> + <title>Miscellaneous Changes</title> + + <para> + The following miscellaneous changes have occurred: + <itemizedlist> + <listitem><para> + In this release, a number of recipes have been changed to + ignore the <filename>largefile</filename> + <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link> + item, enabling large file support unconditionally. + This feature has always been enabled by default. + Disabling the feature has not been widely tested. + <note> + Future releases of the Yocto Project will remove + entirely the ability to disable the + <filename>largefile</filename> feature, + which would make it unconditionally enabled everywhere. + </note> + </para></listitem> + <listitem><para> + If the + <link linkend='var-DISTRO_VERSION'><filename>DISTRO_VERSION</filename></link> + value contains the value of the + <link linkend='var-DATE'><filename>DATE</filename></link> + variable, which is the default between Poky releases, + the <filename>DATE</filename> value is explicitly excluded + from <filename>/etc/issue</filename> and + <filename>/etc/issue.net</filename>, which is displayed at + the login prompt, in order to avoid conflicts with + Multilib enabled. + Regardless, the <filename>DATE</filename> value is + inaccurate if the <filename>base-files</filename> + recipe is restored from shared state (sstate) rather + than rebuilt.</para> + + <para>If you need the build date recorded in + <filename>/etc/issue*</filename> or anywhere else in your + image, a better method is to define a post-processing + function to do it and have the function called from + <link linkend='var-ROOTFS_POSTPROCESS_COMMAND'><filename>ROOTFS_POSTPROCESS_COMMAND</filename></link>. + Doing so ensures the value is always up-to-date with the + created image. + </para></listitem> + <listitem><para> + Dropbear's <filename>init</filename> script now disables + DSA host keys by default. + This change is in line with the systemd service + file, which supports RSA keys only, and with recent + versions of OpenSSH, which deprecates DSA host keys. + </para></listitem> + <listitem><para> + The + <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link> + class now correctly uses tabs as separators between all + columns in <filename>installed-package-sizes.txt</filename> + in order to aid import into other tools. + </para></listitem> + <listitem><para> + The <filename>USE_LDCONFIG</filename> variable has been + replaced with the "ldconfig" + <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link> + feature. + Distributions that previously set: + <literallayout class='monospaced'> + USE_LDCONFIG = "0" + </literallayout> + should now instead use the following: + <literallayout class='monospaced'> + DISTRO_FEATURES_BACKFILL_CONSIDERED_append = " ldconfig" + </literallayout> + </para></listitem> + <listitem><para> + The default value of + <link linkend='var-COPYLEFT_LICENSE_INCLUDE'><filename>COPYLEFT_LICENSE_INCLUDE</filename></link> + now includes all versions of AGPL licenses in addition + to GPL and LGPL. + <note> + The default list is not intended to be guaranteed + as a complete safe list. + You should seek legal advice based on what you are + distributing if you are unsure. + </note> + </para></listitem> + <listitem><para> + Kernel module packages are now suffixed with the kernel + version in order to allow module packages from multiple + kernel versions to co-exist on a target system. + If you wish to return to the previous naming scheme + that does not include the version suffix, use the + following: + <literallayout class='monospaced'> + KERNEL_MODULE_PACKAGE_SUFFIX to "" + </literallayout> + </para></listitem> + <listitem><para> + Removal of <filename>libtool</filename> + <filename>*.la</filename> files is now enabled by default. + The <filename>*.la</filename> files are not actually + needed on Linux and relocating them is an unnecessary + burden.</para> + + <para>If you need to preserve these + <filename>.la</filename> files (e.g. in a custom + distribution), you must change + <link linkend='var-INHERIT_DISTRO'><filename>INHERIT_DISTRO</filename></link> + such that "remove-libtool" is not included in the value. + </para></listitem> + <listitem><para> + Extensible SDKs built for GCC 5+ now refuse to install on a + distribution where the host GCC version is 4.8 or 4.9. + This change resulted from the fact that the installation + is known to fail due to the way the + <filename>uninative</filename> shared state (sstate) + package is built. + See the + <link linkend='ref-classes-uninative'><filename>uninative</filename></link> + class for additional information. + </para></listitem> + <listitem><para> + All native and nativesdk recipes now use a separate + <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link> + value instead of sharing the value used by recipes for the + target, in order to avoid unnecessary rebuilds.</para> + + <para>The <filename>DISTRO_FEATURES</filename> for + <filename>native</filename> recipes is + <link linkend='var-DISTRO_FEATURES_NATIVE'><filename>DISTRO_FEATURES_NATIVE</filename></link> + added to an intersection of + <filename>DISTRO_FEATURES</filename> and + <link linkend='var-DISTRO_FEATURES_FILTER_NATIVE'><filename>DISTRO_FEATURES_FILTER_NATIVE</filename></link>. + </para> + + <para>For nativesdk recipes, the + corresponding variables are + <link linkend='var-DISTRO_FEATURES_NATIVESDK'><filename>DISTRO_FEATURES_NATIVESDK</filename></link> + and + <link linkend='var-DISTRO_FEATURES_FILTER_NATIVESDK'><filename>DISTRO_FEATURES_FILTER_NATIVESDK</filename></link>. + </para></listitem> + <listitem><para> + The <filename>FILESDIR</filename> + variable, which was previously deprecated and rarely used, + has now been removed. + You should change any recipes that set + <filename>FILESDIR</filename> to set + <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link> + instead. + </para></listitem> + <listitem><para> + The <filename>MULTIMACH_HOST_SYS</filename> + variable has been removed as it is no longer needed + with recipe-specific sysroots. + </para></listitem> + </itemizedlist> + </para> + </section> +</section> </chapter> <!-- vim: expandtab tw=80 ts=4 diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-bitbake.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-bitbake.xml index 1de1148264..2f36e16eaf 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/ref-bitbake.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/ref-bitbake.xml @@ -414,7 +414,7 @@ Options: -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS Show debug logging for the specified logging domains -P, --profile Profile the command and save reports. - -u UI, --ui=UI The user interface to use (e.g. knotty and depexp). + -u UI, --ui=UI The user interface to use (e.g. knotty and taskexp). -t SERVERTYPE, --servertype=SERVERTYPE Choose which server to use, process or xmlrpc. --revisions-changed Set the exit code depending on whether upstream diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-classes.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-classes.xml index f7b1126d7c..c88162b3ba 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/ref-classes.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/ref-classes.xml @@ -1301,19 +1301,27 @@ <title><filename>image-live.bbclass</filename></title> <para> - The <filename>image-live</filename> class supports building "live" - images. + This class controls building "live" (i.e. HDDIMG and ISO) images. + Live images contain syslinux for legacy booting, as well as the + bootloader specified by + <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link> + if + <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link> + contains "efi". </para> <para> Normally, you do not use this class directly. Instead, you add "live" to <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>. + You can selectively build just one of these types through the + <link linkend='var-NOISO'><filename>NOISO</filename></link> + and + <link linkend='var-NOHDD'><filename>NOHDD</filename></link> variables. For example, if you were building an ISO image, you would add "live" to <filename>IMAGE_FSTYPES</filename>, set the - <link linkend='var-NOISO'><filename>NOISO</filename></link> variable to - "0" and the build system would use the <filename>image-live</filename> - class to build the ISO image. + <filename>NOISO</filename> variable to "0" and the build system would + use the <filename>image-live</filename> class to build the ISO image. </para> </section> @@ -1755,6 +1763,9 @@ <link linkend='qa-issue-textrel'><filename>ELF binary</filename></link> message for more information regarding runtime performance issues. </para></listitem> +<!-- +This check was removed for YP 2.3 release + <listitem><para><emphasis><filename>unsafe-references-in-binaries:</filename></emphasis> Reports when a binary installed in <filename>${base_libdir}</filename>, @@ -1776,6 +1787,7 @@ <filename>/usr</filename>. </note> </para></listitem> +--> <listitem><para><emphasis><filename>unsafe-references-in-scripts:</filename></emphasis> Reports when a script file installed in <filename>${base_libdir}</filename>, @@ -2216,6 +2228,14 @@ functionality specific to the respective native or target case.</para></listitem> </itemizedlist> + <note><title>Warning</title> + When creating a recipe, you must follow this naming convention: + <literallayout class='monospaced'> + native-<replaceable>myrecipe</replaceable>.bb + </literallayout> + Not doing so can lead to subtle problems because code exists + that depends on the naming convention. + </note> </para> <para> @@ -2258,6 +2278,14 @@ functionality specific to the respective SDK machine or target case.</para></listitem> </itemizedlist> + <note><title>Warning</title> + When creating a recipe, you must follow this naming convention: + <literallayout class='monospaced'> + nativesdk-<replaceable>myrecipe</replaceable>.bb + </literallayout> + Not doing so can lead to subtle problems because code exists + that depends on the naming convention. + </note> </para> <para> @@ -2374,7 +2402,7 @@ <para> If you take the optional step to set up a repository (package feed) - on the development host that can be used by Smart, you can + on the development host that can be used by DNF, you can install packages from the feed while you are running the image on the target (i.e. runtime installation of packages). For more information, see the @@ -3190,13 +3218,144 @@ <title><filename>staging.bbclass</filename></title> <para> - The <filename>staging</filename> class provides the - <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link> - task, which stages files into the sysroot to make them available to - other recipes at build time. - The class is enabled by default because it is inherited by the - <link linkend='ref-classes-base'><filename>base</filename></link> - class. + The <filename>staging</filename> class installs files into individual + recipe work directories for sysroots. + The class contains the following key tasks: + <itemizedlist> + <listitem><para> + The + <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link> + task, which is responsible for handing the files that end up + in the recipe sysroots. + </para></listitem> + <listitem><para> + The + <link linkend='ref-tasks-prepare_recipe_sysroot'><filename>do_prepare_recipe_sysroot</filename></link> + task (a "partner" task to the + <filename>populate_sysroot</filename> task), which installs + the files into the individual recipe work directories (i.e. + <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>). + </para></listitem> + </itemizedlist> + </para> + + <para> + The code in the <filename>staging</filename> class is complex and + basically works in two stages: + <itemizedlist> + <listitem><para> + <emphasis>Stage One:</emphasis> + The first stage addresses recipes that have files they want + to share with other recipes that have dependencies on the + originating recipe. + Normally these dependencies are installed through the + <link linkend='ref-tasks-install'><filename>do_install</filename></link> + task into + <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename>. + The <filename>do_populate_sysroot</filename> task copies + a subset of these files into + <filename>${SYSROOT_DESTDIR}</filename>. + This subset of files is controlled by the + <link linkend='var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></link>, + <link linkend='var-SYSROOT_DIRS_NATIVE'><filename>SYSROOT_DIRS_NATIVE</filename></link>, + and + <link linkend='var-SYSROOT_DIRS_BLACKLIST'><filename>SYSROOT_DIRS_BLACKLIST</filename></link> + variables. + <note> + Additionally, a recipe can customize the files further by + declaring a processing function in the + <link linkend='var-SYSROOT_PREPROCESS_FUNCS'><filename>SYSROOT_PREPROCESS_FUNCS</filename></link> + variable. + </note> + </para> + + <para> + A shared state (sstate) object is built from these files + and the files are placed into a subdirectory of + <link linkend='structure-build-tmp-sysroots-components'><filename>tmp/sysroots-components/</filename></link>. + The files are scanned for hardcoded paths to the original + installation location. + If the location is found in text files, the hardcoded + locations are replaced by tokens and a list of the files + needing such replacements is created. + These adjustments are referred to as "FIXMEs". + The list of files that are scanned for paths is controlled by + the + <link linkend='var-SSTATE_SCAN_FILES'><filename>SSTATE_SCAN_FILES</filename></link> + variable. + </para></listitem> + <listitem><para> + <emphasis>Stage Two:</emphasis> + The second stage addresses recipes that want to use something + from another recipe and declare a dependency on that recipe + through the + <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link> + variable. + The recipe will have a + <link linkend='ref-tasks-prepare_recipe_sysroot'><filename>do_prepare_recipe_sysroot</filename></link> + task and when + this task executes, it creates the + <filename>recipe-sysroot</filename> and + <filename>recipe-sysroot-native</filename> in the recipe + work directory (i.e. + <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>). + The OpenEmbedded build system creates hard links to copies of the + relevant files from <filename>sysroots-components</filename> + into the recipe work directory. + <note> + If hard links are not possible, the build system uses + actual copies. + </note> + The build system then addresses any "FIXMEs" to paths as + defined from the list created in the first stage. + </para> + + <para> + Finally, any files in <filename>${bindir}</filename> + within the sysroot that have the prefix + "<filename>postinst-</filename>" are executed. + <note> + Although such sysroot post installation scripts are not + recommended for general use, the files do allow some issues + such as user creation and module indexes to be addressed. + </note> + </para> + + <para> + Because recipes can have other dependencies outside of + <filename>DEPENDS</filename> (e.g. + <filename>do_unpack[depends] += "tar-native:do_populate_sysroot"</filename>), + the sysroot creation function + <filename>extend_recipe_sysroot</filename> is also added as + a pre-function for those tasks whose dependencies are not + through <filename>DEPENDS</filename> but operate similarly. + </para> + + <para> + When installing dependencies into the sysroot, the code + traverses the dependency graph and processes dependencies + in exactly the same way as the dependencies would or would not + be when installed from sstate. + This processing means, for example, a native tool would have + its native dependencies added but a target library would not + have its dependencies traversed or installed. + The same sstate dependency code is used so that + builds should be identical regardless of whether sstate + was used or not. + For a closer look, see the + <filename>setscene_depvalid()</filename> function in the + <link linkend='ref-classes-sstate'><filename>sstate</filename></link> + class. + </para> + + <para> + The build system is careful to maintain manifests of the files + it installs so that any given dependency can be installed as + needed. + The sstate hash of the installed item is also stored so that + if it changes, the build system can reinstall it. + </para></listitem> + </itemizedlist> </para> </section> @@ -3532,6 +3691,14 @@ For an example, see the <filename>meta/conf/distro/include/yocto-uninative.inc</filename>. </para> + + <para> + The <filename>uninative</filename> class is also used unconditionally + by the extensible SDK. + When building the extensible SDK, + <filename>uninative-tarball</filename> is built and the resulting + tarball is included within the SDK. + </para> </section> <section id='ref-classes-update-alternatives'> diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-devtool-reference.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-devtool-reference.xml index 1764f0196f..99d5a52a0f 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/ref-devtool-reference.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/ref-devtool-reference.xml @@ -215,6 +215,17 @@ The <filename>.bbappend</filename> file is created to point to the external source tree. </para> + + <note> + If your recipe has runtime dependencies defined, you must be sure + that these packages exist on the target hardware before attempting + to run your application. + If dependent packages (e.g. libraries) do not exist on the target, + your application, when run, will fail to find those functions. + For more information, see the + "<link linkend='devtool-deploying-your-software-on-the-target-machine'>Deploying Your Software on the Target Machine</link>" + section. + </note> </section> <section id='devtool-extracting-the-source-for-an-existing-recipe'> @@ -501,6 +512,40 @@ </para> </note> </para> + + <para> + Some conditions exist that could prevent a deployed application + from behaving as expected. + When both of the following conditions exist, your application has + the potential to not behave correctly when run on the target: + <itemizedlist> + <listitem><para> + You are deploying a new application to the target and + the recipe you used to build the application had + correctly defined runtime dependencies. + </para></listitem> + <listitem><para> + The target does not physically have the packages on which + the application depends installed. + </para></listitem> + </itemizedlist> + If both of these conditions exist, your application will not + behave as expected. + The reason for this misbehavior is because the + <filename>devtool deploy-target</filename> command does not deploy + the packages (e.g. libraries) on which your new application + depends. + The assumption is that the packages are already on the target. + Consequently, when a runtime call is made in the application + for a dependent function (e.g. a library call), the function + cannot be found. + </para> + + <para> + To be sure you have all the dependencies local to the target, you + need to be sure that the packages are pre-deployed (installed) + on the target before attempting to run your application. + </para> </section> <section id='devtool-removing-your-software-from-the-target-machine'> diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-features.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-features.xml index 282a517191..7e1c5ef2f1 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/ref-features.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/ref-features.xml @@ -195,6 +195,10 @@ <listitem><para><emphasis>keyboard:</emphasis> Include keyboard support (e.g. keymaps will be loaded during boot). </para></listitem> + <listitem><para><emphasis>ldconfig:</emphasis> + Include support for ldconfig and + <filename>ld.so.conf</filename> on the target. + </para></listitem> <listitem><para><emphasis>nfs:</emphasis> Include NFS client support (for mounting NFS exports on device). </para></listitem> @@ -297,6 +301,12 @@ Enables logging postinstall script runs to the <filename>/var/log/postinstall.log</filename> file on first boot of the image on the target system. + <note> + To make the <filename>/var/log</filename> directory + on the target persistent, use the + <ulink url='&YOCTO_DOCS_REF_URL;#var-VOLATILE_LOG_DIR'><filename>VOLATILE_LOG_DIR</filename></ulink> + variable by setting it to "no". + </note> </para></listitem> <listitem><para><emphasis>ptest-pkgs:</emphasis> Installs ptest packages for all ptest-enabled recipes. diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-images.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-images.xml index 69b58f6ab4..f2209686f0 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/ref-images.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/ref-images.xml @@ -54,9 +54,6 @@ <listitem><para><filename>core-image-clutter</filename>: An image with support for the Open GL-based toolkit Clutter, which enables development of rich and animated graphical user interfaces.</para></listitem> - <listitem><para><filename>core-image-directfb</filename>: - An image that uses <filename>directfb</filename> instead of X11. - </para></listitem> <listitem><para><filename>core-image-full-cmdline</filename>: A console-only image with more full-featured Linux system functionality installed.</para></listitem> diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-manual.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-manual.xml index 47f64769c0..752b210152 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/ref-manual.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/ref-manual.xml @@ -108,14 +108,29 @@ <revremark>Released with the Yocto Project 2.2 Release.</revremark> </revision> <revision> - <revnumber>2.2.1</revnumber> - <date>January 2017</date> - <revremark>Released with the Yocto Project 2.2.1 Release.</revremark> + <revnumber>2.3</revnumber> + <date>May 2017</date> + <revremark>Released with the Yocto Project 2.3 Release.</revremark> </revision> <revision> - <revnumber>2.2.2</revnumber> + <revnumber>2.3.1</revnumber> <date>June 2017</date> - <revremark>Released with the Yocto Project 2.2.2 Release.</revremark> + <revremark>Released with the Yocto Project 2.3.1 Release.</revremark> + </revision> + <revision> + <revnumber>2.3.2</revnumber> + <date>September 2017</date> + <revremark>Released with the Yocto Project 2.3.2 Release.</revremark> + </revision> + <revision> + <revnumber>2.3.3</revnumber> + <date>January 2018</date> + <revremark>Released with the Yocto Project 2.3.3 Release.</revremark> + </revision> + <revision> + <revnumber>2.3.4</revnumber> + <date>April 2018</date> + <revremark>Released with the Yocto Project 2.3.4 Release.</revremark> </revision> </revhistory> @@ -129,12 +144,32 @@ Permission is granted to copy, distribute and/or modify this document under the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England & Wales</ulink> as published by Creative Commons. </para> - <note> - For the latest version of this manual associated with this - Yocto Project release, see the - <ulink url='&YOCTO_DOCS_REF_URL;'>Yocto Project Reference Manual</ulink> - from the Yocto Project website. - </note> + <note><title>Manual Notes</title> + <itemizedlist> + <listitem><para> + For the latest version of the Yocto Project Reference + Manual associated with this Yocto Project release + (version &YOCTO_DOC_VERSION;), + see the Yocto Project Reference Manual from the + <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>. + </para></listitem> + <listitem><para> + This version of the manual is version + &YOCTO_DOC_VERSION;. + For later releases of the Yocto Project (if they exist), + go to the + <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink> + and use the drop-down "Active Releases" button + and choose the Yocto Project version for which you want + the manual. + </para></listitem> + <listitem><para> + For an in-development version of the Yocto Project + Reference Manual, see + <ulink url='&YOCTO_DOCS_URL;/latest/ref-manual/ref-manual.html'></ulink>. + </para></listitem> + </itemizedlist> + </note> </legalnotice> </bookinfo> @@ -147,6 +182,8 @@ <xi:include href="technical-details.xml"/> + <xi:include href="ref-release-process.xml"/> + <xi:include href="migration.xml"/> <xi:include href="ref-structure.xml"/> diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-qa-checks.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-qa-checks.xml index 86456bd429..515106ae68 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/ref-qa-checks.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/ref-qa-checks.xml @@ -1170,45 +1170,6 @@ can be found then it should be implemented. I can't find one at the moment. </listitem> </itemizedlist> </para> - -<!-- -Here are some messages that might be documented in the future. -Right now we are not documenting them because the QA checks are not -enabled by default: - - <para> - <itemizedlist> - <listitem><para> - <literallayout class='monospaced'> - Desktop file issue: <error> [desktop] - </literallayout> - NEED A DESCRIPTION AND SOLUTION - </para></listitem> - </itemizedlist> - </para> - - <para> - <itemizedlist> - <listitem><para> - <literallayout class='monospaced'> - <packagename>: <file>, installed in the base_prefix, requires a shared library under exec_prefix (<exec_prefix&t;g) [unsafe-references-in-binaries] - </literallayout> - NEED A DESCRIPTION AND SOLUTION - </para></listitem> - </itemizedlist> - </para> - - <para> - <itemizedlist> - <listitem><para> - <literallayout class='monospaced'> - <packagename>: Found a reference to <exec_prefix>/ in <path> - Shell scripts in base_bindir and base_sbindir should not reference anything in exec_prefix [unsafe-references-in-scripts] - </literallayout> - NEED A DESCRIPTION AND SOLUTION - </para></listitem> - </itemizedlist> - </para> ---> </section> <section id='configuring-and-disabling-qa-checks'> diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-release-process.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-release-process.xml new file mode 100644 index 0000000000..fe3ba0933e --- /dev/null +++ b/import-layers/yocto-poky/documentation/ref-manual/ref-release-process.xml @@ -0,0 +1,254 @@ +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" +[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > + +<chapter id='ref-release-process'> +<title>Yocto Project Releases and the Stable Release Process</title> + +<para> + The Yocto Project release process is predictable and consists of both + major and minor (point) releases. + This brief chapter provides information on how releases are named, their + life cycle, and their stability. +</para> + +<section id='major-and-minor-release-cadence'> + <title>Major and Minor Release Cadence</title> + + <para> + The Yocto Project delivers major releases (e.g. &DISTRO;) using a six + month cadence roughly timed each April and October of the year. + Following are examples of some major YP releases with their codenames + also shown. + See the + "<link linkend='major-release-codenames'>Major Release Codenames</link>" + section for information on codenames used with major releases. + <literallayout class='monospaced'> + 2.2 (Morty) + 2.1 (Krogoth) + 2.0 (Jethro) + </literallayout> + While the cadence is never perfect, this timescale facilitates + regular releases that have strong QA cycles while not overwhelming + users with too many new releases. + The cadence is predictable and avoids many major holidays in various + geographies. + </para> + + <para> + The Yocto project delivers minor (point) releases on an unscheduled + basis and are usually driven by the accumulation of enough significant + fixes or enhancements to the associated major release. + Following are some example past point releases: + <literallayout class='monospaced'> + 2.1.1 + 2.1.2 + 2.2.1 + </literallayout> + The point release indicates a point in the major release branch where + a full QA cycle and release process validates the content of the new + branch. + <note> + Realize that there can be patches merged onto the stable release + branches as and when they become available. + </note> + </para> +</section> + +<section id='major-release-codenames'> + <title>Major Release Codenames</title> + + <para> + Each major release receives a codename that identifies the release in + the + <ulink url='&YOCTO_DOCS_DEV_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>. + The concept is that branches of + <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> + with the same codename are likely to be compatible and thus + work together. + <note> + Codenames are associated with major releases because a Yocto + Project release number (e.g. &DISTRO;) could conflict with + a given layer or company versioning scheme. + Codenames are unique, interesting, and easily identifiable. + </note> + Releases are given a nominal release version as well but the codename + is used in repositories for this reason. + You can find information on Yocto Project releases and codenames at + <ulink url='https://wiki.yoctoproject.org/wiki/Releases'></ulink>. + </para> +</section> + +<section id='stable-release-process'> + <title>Stable Release Process</title> + + <para> + Once released, the release enters the stable release process at which + time a person is assigned as the maintainer for that stable release. + This maintainer monitors activity for the release by investigating + and handling nominated patches and backport activity. + Only fixes and enhancements that have first been applied on the + "master" branch (i.e. the current, in-development branch) are + considered for backporting to a stable release. + <note> + The current Yocto Project policy regarding backporting is to + consider bug fixes and security fixes only. + Policy dictates that features are not backported to a stable + release. + This policy means generic recipe version upgrades are unlikely to + be accepted for backporting. + The exception to this policy occurs when a strong reason exists + such as the fix happens to also be the preferred upstream approach. + </note> + </para> + + <para> + Stable release branches have strong maintenance for about a year after + their initial release. + Should significant issues be found for any release regardless of its + age, fixes could be backported to older releases. + For issues that are not backported given an older release, + Community LTS trees and branches exist where + community members share patches for older releases. + However, these types of patches do not go through the same release + process as do point releases. + You can find more information about stable branch maintenance at + <ulink url='https://wiki.yoctoproject.org/wiki/Stable_branch_maintenance'></ulink>. + </para> +</section> + +<section id='testing-and-quality-assurance'> + <title>Testing and Quality Assurance</title> + + <para> + Part of the Yocto Project development and release process is quality + assurance through the execution of test strategies. + Test strategies provide the Yocto Project team a way to ensure a + release is validated. + Additionally, because the test strategies are visible to you as a + developer, you can validate your projects. + This section overviews the available test infrastructure used in the + Yocto Project. + For information on how to run available tests on your projects, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>" + section in the Yocto Project Development Manual. + </para> + + <para> + The QA/testing infrastructure is woven into the project to the point + where core developers take some of it for granted. + The infrastructure consists of the following pieces: + <itemizedlist> + <listitem><para> + <filename>bitbake-selftest</filename>: + A standalone command that runs unit tests on key pieces of + BitBake and its fetchers. + </para></listitem> + <listitem><para> + <link linkend='ref-classes-sanity'><filename>sanity.bbclass</filename></link>: + This automatically included class checks the build environment + for missing tools (e.g. <filename>gcc</filename>) or common + misconfigurations such as + <link linkend='var-MACHINE'><filename>MACHINE</filename></link> + set incorrectly. + </para></listitem> + <listitem><para> + <link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>: + This class checks the generated output from builds for sanity. + For example, if building for an ARM target, did the build + produce ARM binaries. + If, for example, the build produced PPC binaries then there + is a problem. + </para></listitem> + <listitem><para> + <link linkend='ref-classes-testimage*'><filename>testimage.bbclass</filename></link>: + This class performs runtime testing of images after they are + built. + The tests are usually used with + <ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>QEMU</ulink> + to boot the images and check the combined runtime result + boot operation and functions. + However, the test can also use the IP address of a machine to + test. + </para></listitem> + <listitem><para> + <ulink url='&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest'><filename>ptest</filename></ulink>: + Runs tests against packages produced during the build for a + given piece of software. + The test allows the packages to be be run within a target + image. + </para></listitem> + <listitem><para> + <filename>oe-selftest</filename>: + Tests combination BitBake invocations. + These tests operate outside the OpenEmbedded build system + itself. + The <filename>oe-selftest</filename> can run all tests by + default or can run selected tests or test suites. + <note> + Running <filename>oe-selftest</filename> requires + host packages beyond the "Essential" grouping. + See the + "<link linkend='required-packages-for-the-host-development-system'>Required Packages for the Host Development System</link>" + section for more information. + </note> + </para></listitem> + </itemizedlist> + </para> + + <para> + Originally, much of this testing was done manually. + However, significant effort has been made to automate the tests so + that more people can use them and the Yocto Project development team + can run them faster and more efficiently. + </para> + + <para> + The Yocto Project's main Autobuilder + (<filename>autobuilder.yoctoproject.org</filename>) publicly tests + each Yocto Project release's code in the OE-Core, Poky, and BitBake + repositories. + The testing occurs for both the current state of the + "master" branch and also for submitted patches. + Testing for submitted patches usually occurs in the + "ross/mut" branch in the <filename>poky-contrib</filename> repository + (i.e. the master-under-test branch) or in the "master-next" branch + in the <filename>poky</filename> repository. + <note> + You can find all these branches in the Yocto Project + <ulink url='&YOCTO_DOCS_DEV_URL;#source-repositories'>Source Repositories</ulink>. + </note> + Testing within these public branches ensures in a publicly visible way + that all of the main supposed architectures and recipes in OE-Core + successfully build and behave properly. + </para> + + <para> + Various features such as <filename>multilib</filename>, sub + architectures (e.g. <filename>x32</filename>, + <filename>poky-tiny</filename>, <filename>musl</filename>, + <filename>no-x11</filename> and and so forth), + <filename>bitbake-selftest</filename>, and + <filename>oe-selftest</filename> are tested as part of + the QA process of a release. + Complete testing and validation for a release takes the Autobuilder + workers several hours. + <note> + The Autobuilder workers are non-homogeneous, which means regular + testing across a variety of Linux distributions occurs. + The Autobuilder is limited to only testing QEMU-based setups and + not real hardware. + </note> + </para> + + <para> + Finally, in addition to the Autobuilder's tests, the Yocto Project + QA team also performs testing on a variety of platforms, which includes + actual hardware, to ensure expected results. + </para> +</section> + +</chapter> +<!-- +vim: expandtab tw=80 ts=4 +--> diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-structure.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-structure.xml index 541a47e556..9b2701cc31 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/ref-structure.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/ref-structure.xml @@ -797,15 +797,47 @@ </para> </section> + <section id='structure-build-tmp-sysroots-components'> + <title><filename>build/tmp/sysroots-components/</filename></title> + + <para> + This directory is the location of the sysroot contents that the + task + <link linkend='ref-tasks-prepare_recipe_sysroot'><filename>do_prepare_recipe_sysroot</filename></link> + links or copies into the recipe-specific sysroot for each + recipe listed in + <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>. + Population of this directory is handled through shared state, while + the path is specified by the <filename>COMPONENTS_DIR</filename> + variable. Apart from a few unusual circumstances, handling of the + <filename>sysroots-components</filename> directory should be + automatic, and recipes should not directly reference + <filename>build/tmp/sysroots-components</filename>. + </para> + </section> + <section id='structure-build-tmp-sysroots'> <title><filename>build/tmp/sysroots/</filename></title> <para> - This directory contains shared header files and libraries as well as other shared - data. - Packages that need to share output with other packages do so within this directory. - The directory is subdivided by architecture so multiple builds can run within - the one Build Directory. + Previous versions of the OpenEmbedded build system used to + create a global shared sysroot per machine along with a native + sysroot. + Beginning with the &DISTRO; version of the Yocto Project, + sysroots exist in recipe-specific + <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link> + directories. + Thus, the <filename>build/tmp/sysroots/</filename> directory + is unused. + <note> + The <filename>build/tmp/sysroots/</filename> directory + can still be populated using the + <filename>bitbake build-sysroots</filename> command and can + be used for compatibility in some cases. + However, in general it is not recommended to populate + this directory. + Individual recipe-specific sysroots should be used. + </note> </para> </section> @@ -894,6 +926,101 @@ </para> </section> + <section id='structure-build-tmp-work-tunearch-recipename-version'> + <title><filename>build/tmp/work/<replaceable>tunearch</replaceable>/<replaceable>recipename</replaceable>/<replaceable>version</replaceable>/</filename></title> + + <para> + The recipe work directory - <filename>${WORKDIR}</filename>. + </para> + + <para> + As described earlier in the + "<link linkend='structure-build-tmp-sysroots'><filename>build/tmp/sysroots/</filename></link>" + section, beginning with the &DISTRO; release of the Yocto + Project, the OpenEmbedded build system builds each recipe in its + own work directory (i.e. + <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>). + The path to the work directory is constructed using the + architecture of the given build (e.g. + <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>, + <link linkend='var-MACHINE_ARCH'><filename>MACHINE_ARCH</filename></link>, + or "allarch"), the recipe name, and the version of the recipe (i.e. + <link linkend='var-PE'><filename>PE</filename></link><filename>:</filename><link linkend='var-PV'><filename>PV</filename></link><filename>-</filename><link linkend='var-PR'><filename>PR</filename></link>). + </para> + + <para> + A number of key subdirectories exist within each recipe + work directory: + <itemizedlist> + <listitem><para> + <filename>${WORKDIR}/temp</filename>: + Contains the log files of each task executed for this + recipe, the "run" files for each executed task, which + contain the code run, and a + <filename>log.task_order</filename> file, which lists the + order in which tasks were executed. + </para></listitem> + <listitem><para> + <filename>${WORKDIR}/image</filename>: + Contains the output of the + <link linkend='ref-tasks-install'><filename>do_install</filename></link> + task, which corresponds to the + <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename> + variable in that task. + </para></listitem> + <listitem><para> + <filename>${WORKDIR}/pseudo</filename>: + Contains the pseudo database and log for any tasks executed + under pseudo for the recipe. + </para></listitem> + <listitem><para> + <filename>${WORKDIR}/sysroot-destdir</filename>: + Contains the output of the + <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link> + task. + </para></listitem> + <listitem><para> + <filename>${WORKDIR}/package</filename>: + Contains the output of the + <link linkend='ref-tasks-package'><filename>do_package</filename></link> + task before the output is split into individual packages. + </para></listitem> + <listitem><para> + <filename>${WORKDIR}/packages-split</filename>: + Contains the output of the <filename>do_package</filename> + task after the output has been split into individual + packages. + Subdirectories exist for each individual package created + by the recipe. + </para></listitem> + <listitem><para> + <filename>${WORKDIR}/recipe-sysroot</filename>: + A directory populated with the target dependencies of the + recipe. + This directory looks like the target filesystem and + contains libraries that the recipe might need to link + against (e.g. the C library). + </para></listitem> + <listitem><para> + <filename>${WORKDIR}/recipe-sysroot-native</filename>: + A directory populated with the native dependencies of the + recipe. + This directory contains the tools the recipe needs to build + (e.g. the compiler, Autoconf, libtool, and so forth). + </para></listitem> + <listitem><para> + <filename>${WORKDIR}/build</filename>: + This subdirectory applies only to recipes that support + builds where the source is separate from the + build artifacts. + The OpenEmbedded build system uses this directory as a + separate build directory (i.e. + <filename>${</filename><link linkend='var-B'><filename>B</filename></link><filename>}</filename>). + </para></listitem> + </itemizedlist> + </para> + </section> + <section id='structure-build-work-shared'> <title><filename>build/tmp/work-shared/</filename></title> diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-tasks.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-tasks.xml index e9859c1fa9..87ddb98278 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/ref-tasks.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/ref-tasks.xml @@ -490,6 +490,21 @@ </para> </section> + <section id='ref-tasks-prepare_recipe_sysroot'> + <title><filename>do_prepare_recipe_sysroot</filename></title> + + <para> + Installs the files into the individual recipe specific sysroots + (i.e. + <filename>${</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link><filename>}</filename> + based upon the dependencies specified by + <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>. + See the + "<link linkend='ref-classes-staging'><filename>staging</filename></link>" + class for more information. + </para> + </section> + <section id='ref-tasks-rm_work'> <title><filename>do_rm_work</filename></title> @@ -853,7 +868,10 @@ <title><filename>do_compile_kernelmodules</filename></title> <para> - Compiles loadable modules for the Linux kernel. + Runs the step that builds the kernel modules (if needed). + Building a kernel consists of two steps: 1) the kernel + (<filename>vmlinux</filename>) is built, and 2) the modules + are built (i.e. <filename>make modules</filename>). </para> </section> @@ -861,9 +879,21 @@ <title><filename>do_diffconfig</filename></title> <para> - Compares the old and new config files after running the - <link linkend='ref-tasks-menuconfig'><filename>do_menuconfig</filename></link> - task for the kernel. + When invoked by the user, this task creates a file containing the + differences between the original config as produced by + <link linkend='ref-tasks-kernel_configme'><filename>do_kernel_configme</filename></link> + task and the changes made by the user with other methods + (i.e. using + (<link linkend='ref-tasks-kernel_menuconfig'><filename>do_kernel_menuconfig</filename></link>). + Once the file of differences is created, it can be used to create + a config fragment that only contains the differences. + You can invoke this task from the command line as follows: + <literallayout class='monospaced'> + $ bitbake linux-yocto -c diffconfig + </literallayout> + For more information, see the + "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#generating-configuration-files'>Generating Configuration Files</ulink>" + section in the Yocto Project Linux Kernel Development Manual. </para> </section> @@ -871,7 +901,12 @@ <title><filename>do_kernel_checkout</filename></title> <para> - Checks out source/meta branches for a linux-yocto style kernel. + Converts the newly unpacked kernel source into a form with which + the OpenEmbedded build system can work. + Because the kernel source can be fetched in several different ways, + the <filename>do_kernel_checkout</filename> task makes sure that + subsequent tasks are given a clean working tree copy of the kernel + with the correct branches checked out. </para> </section> @@ -879,7 +914,21 @@ <title><filename>do_kernel_configcheck</filename></title> <para> - Validates the kernel configuration for a linux-yocto style kernel. + Validates the configuration produced by the + <link linkend='ref-tasks-kernel_menuconfig'><filename>do_kernel_menuconfig</filename></link> + task. + The <filename>do_kernel_configcheck</filename> task produces + warnings when a requested configuration does not appear in the + final <filename>.config</filename> file or when you override a + policy configuration in a hardware configuration fragment. + You can run this task explicitly and view the output by using + the following command: + <literallayout class='monospaced'> + $ bitbake linux-yocto -c kernel_configcheck -f + </literallayout> + For more information, see the + "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#generating-configuration-files'>Generating Configuration Files</ulink>" + section in the Yocto Project Linux Kernel Development Manual. </para> </section> @@ -887,17 +936,41 @@ <title><filename>do_kernel_configme</filename></title> <para> - Assembles the kernel configuration for a linux-yocto style kernel. + After the kernel is patched by the + <link linkend='ref-tasks-patch'><filename>do_patch</filename></link> + task, the <filename>do_kernel_configme</filename> task assembles + and merges all the kernel config fragments into a merged + configuration that can then be passed to the kernel configuration + phase proper. + This is also the time during which user-specified defconfigs + are applied if present, and where configuration modes such as + <filename>--allnoconfig</filename> are applied. </para> </section> - <section id='ref-tasks-kernel_link_vmlinux'> - <title><filename>do_kernel_link_vmlinux</filename></title> + <section id='ref-tasks-kernel_menuconfig'> + <title><filename>do_kernel_menuconfig</filename></title> <para> - Creates a symbolic link in - <filename>arch/$arch/boot</filename> for vmlinux kernel - images. + Invoked by the user to manipulate the + <filename>.config</filename> file used to build a linux-yocto + recipe. + This task starts the Linux kernel configuration tool, which you + then use to modify the kernel configuration. + <note> + You can also invoke this tool from the command line as + follows: + <literallayout class='monospaced'> + $ bitbake linux-yocto -c menuconfig + </literallayout> + </note> + See the + "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#generating-configuration-files'>Generating Configuration Files</ulink>" + section in the Yocto Project Linux Kernel Development Manual + for more information on this configuration tool. + You can also reference the + "<ulink url='&YOCTO_DOCS_DEV_URL;#using-menuconfig'>Using <filename>menuconfig</filename></ulink>" + section in the Yocto Project Development Manual. </para> </section> @@ -905,8 +978,16 @@ <title><filename>do_kernel_metadata</filename></title> <para> - Collects kernel metadata for a - <filename>linux-yocto</filename> style kernel. + Collects all the features required for a given kernel build, + whether the features come from + <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link> + or from Git repositories. + After collection, the <filename>do_kernel_metadata</filename> task + processes the features into a series of config fragments and + patches, which can then be applied by subsequent tasks such as + <link linkend='ref-tasks-patch'><filename>do_patch</filename></link> + and + <link linkend='ref-tasks-kernel_configme'><filename>do_kernel_configme</filename></link>. </para> </section> @@ -925,7 +1006,17 @@ <title><filename>do_savedefconfig</filename></title> <para> - Creates a minimal Linux kernel configuration file. + When invoked by the user, creates a defconfig file that can be + used instead of the default defconfig. + The saved defconfig contains the differences between the default + defconfig and the changes made by the user using other methods + (i.e. the + <link linkend='ref-tasks-kernel_menuconfig'><filename>do_kernel_menuconfig</filename></link> + task. + You can invoke the task using the following command: + <literallayout class='monospaced'> + $ bitbake linux-yocto -c savedefconfig + </literallayout> </para> </section> @@ -933,7 +1024,14 @@ <title><filename>do_shared_workdir</filename></title> <para> - Creates the shared working directory for the kernel. + After the kernel has been compiled but before the kernel modules + have been compiled, this task copies files required for module + builds and which are generated from the kernel build into the + shared work directory. + With these copies successfully copied, the + <link linkend='ref-tasks-compile_kernelmodules'><filename>do_compile_kernelmodules</filename></link> + task can successfully build the kernel modules in the next step + of the build. </para> </section> @@ -941,9 +1039,12 @@ <title><filename>do_sizecheck</filename></title> <para> - Checks the size of the kernel image against - <link linkend='var-KERNEL_IMAGE_MAXSIZE'><filename>KERNEL_IMAGE_MAXSIZE</filename></link> - when set. + After the kernel has been built, this task checks the size of the + stripped kernel image against + <link linkend='var-KERNEL_IMAGE_MAXSIZE'><filename>KERNEL_IMAGE_MAXSIZE</filename></link>. + If that variable was set and the size of the stripped kernel + exceeds that size, the kernel build produces a warning to that + effect. </para> </section> @@ -951,15 +1052,13 @@ <title><filename>do_strip</filename></title> <para> - Strips unneeded sections out of the Linux kernel image. - </para> - </section> - - <section id='ref-tasks-uboot_mkimage'> - <title><filename>do_uboot_mkimage</filename></title> - - <para> - Creates a uImage file from the kernel for the U-Boot bootloader. + If + <filename>KERNEL_IMAGE_STRIP_EXTRA_SECTIONS</filename> is defined, + this task strips the sections named in that variable from + <filename>vmlinux</filename>. + This stripping is typically used to remove nonessential sections + such as <filename>.comment</filename> sections from a + size-sensitive configuration. </para> </section> @@ -967,10 +1066,14 @@ <title><filename>do_validate_branches</filename></title> <para> - Ensures that the source, metadata (or both) branches are on the - locations specified by their - <link linkend='var-SRCREV'><filename>SRCREV</filename></link> - values for a linux-yocto style kernel. + After the kernel is unpacked but before it is patched, this task + makes sure that the machine and metadata branches as specified + by the <link linkend='var-SRCREV'><filename>SRCREV</filename></link> + variables actually exist on the specified branches. + If these branches do not exist and + <link linkend='var-AUTOREV'><filename>AUTOREV</filename></link> + is not being used, the <filename>do_validate_branches</filename> + task fails during the build. </para> </section> </section> diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-variables.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-variables.xml index 807e24251f..ad10139727 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/ref-variables.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/ref-variables.xml @@ -37,7 +37,7 @@ <link linkend='var-S'>S</link> <link linkend='var-T'>T</link> <link linkend='var-UBOOT_CONFIG'>U</link> -<!-- <link linkend='var-glossary-v'>V</link> --> + <link linkend='var-VOLATILE_LOG_DIR'>V</link> <link linkend='var-WARN_QA'>W</link> <link linkend='var-XSERVER'>X</link> <!-- <link linkend='var-glossary-y'>Y</link> --> @@ -484,6 +484,12 @@ in your recipe so that it does contain <filename>${SRCPV}</filename>. </para> + + <para> + For more information see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#automatically-incrementing-a-binary-package-revision-number'>Automatically Incrementing a Binary Package Revision Number</ulink>" + section in the Yocto Project Development Manual. + </para> </glossdef> </glossentry> @@ -2364,6 +2370,160 @@ </glossdef> </glossentry> + <glossentry id='var-COPYLEFT_LICENSE_EXCLUDE'><glossterm>COPYLEFT_LICENSE_EXCLUDE</glossterm> + <info> + COPYLEFT_LICENSE_EXCLUDE[doc] = "Licenses to exclude in the source archived by the archiver class." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + A space-separated list of licenses to exclude from the + source archived by the + <link linkend='ref-classes-archiver'><filename>archiver</filename></link> + class. + In other words, if a license in a recipe's + <link linkend='var-LICENSE'><filename>LICENSE</filename></link> + value is in the value of + <filename>COPYLEFT_LICENSE_EXCLUDE</filename>, then its + source is not archived by the class. + <note> + The <filename>COPYLEFT_LICENSE_EXCLUDE</filename> + variable takes precedence over the + <link linkend='var-COPYLEFT_LICENSE_INCLUDE'><filename>COPYLEFT_LICENSE_INCLUDE</filename></link> + variable. + </note> + The default value, which is "CLOSED Proprietary", for + <filename>COPYLEFT_LICENSE_EXCLUDE</filename> is set + by the + <link linkend='ref-classes-copyleft_filter'><filename>copyleft_filter</filename></link> + class, which is inherited by the + <filename>archiver</filename> class. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-COPYLEFT_LICENSE_INCLUDE'><glossterm>COPYLEFT_LICENSE_INCLUDE</glossterm> + <info> + COPYLEFT_LICENSE_INCLUDE[doc] = "Licenses to include in the source archived by the archiver class." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + A space-separated list of licenses to include in the + source archived by the + <link linkend='ref-classes-archiver'><filename>archiver</filename></link> + class. + In other words, if a license in a recipe's + <link linkend='var-LICENSE'><filename>LICENSE</filename></link> + value is in the value of + <filename>COPYLEFT_LICENSE_INCLUDE</filename>, then its + source is archived by the class. + </para> + + <para> + The default value is set by the + <link linkend='ref-classes-copyleft_filter'><filename>copyleft_filter</filename></link> + class, which is inherited by the + <filename>archiver</filename> class. + The default value includes "GPL*", "LGPL*", and "AGPL*". + </para> + </glossdef> + </glossentry> + + <glossentry id='var-COPYLEFT_PN_EXCLUDE'><glossterm>COPYLEFT_PN_EXCLUDE</glossterm> + <info> + COPYLEFT_PN_EXCLUDE[doc] = "Recipes to exclude in the source archived by the archiver class." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + A list of recipes to exclude in the source archived + by the + <link linkend='ref-classes-archiver'><filename>archiver</filename></link> + class. + The <filename>COPYLEFT_PN_EXCLUDE</filename> variable + overrides the license inclusion and exclusion caused + through the + <link linkend='var-COPYLEFT_LICENSE_INCLUDE'><filename>COPYLEFT_LICENSE_INCLUDE</filename></link> + and + <link linkend='var-COPYLEFT_LICENSE_EXCLUDE'><filename>COPYLEFT_LICENSE_EXCLUDE</filename></link> + variables, respectively. + </para> + + <para> + The default value, which is "" indicating to not explicitly + exclude any recipes by name, for + <filename>COPYLEFT_PN_EXCLUDE</filename> is set + by the + <link linkend='ref-classes-copyleft_filter'><filename>copyleft_filter</filename></link> + class, which is inherited by the + <filename>archiver</filename> class. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-COPYLEFT_PN_INCLUDE'><glossterm>COPYLEFT_PN_INCLUDE</glossterm> + <info> + COPYLEFT_PN_INCLUDE[doc] = "Recipes to include in the source archived by the archiver class." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + A list of recipes to include in the source archived + by the + <link linkend='ref-classes-archiver'><filename>archiver</filename></link> + class. + The <filename>COPYLEFT_PN_INCLUDE</filename> variable + overrides the license inclusion and exclusion caused + through the + <link linkend='var-COPYLEFT_LICENSE_INCLUDE'><filename>COPYLEFT_LICENSE_INCLUDE</filename></link> + and + <link linkend='var-COPYLEFT_LICENSE_EXCLUDE'><filename>COPYLEFT_LICENSE_EXCLUDE</filename></link> + variables, respectively. + </para> + + <para> + The default value, which is "" indicating to not explicitly + include any recipes by name, for + <filename>COPYLEFT_PN_INCLUDE</filename> is set + by the + <link linkend='ref-classes-copyleft_filter'><filename>copyleft_filter</filename></link> + class, which is inherited by the + <filename>archiver</filename> class. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-COPYLEFT_RECIPE_TYPES'><glossterm>COPYLEFT_RECIPE_TYPES</glossterm> + <info> + COPYLEFT_RECIPE_TYPES[doc] = "Recipe types to include in the source archived by the archiver class." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + A space-separated list of recipe types to include + in the source archived by the + <link linkend='ref-classes-archiver'><filename>archiver</filename></link> + class. + Recipe types are <filename>target</filename>, + <filename>native</filename>, + <filename>nativesdk</filename>, + <filename>cross</filename>, + <filename>crosssdk</filename>, and + <filename>cross-canadian</filename>. + </para> + + <para> + The default value, which is "target*", for + <filename>COPYLEFT_RECIPE_TYPES</filename> is set + by the + <link linkend='ref-classes-copyleft_filter'><filename>copyleft_filter</filename></link> + class, which is inherited by the + <filename>archiver</filename> class. + </para> + </glossdef> + </glossentry> + <glossentry id='var-COPY_LIC_DIRS'><glossterm>COPY_LIC_DIRS</glossterm> <info> COPY_LIC_DIRS[doc] = "If set to "1" along with the COPY_LIC_MANIFEST variable, the OpenEmbedded build system copies into the image the license files, which are located in /usr/share/common-licenses, for each package." @@ -3463,6 +3623,47 @@ </glossdef> </glossentry> + <glossentry id='var-DISTRO_FEATURES_FILTER_NATIVE'><glossterm>DISTRO_FEATURES_FILTER_NATIVE</glossterm> + <info> + DISTRO_FEATURES_FILTER_NATIVE[doc] = "Specifies a list of features that if present in the target DISTRO_FEATURES value should be included in DISTRO_FEATURES when building native recipes." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Specifies a list of features that if present in + the target + <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link> + value should be included in + <filename>DISTRO_FEATURES</filename> when building native + recipes. + This variable is used in addition to the features + filtered using the + <link linkend='var-DISTRO_FEATURES_NATIVE'><filename>DISTRO_FEATURES_NATIVE</filename></link> + variable. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-DISTRO_FEATURES_FILTER_NATIVESDK'><glossterm>DISTRO_FEATURES_FILTER_NATIVESDK</glossterm> + <info> + DISTRO_FEATURES_FILTER_NATIVESDK[doc] = "Specifies a list of features that if present in the target DISTRO_FEATURES value should be included in DISTRO_FEATURES when building nativesdk recipes." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Specifies a list of features that if present in the target + <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link> + value should be included in + <filename>DISTRO_FEATURES</filename> when building + nativesdk recipes. + This variable is used in addition to the features + filtered using the + <link linkend='var-DISTRO_FEATURES_NATIVESDK'><filename>DISTRO_FEATURES_NATIVESDK</filename></link> + variable. + </para> + </glossdef> + </glossentry> + <glossentry id='var-DISTRO_FEATURES_LIBC'><glossterm>DISTRO_FEATURES_LIBC</glossterm> <info> DISTRO_FEATURES_LIBC[doc] = "Specifies the list of distro features that are specific to the C library (libc)." @@ -3480,6 +3681,42 @@ </glossdef> </glossentry> + <glossentry id='var-DISTRO_FEATURES_NATIVE'><glossterm>DISTRO_FEATURES_NATIVE</glossterm> + <info> + DISTRO_FEATURES_NATIVE[doc] = "Specifies a list of features that should be included in DISTRO_FEATURES when building native recipes." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Specifies a list of features that should be included in + <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link> + when building native recipes. + This variable is used in addition to the features + filtered using the + <link linkend='var-DISTRO_FEATURES_FILTER_NATIVE'><filename>DISTRO_FEATURES_FILTER_NATIVE</filename></link> + variable. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-DISTRO_FEATURES_NATIVESDK'><glossterm>DISTRO_FEATURES_NATIVESDK</glossterm> + <info> + DISTRO_FEATURES_NATIVESDK[doc] = "Specifies a list of features that should be included in DISTRO_FEATURES when building nativesdk recipes." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Specifies a list of features that should be included in + <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link> + when building nativesdk recipes. + This variable is used in addition to the features + filtered using the + <link linkend='var-DISTRO_FEATURES_FILTER_NATIVESDK'><filename>DISTRO_FEATURES_FILTER_NATIVESDK</filename></link> + variable. + </para> + </glossdef> + </glossentry> + <glossentry id='var-DISTRO_NAME'><glossterm>DISTRO_NAME</glossterm> <info> DISTRO_NAME[doc] = "The long name of the distribution." @@ -3643,7 +3880,9 @@ <para> See the <link linkend='ref-classes-systemd-boot'><filename>systemd-boot</filename></link> - class for more information. + and + <link linkend='ref-classes-image-live'><filename>image-live</filename></link> + classes for more information. </para> </glossdef> </glossentry> @@ -4954,6 +5193,53 @@ </glossdef> </glossentry> + <glossentry id='var-HOSTTOOLS'><glossterm>HOSTTOOLS</glossterm> + <info> + HOSTTOOLS[doc] = "A space-separated list (filter) of tools on the build host that should be allowed to be called from within build tasks." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + A space-separated list (filter) of tools on the build host + that should be allowed to be called from within build tasks. + Using this filter helps reduce the possibility of host + contamination. + If a tool specified in the value of + <filename>HOSTTOOLS</filename> is not found on the + build host, the OpenEmbedded build system produces + an error and the build is not started. + </para> + + <para> + For additional information, see + <link linkend='var-HOSTTOOLS_NONFATAL'><filename>HOSTTOOLS_NONFATAL</filename></link>. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-HOSTTOOLS_NONFATAL'><glossterm>HOSTTOOLS_NONFATAL</glossterm> + <info> + HOSTTOOLS_NONFATAL[doc] = "A space-separated list (filter) of tools on the build host that should be allowed to be called from within build tasks." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + A space-separated list (filter) of tools on the build host + that should be allowed to be called from within build tasks. + Using this filter helps reduce the possibility of host + contamination. + Unlike + <link linkend='var-HOSTTOOLS'><filename>HOSTTOOLS</filename></link>, + the OpenEmbedded build system does not produce and error + if a tool specified in the value of + <filename>HOSTTOOLS_NONFATAL</filename> is not found on the + build host. + Thus, you can use <filename>HOSTTOOLS_NONFATAL</filename> + to filter optional host tools. + </para> + </glossdef> + </glossentry> + <glossentry id='var-HOST_VENDOR'><glossterm>HOST_VENDOR</glossterm> <info> HOST_VENDOR[doc] = "The name of the vendor. Normally same as the TARGET_VENDOR." @@ -6030,14 +6316,24 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossentry id='var-INHERIT'><glossterm>INHERIT</glossterm> <info> - INHERIT[doc] = "Causes the named class to be inherited at this point during parsing. The variable is only valid in configuration files." + INHERIT[doc] = "Causes the named class or classes to be inherited globally." </info> <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - Causes the named class to be inherited at - this point during parsing. - The variable is only valid in configuration files. + Causes the named class or classes to be inherited globally. + Anonymous functions in the class or classes + are not executed for the + base configuration and in each individual recipe. + The OpenEmbedded build system ignores changes to + <filename>INHERIT</filename> in individual recipes. + </para> + + <para> + For more information on <filename>INHERIT</filename>, see + the + "<ulink url="&YOCTO_DOCS_BB_URL;#inherit-configuration-directive"><filename>INHERIT</filename> Configuration Directive</ulink>" + section in the Yocto Project Bitbake User Manual. </para> </glossdef> </glossentry> @@ -7145,21 +7441,30 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossentry id='var-LAYERDEPENDS'><glossterm>LAYERDEPENDS</glossterm> <info> - LAYERDEPENDS[doc] = "Lists the layers, separated by spaces, upon which this recipe depends. This variable is used in the conf/layer.conf file and must be suffixed with the name of the specific layer." + LAYERDEPENDS[doc] = "Lists the layers, separated by spaces, on which this recipe depends. This variable is used in the conf/layer.conf file and must be suffixed with the name of the specific layer." </info> <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - Lists the layers that this recipe depends upon, separated by spaces. - Optionally, you can specify a specific layer version for a dependency - by adding it to the end of the layer name with a colon, (e.g. "anotherlayer:3" - to be compared against - <link linkend='var-LAYERVERSION'><filename>LAYERVERSION</filename></link><filename>_anotherlayer</filename> - in this case). - An error will be produced if any dependency is missing or - the version numbers do not match exactly (if specified). - This variable is used in the <filename>conf/layer.conf</filename> file - and must be suffixed with the name of the specific layer (e.g. + Lists the layers, separated by spaces, on which this + recipe depends. + Optionally, you can specify a specific layer version for a + dependency by adding it to the end of the layer name. + Here is an example: + <literallayout class='monospaced'> + LAYERDEPENDS_mylayer = "anotherlayer (=3)" + </literallayout> + In this previous example, version 3 of "anotherlayer" + is compared against + <link linkend='var-LAYERVERSION'><filename>LAYERVERSION</filename></link><filename>_anotherlayer</filename>. + </para> + + <para> + An error is produced if any dependency is missing or + the version numbers (if specified) do not match exactly. + This variable is used in the + <filename>conf/layer.conf</filename> file and must be + suffixed with the name of the specific layer (e.g. <filename>LAYERDEPENDS_mylayer</filename>). </para> </glossdef> @@ -7180,6 +7485,39 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> + <glossentry id='var-LAYERRECOMMENDS'><glossterm>LAYERRECOMMENDS</glossterm> + <info> + LAYERRECOMMENDS[doc] = "Lists the layers, separated by spaces, recommended for use with this layer." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Lists the layers, separated by spaces, recommended for + use with this layer. + </para> + + <para> + Optionally, you can specify a specific layer version for a + recommendation by adding the version to the end of the + layer name. + Here is an example: + <literallayout class='monospaced'> + LAYERRECOMMENDS_mylayer = "anotherlayer (=3)" + </literallayout> + In this previous example, version 3 of "anotherlayer" is + compared against + <filename>LAYERVERSION_anotherlayer</filename>. + </para> + + <para> + This variable is used in the + <filename>conf/layer.conf</filename> file and must be + suffixed with the name of the specific layer (e.g. + <filename>LAYERRECOMMENDS_mylayer</filename>). + </para> + </glossdef> + </glossentry> + <glossentry id='var-LAYERVERSION'><glossterm>LAYERVERSION</glossterm> <info> LAYERVERSION[doc] = "Optionally specifies the version of a layer as a single number. This variable is used in the conf/layer.conf file and must be suffixed with the name of the specific layer." @@ -8198,13 +8536,16 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> +<!-- <glossentry id='var-MULTIMACH_HOST_SYS'><glossterm>MULTIMACH_HOST_SYS</glossterm> <info> MULTIMACH_HOST_SYS[doc] = "Separates files for different machines such that you can build for multiple host machines using the same output directories." </info> <glossdef> <para role="glossdeffirst"> +--> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> +<!-- Serves the same purpose as <link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>, but for the "HOST" system, in situations that involve a @@ -8222,6 +8563,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </para> </glossdef> </glossentry> +--> <glossentry id='var-MULTIMACH_TARGET_SYS'><glossterm>MULTIMACH_TARGET_SYS</glossterm> <info> @@ -8251,9 +8593,6 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" See the <link linkend='var-STAMP'><filename>STAMP</filename></link> variable for an example. - <link linkend='var-MULTIMACH_HOST_SYS'><filename>MULTIMACH_HOST_SYS</filename></link> - is the corresponding variable for the host system in - situations that involve a "HOST" and a "TARGET" system. See the <link linkend='var-STAGING_DIR_TARGET'><filename>STAGING_DIR_TARGET</filename></link> variable for more information. @@ -8332,7 +8671,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <filename>local.conf</filename> file or you can attach it to a specific image recipe by using the recipe name override: <literallayout class='monospaced'> - NO_RECOMMENDATIONS_pn-<replaceable>target_image</replaceable> = "<replaceable>package_name</replaceable>" + NO_RECOMMENDATIONS_pn-<replaceable>target_image</replaceable> = "1" </literallayout> </para> @@ -9163,6 +9502,31 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> + <glossentry id='var-PACKAGE_WRITE_DEPS'><glossterm>PACKAGE_WRITE_DEPS</glossterm> + <info> + PACKAGE_WRITE_DEPS[doc] = "Specifies post-installation and pre-installation script dependencies on native/cross tools." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Specifies a list of dependencies for post-installation and + pre-installation scripts on native/cross tools. + If your post-installation or pre-installation script can + execute at rootfs creation time rather than on the + target but depends on a native tool in order to execute, + you need to list the tools in + <filename>PACKAGE_WRITE_DEPENDS</filename>. + </para> + + <para> + For information on running post-installation scripts, see + the + "<ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-post-installation-scripts'>Post-Installation Scripts</ulink>" + section in the Yocto Project Development Manual. + </para> + </glossdef> + </glossentry> + <glossentry id='var-PACKAGECONFIG'><glossterm>PACKAGECONFIG</glossterm> <info> PACKAGECONFIG[doc] = "This variable provides a means of enabling or disabling features of a recipe on a per-recipe basis." @@ -9299,29 +9663,22 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" from the <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link> setting. - This list of options helps other classes and - recipes take advantage of the - <filename>PACKAGECONFIG</filename> mechanism without - having to include options from - <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>. </para> <para> - To illustrate how to use - <filename>PACKAGECONFIG_CONFARGS</filename>, consider the - following example: - <literallayout class='monospaced'> - PACKAGECONFIG_CONFARGS = " \ - -prefix ${prefix} \ - -sysroot ${STAGING_DIR_NATIVE} \ - -no-gcc-sysroot - " - </literallayout> - In the previous example, - <filename>PACKAGECONFIG_CONFARGS</filename> is set with - three configuration options that can be passed using the - <filename>PACKAGECONFIG</filename> mechanism, thus - avoiding having to use <filename>EXTRA_OECONF</filename>. + Classes such as + <link linkend='ref-classes-autotools'><filename>autotools</filename></link> + and + <link linkend='ref-classes-cmake'><filename>cmake</filename></link> + use <filename>PACKAGECONFIG_CONFARGS</filename> to pass + <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link> + options to <filename>configure</filename> and + <filename>cmake</filename>, respectively. + If you are using + <filename>PACKAGECONFIG</filename> but not a class that + handles the <filename>do_configure</filename> task, then + you need to use + <filename>PACKAGECONFIG_CONFARGS</filename> appropriately. </para> <para> @@ -12499,15 +12856,17 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" every time BitBake parses your recipe, you should specify a <filename>SRCREV</filename> that is a full revision identifier and not just a tag. + <note> + For information on limitations when inheriting the + latest revision of software using + <filename>SRCREV</filename>, see the + <link linkend='var-AUTOREV'><filename>AUTOREV</filename></link> + variable description and the + "<ulink url='&YOCTO_DOCS_DEV_URL;#automatically-incrementing-a-binary-package-revision-number'>Automatically Incrementing a Binary Package Revision Number</ulink>" + section, which is in the Yocto Project Development Manual. + </note> </para> - <note> - For information on limitations when inheriting the latest - revision of software using <filename>SRCREV</filename>, - see the - <link linkend='var-AUTOREV'><filename>AUTOREV</filename></link> - variable description. - </note> </glossdef> </glossentry> @@ -12588,6 +12947,41 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> + <glossentry id='var-SSTATE_SCAN_FILES'><glossterm>SSTATE_SCAN_FILES</glossterm> + <info> + SSTATE_SCAN_FILES[doc] = "Controls the list of files the OpenEmbedded build system scans for hardcoded installation paths." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Controls the list of files the OpenEmbedded build system + scans for hardcoded installation paths. The variable uses a + space-separated list of filenames (not paths) with standard + wildcard characters allowed. + </para> + + <para> + During a build, the OpenEmbedded build system creates a + shared state (sstate) object during the first stage of + preparing the sysroots. That object is scanned for + hardcoded paths for original installation locations. + The list of files that are scanned for paths is controlled + by the <filename>SSTATE_SCAN_FILES</filename> variable. + Typically, recipes add files they want to be scanned to the + value of <filename>SSTATE_SCAN_FILES</filename> rather than + the variable being comprehensively set. The + <link linkend='ref-classes-sstate'><filename>sstate</filename></link> + class specifies the default list of files. + </para> + + <para> + For details on the process, see the + <link linkend='ref-classes-staging'><filename>staging</filename></link> + class. + </para> + </glossdef> + </glossentry> + <glossentry id='var-STAGING_BASE_LIBDIR_NATIVE'><glossterm>STAGING_BASE_LIBDIR_NATIVE</glossterm> <info> STAGING_BASE_LIBDIR_NATIVE[doc] = "Specifies the path to the /lib subdirectory of the sysroot directory for the build host." @@ -12801,12 +13195,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" they make use of host headers and libraries. </para> </note> - </para></listitem> - <listitem><para>For native SDK - recipes that build for the SDK - (<filename>nativesdk</filename>), the value is - "${STAGING_DIR}/${<link linkend='var-MULTIMACH_HOST_SYS'>MULTIMACH_HOST_SYS</link>}". - </para></listitem> + </para></listitem> </itemizedlist> </para> </glossdef> @@ -13185,6 +13574,28 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> + <glossentry id='var-SYSROOT_DESTDIR'><glossterm>SYSROOT_DESTDIR</glossterm> + <info> + SYSROOT_DESTDIR[doc] = "Points to the temporary work directory (default ${WORKDIR}/sysroot-destdir) where the files that will be populated into the sysroot are assembled during the do_populate_sysroot task." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Points to the temporary directory under the work directory + (default + <filename>${</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link><filename>}/sysroot-destidir</filename>) + where the files + that will be populated into the sysroot are assembled + during the + <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link> + task. + <literallayout class='monospaced'> + SYSROOT_DESTDIR ?= "console=ttyS0,115200" + </literallayout> + </para> + </glossdef> + </glossentry> + <glossentry id='var-SYSROOT_DIRS'><glossterm>SYSROOT_DIRS</glossterm> <info> SYSROOT_DIRS[doc] = "Directories that are staged into the sysroot by the do_populate_sysroot task." @@ -14197,8 +14608,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <note> The <filename>TEST_SERVER_IP</filename> variable is only used for a small number of tests such as - the "smart" test suite, which needs to download - packages from <filename>DEPLOY_DIR/rpm</filename>. + the "dnf" test suite, which needs to download + packages from + <filename>WORKDIR/oe-rootfs-repo</filename>. </note> </para> </glossdef> @@ -15544,8 +15956,30 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdiv> -<!-- <glossdiv id='var-glossary-v'><title>V</title>--> -<!-- </glossdiv>--> + <glossdiv id='var-glossary-v'><title>V</title> + + <glossentry id='var-VOLATILE_LOG_DIR'><glossterm>VOLATILE_LOG_DIR</glossterm> + <info> + VOLATILE_LOG_DIR[doc] = "Specifies the persistence of the target's /var/log directory, which is used to house postinstall target log files." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Specifies the persistence of the target's + <filename>/var/log</filename> directory, which is used to + house postinstall target log files. + </para> + + <para> + By default, <filename>VOLATILE_LOG_DIR</filename> is set + to "yes", which means the file is not persistent. + You can override this setting by setting the + variable to "no" to make the log directory persistent. + </para> + </glossdef> + </glossentry> + + </glossdiv> <glossdiv id='var-glossary-w'><title>W</title> @@ -15568,6 +16002,50 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> + <glossentry id='var-WKS_FILE_DEPENDS'><glossterm>WKS_FILE_DEPENDS</glossterm> + <info> + WKS_FILE_DEPENDS[doc] = "Lists a recipe's build-time dependencies specific to Wic." + </info> + <glossdef> + <para role="glossdeffirst"> + When placed in the recipe that builds your image, this + variable lists build-time dependencies. + The <filename>WKS_FILE_DEPENDS</filename> variable is only + applicable when Wic images are active (i.e. when + <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link> + contains entries related to Wic). + If your recipe does not create Wic images, the variable + has no effect. + </para> + + <para> + The <filename>WKS_FILE_DEPENDS</filename> variable is + similar to the + <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link> + variable. + When you use the variable in your recipe that builds the + Wic image, dependencies you list in the + <filename>WIC_FILE_DEPENDS</filename> variable are added to + the <filename>DEPENDS</filename> variable. + </para> + + <para> + With the <filename>WKS_FILE_DEPENDS</filename> variable, + you have the possibility to specify a list of additional + dependencies (e.g. native tools, bootloaders, and so forth), + that are required to build Wic images. + Following is an example: + <literallayout class='monospaced'> + WKS_FILE_DEPENDS = "<replaceable>some-native-tool</replaceable>" + </literallayout> + In the previous example, + <replaceable>some-native-tool</replaceable> would be + replaced with an actual native tool on which the build + would depend. + </para> + </glossdef> + </glossentry> + <glossentry id='var-WKS_FILE'><glossterm>WKS_FILE</glossterm> <info> WKS_FILE[doc] = "Specifies the name of the wic kickstart file." diff --git a/import-layers/yocto-poky/documentation/ref-manual/technical-details.xml b/import-layers/yocto-poky/documentation/ref-manual/technical-details.xml index 9bb09fb948..1964a9a105 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/technical-details.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/technical-details.xml @@ -432,7 +432,7 @@ For information on how the OpenEmbedded build system works with packages and can track incrementing <filename>PR</filename> information, see the - "<ulink url='&YOCTO_DOCS_DEV_URL;#incrementing-a-package-revision-number'>Incrementing a Package Revision Number</ulink>" + "<ulink url='&YOCTO_DOCS_DEV_URL;#automatically-incrementing-a-binary-package-revision-number'>Automatically Incrementing a Binary Package Revision Number</ulink>" section. </note> @@ -1445,14 +1445,33 @@ <para> The <filename>LIC_FILES_CHKSUM</filename> - variable contains checksums of the license text in the source code for the recipe. - Following is an example of how to specify <filename>LIC_FILES_CHKSUM</filename>: + variable contains checksums of the license text in the source + code for the recipe. + Following is an example of how to specify + <filename>LIC_FILES_CHKSUM</filename>: <literallayout class='monospaced'> LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \ file://licfile1.txt;beginline=5;endline=29;md5=yyyy \ file://licfile2.txt;endline=50;md5=zzzz \ ..." </literallayout> + <note><title>Notes</title> + <itemizedlist> + <listitem><para> + When using "beginline" and "endline", realize that + line numbering begins with one and not zero. + Also, the included lines are inclusive (i.e. lines + five through and including 29 in the previous + example for <filename>licfile1.txt</filename>). + </para></listitem> + <listitem><para> + When a license check fails, the selected license + text is included as part of the QA message. + Using this output, you can determine the exact + start and finish for the needed license text. + </para></listitem> + </itemizedlist> + </note> </para> <para> @@ -1474,7 +1493,8 @@ <para> The first line locates a file in - <filename>${S}/src/ls.c</filename>. + <filename>${S}/src/ls.c</filename> and isolates lines five + through 16 as license text. The second line refers to a file in <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>. </para> diff --git a/import-layers/yocto-poky/documentation/ref-manual/usingpoky.xml b/import-layers/yocto-poky/documentation/ref-manual/usingpoky.xml index f7345547c5..d08031617b 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/usingpoky.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/usingpoky.xml @@ -69,6 +69,39 @@ <literallayout class='monospaced'> $ bitbake <replaceable>target</replaceable> </literallayout> + <note> + <para> + If you experience a build error due to resources + temporarily being unavailable and it appears you + should not be having this issue, it might be due + to the combination of a 4.3+ Linux kernel and + <filename>systemd</filename> version 228+ + (i.e. see this + <ulink url='http://unix.stackexchange.com/questions/253903/creating-threads-fails-with-resource-temporarily-unavailable-with-4-3-kernel'>link</ulink> + for information). + </para> + + <para> + To work around this issue, you can try either + of the following: + <itemizedlist> + <listitem><para> + Try the build again. + </para></listitem> + <listitem><para> + Modify the "DefaultTasksMax" + <filename>systemd</filename> parameter + by uncommenting it and setting it to + "infinity". + You can find this parameter in the + <filename>system.conf</filename> file + located in + <filename>/etc/systemd</filename> + on most systems. + </para></listitem> + </itemizedlist> + </para> + </note> </para> <para> @@ -392,14 +425,6 @@ are not listed. </para></listitem> <listitem><para> - <filename>pn-depends.dot</filename>: A graph showing - dependencies between build-time targets (recipes). - </para></listitem> - <listitem><para> - <filename>package-depends.dot</filename>: A graph showing - known dependencies between runtime targets. - </para></listitem> - <listitem><para> <filename>task-depends.dot</filename>: A graph showing dependencies between tasks. </para></listitem> @@ -455,7 +480,7 @@ You can use a different method to view dependency information by using the following command: <literallayout class='monospaced'> - $ bitbake -g -u depexp <replaceable>recipename</replaceable> + $ bitbake -g -u taskexp <replaceable>recipename</replaceable> </literallayout> This command displays a GUI window from which you can view build-time and runtime dependencies for the recipes involved in @@ -711,79 +736,6 @@ </para> </section> - <section id='checking-for-missing-build-time-dependencies'> - <title>Checking for Missing Build-Time Dependencies</title> - - <para> - A recipe might build successfully even though some of its - build-time dependencies are missing from - <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>. - Following are the two most common ways in which that can happen: - <itemizedlist> - <listitem><para> - The build-time dependency just happens to already exist in - the staging sysroot - (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>) - by the time the recipe is built. - This situation occurs when the build-time dependency is - built earlier during recipe processing. - </para></listitem> - <listitem><para> - The component built by the recipe conditionally enables - functionality depending on whether it can find the - build-time dependency in the staging sysroot. - If the build-time dependency is missing, the corresponding - functionality is disabled. - This condition is known as a "floating dependency". - </para></listitem> - </itemizedlist> - </para> - - <para> - Because dealing with the second case is more complex, focus will - be on the first case. - The - <link linkend='ref-classes-insane'><filename>build-deps</filename></link> - QA check checks that every library the component linked against is - declared as a build-time dependency. - If that is not the case, then the first situation described in the - previous list exists, and <filename>build-deps</filename> reports - a missing build-time dependency. - </para> - - <para> - Another, more manual, way to check a recipe for missing build-time - dependencies of the first type is to build with an empty staging - sysroot. - This method can also find missing build-time dependencies - that are not in the form of libraries, which the - <filename>build-deps</filename> QA check is unable to find. - </para> - - <para> - An easy way to empty the staging sysroots is to simply remove - <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>, - which is usually - <filename>${</filename><link linkend='var-BUILDDIR'><filename>BUILDDIR</filename></link><filename>}/tmp</filename>, - as it includes the staging sysroots. - Another, faster method to empty the staging sysroots is to use the - <filename>scripts/wipe-sysroot</filename> script, - which removes just the staging sysroots and keeps everything else - in <filename>TMPDIR</filename>. - <note> - The <filename>scripts/</filename> directory appears in - <filename>PATH</filename> after running the build environment - initialization script (i.e. - <link linkend='structure-core-script'><filename>oe-init-build-env</filename></link> - or - <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>), - which results in the ability to to run - <filename>wipe-sysroot</filename> immediately. - </note> - </para> - - </section> - <section id='usingpoky-debugging-bitbake'> <title>General BitBake Problems</title> |