diff options
Diffstat (limited to 'import-layers/yocto-poky/documentation/ref-manual')
16 files changed, 4165 insertions, 664 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 84ff584ba..b73e59ca7 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/closer-look.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/closer-look.xml @@ -888,7 +888,9 @@ class, you can add additional configuration options by using the <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link> - variable. + or + <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link> + variables. For information on how this variable works within that class, see the <filename>meta/classes/autotools.bbclass</filename> file. @@ -1209,6 +1211,199 @@ which includes the environment setup script. </para> </section> + + <section id='stamp-files-and-the-rerunning-of-tasks'> + <title>Stamp Files and the Rerunning of Tasks</title> + + <para> + For each task that completes successfully, BitBake writes a + stamp file into the + <link linkend='var-STAMPS_DIR'><filename>STAMPS_DIR</filename></link> + directory. + The beginning of the stamp file's filename is determined by the + <link linkend='var-STAMP'><filename>STAMP</filename></link> + variable, and the end of the name consists of the task's name + and current + <ulink url='&YOCTO_DOCS_BB_URL;#checksums'>input checksum</ulink>. + <note> + This naming scheme assumes that + <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_SIGNATURE_HANDLER'><filename>BB_SIGNATURE_HANDLER</filename></ulink> + is "OEBasicHash", which is almost always the case in + current OpenEmbedded. + </note> + To determine if a task needs to be rerun, BitBake checks if a + stamp file with a matching input checksum exists for the task. + If such a stamp file exists, the task's output is assumed to + exist and still be valid. + If the file does not exist, the task is rerun. + <note> + <para>The stamp mechanism is more general than the shared + state (sstate) cache mechanism described in the + "<link linkend='setscene-tasks-and-shared-state'>Setscene Tasks and Shared State</link>" + section. + BitBake avoids rerunning any task that has a valid + stamp file, not just tasks that can be accelerated through + the sstate cache.</para> + <para>However, you should realize that stamp files only + serve as a marker that some work has been done and that + these files do not record task output. + The actual task output would usually be somewhere in + <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> + (e.g. in some recipe's + <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.) + What the sstate cache mechanism adds is a way to cache task + output that can then be shared between build machines. + </para> + </note> + Since <filename>STAMPS_DIR</filename> is usually a subdirectory + of <filename>TMPDIR</filename>, removing + <filename>TMPDIR</filename> will also remove + <filename>STAMPS_DIR</filename>, which means tasks will + properly be rerun to repopulate <filename>TMPDIR</filename>. + </para> + + <para> + If you want some task to always be considered "out of date", + you can mark it with the + <ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>nostamp</filename></ulink> + varflag. + If some other task depends on such a task, then that task will + also always be considered out of date, which might not be what + you want. + </para> + + <para> + For details on how to view information about a task's + signature, see the + "<link linkend='usingpoky-viewing-task-variable-dependencies'>Viewing Task Variable Dependencies</link>" + section. + </para> + </section> + + <section id='setscene-tasks-and-shared-state'> + <title>Setscene Tasks and Shared State</title> + + <para> + The description of tasks so far assumes that BitBake needs to + build everything and there are no prebuilt objects available. + BitBake does support skipping tasks if prebuilt objects are + available. + These objects are usually made available in the form of a + shared state (sstate) cache. + <note> + For information on variables affecting sstate, see the + <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link> + and + <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link> + variables. + </note> + </para> + + <para> + The idea of a setscene task (i.e + <filename>do_</filename><replaceable>taskname</replaceable><filename>_setscene</filename>) + is a version of the task where + instead of building something, BitBake can skip to the end + result and simply place a set of files into specific locations + as needed. + In some cases, it makes sense to have a setscene task variant + (e.g. generating package files in the + <filename>do_package_write_*</filename> task). + In other cases, it does not make sense, (e.g. a + <link linkend='ref-tasks-patch'><filename>do_patch</filename></link> + task or + <link linkend='ref-tasks-unpack'><filename>do_unpack</filename></link> + task) since the work involved would be equal to or greater than + the underlying task. + </para> + + <para> + In the OpenEmbedded build system, the common tasks that have + setscene variants are <link linkend='ref-tasks-package'><filename>do_package</filename></link>, + <filename>do_package_write_*</filename>, + <link linkend='ref-tasks-deploy'><filename>do_deploy</filename></link>, + <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link>, + and + <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>. + Notice that these are most of the tasks whose output is an + end result. + </para> + + <para> + The OpenEmbedded build system has knowledge of the relationship + between these tasks and other tasks that precede them. + For example, if BitBake runs + <filename>do_populate_sysroot_setscene</filename> for + something, there is little point in running any of the + <filename>do_fetch</filename>, <filename>do_unpack</filename>, + <filename>do_patch</filename>, + <filename>do_configure</filename>, + <filename>do_compile</filename>, and + <filename>do_install</filename> tasks. + However, if <filename>do_package</filename> needs to be run, + BitBake would need to run those other tasks. + </para> + + <para> + It becomes more complicated if everything can come from an + sstate cache because some objects are simply not required at + all. + For example, you do not need a compiler or native tools, such + as quilt, if there is nothing to compile or patch. + If the <filename>do_package_write_*</filename> packages are + available from sstate, BitBake does not need the + <filename>do_package</filename> task data. + </para> + + <para> + To handle all these complexities, BitBake runs in two phases. + The first is the "setscene" stage. + During this stage, BitBake first checks the sstate cache for + any targets it is planning to build. + BitBake does a fast check to see if the object exists rather + than a complete download. + If nothing exists, the second phase, which is the setscene + stage, completes and the main build proceeds. + </para> + + <para> + If objects are found in the sstate cache, the OpenEmbedded + build system works backwards from the end targets specified + by the user. + For example, if an image is being built, the OpenEmbedded build + system first looks for the packages needed for that image and + the tools needed to construct an image. + If those are available, the compiler is not needed. + Thus, the compiler is not even downloaded. + If something was found to be unavailable, or the download or + setscene task fails, the OpenEmbedded build system then tries + to install dependencies, such as the compiler, from the cache. + </para> + + <para> + The availability of objects in the sstate cache is handled by + the function specified by the + <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_HASHCHECK_FUNCTION'><filename>BB_HASHCHECK_FUNCTION</filename></ulink> + variable and returns a list of the objects that are available. + The function specified by the + <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_SETSCENE_DEPVALID'><filename>BB_SETSCENE_DEPVALID</filename></ulink> + variable is the function that determines whether a given + dependency needs to be followed, and whether for any given + 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> <section id='images-dev-environment'> @@ -1403,6 +1598,10 @@ Specifies whether or not packagedata will be included in the extensible SDK for all recipes in the "world" target. </para></listitem> + <listitem><para><link linkend='var-SDK_INCLUDE_TOOLCHAIN'><filename>SDK_INCLUDE_TOOLCHAIN</filename></link>: + Specifies whether or not the toolchain will be included + when building the extensible SDK. + </para></listitem> <listitem><para><link linkend='var-SDK_LOCAL_CONF_WHITELIST'><filename>SDK_LOCAL_CONF_WHITELIST</filename></link>: A list of variables allowed through from the build system configuration into the extensible SDK configuration. diff --git a/import-layers/yocto-poky/documentation/ref-manual/faq.xml b/import-layers/yocto-poky/documentation/ref-manual/faq.xml index d2e4e8eb1..5f3f17349 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/faq.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/faq.xml @@ -33,9 +33,7 @@ <para id='faq-not-meeting-requirements'> My development system does not meet the required Git, tar, and Python versions. - In particular, I do not have Python 2.7.3 or greater, or - I do have Python 3.x, which is specifically not supported by - the Yocto Project. + In particular, I do not have Python 3.4.0 or greater. Can I still use the Yocto Project? </para> </question> diff --git a/import-layers/yocto-poky/documentation/ref-manual/figures/build-workspace-directory.png b/import-layers/yocto-poky/documentation/ref-manual/figures/build-workspace-directory.png Binary files differnew file mode 100644 index 000000000..5387d33f0 --- /dev/null +++ b/import-layers/yocto-poky/documentation/ref-manual/figures/build-workspace-directory.png diff --git a/import-layers/yocto-poky/documentation/ref-manual/introduction.xml b/import-layers/yocto-poky/documentation/ref-manual/introduction.xml index ce8fa5c65..90d965f6d 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/introduction.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/introduction.xml @@ -47,7 +47,7 @@ <listitem><para><emphasis> <link linkend='usingpoky'>Using the Yocto Project</link>:</emphasis> Provides an overview of the components that make up the Yocto Project - followed by information about debugng images created in the Yocto Project. + followed by information about debugging images created in the Yocto Project. </para></listitem> <listitem><para><emphasis> <link linkend='closer-look'>A Closer Look at the Yocto Project Development Environment</link>:</emphasis> @@ -80,6 +80,11 @@ Describes the tasks defined by the OpenEmbedded build system. </para></listitem> <listitem><para><emphasis> + <link linkend='ref-devtool-reference'><filename>devtool</filename> Quick Reference</link>:</emphasis> + Provides a quick reference for the <filename>devtool</filename> + command. + </para></listitem> + <listitem><para><emphasis> <link linkend='ref-qa-checks'>QA Error and Warning Messages</link>:</emphasis> Lists and describes QA warning and error messages. </para></listitem> @@ -252,12 +257,6 @@ <literallayout class='monospaced'> $ sudo apt-get install make xsltproc docbook-utils fop dblatex xmlto </literallayout></para></listitem> - <listitem><para><emphasis>SDK Installer Extras:</emphasis> - Packages needed if you are going to be using the - the standard or extensible SDK: - <literallayout class='monospaced'> - $ sudo apt-get install autoconf automake libtool libglib2.0-dev libarchive-dev - </literallayout></para></listitem> <listitem><para><emphasis>OpenEmbedded Self-Test (<filename>oe-selftest</filename>):</emphasis> Packages needed if you are going to run <filename>oe-selftest</filename>: @@ -296,17 +295,11 @@ $ sudo dnf install make docbook-style-dsssl docbook-style-xsl \ docbook-dtds docbook-utils fop libxslt dblatex xmlto xsltproc </literallayout></para></listitem> - <listitem><para><emphasis>SDK Installer Extras:</emphasis> - Packages needed if you are going to be using the - standard or extensible SDK: - <literallayout class='monospaced'> - $ sudo dnf install autoconf automake libtool glib2-devel libarchive-devel - </literallayout></para></listitem> <listitem><para><emphasis>OpenEmbedded Self-Test (<filename>oe-selftest</filename>):</emphasis> Packages needed if you are going to run <filename>oe-selftest</filename>: <literallayout class='monospaced'> - $ sudo dnf install GitPython + $ sudo dnf install python3-GitPython </literallayout> </para></listitem> </itemizedlist> @@ -339,12 +332,6 @@ <literallayout class='monospaced'> $ sudo zypper install make fop xsltproc dblatex xmlto </literallayout></para></listitem> - <listitem><para><emphasis>SDK Installer Extras:</emphasis> - Packages needed if you are going to be using the - standard or extensible SDK: - <literallayout class='monospaced'> - $ sudo zypper install autoconf automake libtool glib2-devel libarchive-devel - </literallayout></para></listitem> <listitem><para><emphasis>OpenEmbedded Self-Test (<filename>oe-selftest</filename>):</emphasis> Packages needed if you are going to run <filename>oe-selftest</filename>: @@ -394,12 +381,6 @@ $ sudo yum install make docbook-style-dsssl docbook-style-xsl \ docbook-dtds docbook-utils fop libxslt dblatex xmlto xsltproc </literallayout></para></listitem> - <listitem><para><emphasis>SDK Installer Extras:</emphasis> - Packages needed if you are going to be using the - standard or extensible SDK: - <literallayout class='monospaced'> - $ sudo yum install autoconf automake libtool glib2-devel libarchive-devel - </literallayout></para></listitem> <listitem><para><emphasis>OpenEmbedded Self-Test (<filename>oe-selftest</filename>):</emphasis> Packages needed if you are going to run <filename>oe-selftest</filename>: @@ -422,8 +403,7 @@ <itemizedlist> <listitem><para>Git 1.8.3.1 or greater</para></listitem> <listitem><para>tar 1.24 or greater</para></listitem> - <listitem><para>Python 2.7.3 or greater not including - Python 3.x, which is not supported.</para></listitem> + <listitem><para>Python 3.4.0 or greater</para></listitem> </itemizedlist> </para> diff --git a/import-layers/yocto-poky/documentation/ref-manual/migration.xml b/import-layers/yocto-poky/documentation/ref-manual/migration.xml index e6c0aa36b..3e7e6b084 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/migration.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/migration.xml @@ -2447,8 +2447,8 @@ </literallayout> </para></listitem> <listitem><para> - <filename>d.delVar('</filename><replaceable>varname</replaceable><filename>')</filename> and - <filename>d.setVar('</filename><replaceable>varname</replaceable><filename>', None)</filename> + <filename>d.delVar('</filename><replaceable>VARNAME</replaceable><filename>')</filename> and + <filename>d.setVar('</filename><replaceable>VARNAME</replaceable><filename>', None)</filename> result in the variable and all of its overrides being cleared out. Before the change, only the non-overridden values @@ -2740,13 +2740,13 @@ <para> Variable expressions, such as - <filename>${</filename><replaceable>varname</replaceable><filename>}</filename> + <filename>${</filename><replaceable>VARNAME</replaceable><filename>}</filename> no longer expand automatically within Python functions. Suppressing expansion was done to allow Python functions to construct shell scripts or other code for situations in which you do not want such expressions expanded. For any existing code that relies on these expansions, you need to - change the expansions to either expand the value of individual + change the expansions to expand the value of individual variables through <filename>d.getVar()</filename>. To alternatively expand more complex expressions, use <filename>d.expand()</filename>. @@ -2880,7 +2880,7 @@ to allow the default implementation from the <filename>autotools</filename> class to work such that <filename>autoreconf</filename> succeeds and produces a working - configure script), and to remove the + configure script, and to remove the overridden <filename>do_configure</filename> task such that the default implementation does get used. </para> @@ -2910,7 +2910,8 @@ <filename>do_rootfs</filename>, you should make edits so that those tasks are after the <link linkend='ref-tasks-image-complete'><filename>do_image_complete</filename></link> - task rather than before the task so that the your added tasks + task rather than after <filename>do_rootfs</filename> + so that the your added tasks run at the correct time. </para> @@ -3057,6 +3058,10 @@ <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-extensible'>extensible SDK</ulink>. For information on these SDKs and how to build and use them, see the <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-intro'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>. + <note> + The Yocto Project Eclipse IDE Plug-in is still supported and + is not affected by this change. + </note> </para> </section> @@ -3128,7 +3133,7 @@ The separate <filename>poky-tiny</filename> distribution now uses the musl C library instead of a heavily pared down <filename>glibc</filename>. - Using <filename>glibc</filename> results in a smaller + Using musl results in a smaller distribution and facilitates much greater maintainability because musl is designed to have a small footprint.</para> @@ -3194,6 +3199,21 @@ </para> </section> + <section id='migration-2.1-supporting-gobject-introspection'> + <title>Supporting GObject Introspection</title> + + <para> + This release supports generation of GLib Introspective + Repository (GIR) files through GObject introspection, which is + the standard mechanism for accessing GObject-based software from + runtime environments. + You can enable, disable, and test the generation of this data. + See the + "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-gobject-introspection-support'>Enabling GObject Introspection Support</ulink>" + section for more information. + </para> + </section> + <section id='migration-2.1-miscellaneous-changes'> <title>Miscellaneous Changes</title> @@ -3205,6 +3225,9 @@ If your host distribution does not provide a sufficiently recent version, you can install the buildtools, which will provide it. + See the + "<link linkend='required-git-tar-and-python-versions'>Required Git, tar, and Python Versions</link>" + section for more information on the buildtools tarball. </para></listitem> <listitem><para> The buggy and incomplete support for the RPM version 4 @@ -3213,6 +3236,25 @@ remains. </para></listitem> <listitem><para> + Previously, the following list of packages were removed + if package-management was not in + <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>, + regardless of any dependencies: + <literallayout class='monospaced'> + update-rc.d + base-passwd + shadow + update-alternatives + run-postinsts + </literallayout> + With the Yocto Project 2.1 release, these packages are only + removed if "read-only-rootfs" is in + <filename>IMAGE_FEATURES</filename>, since they might + still be needed for a read-write image even in the absence + of a package manager (e.g. if users need to be added, + modified, or removed at runtime). + </para></listitem> + <listitem><para> The <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-devtool-use-devtool-modify-to-modify-the-source-of-an-existing-component'><filename>devtool modify</filename></ulink> command now defaults to extracting the source since that @@ -3220,7 +3262,7 @@ The "-x" or "--extract" options are now no-ops. If you wish to provide your own existing source tree, you will now need to specify either the "-n" or - "--no-extract" option when running + "--no-extract" options when running <filename>devtool modify</filename>. </para></listitem> <listitem><para> @@ -3228,10 +3270,8 @@ or does not specify whether a keyboard is attached, then the default is to assume a keyboard is attached rather than assume no keyboard. - <note> - This change primarily affects the Sato UI. - </note> - </para></listitem> + This change primarily affects the Sato UI. + </para></listitem> <listitem><para> The <filename>.debug</filename> directory packaging is now automatic. @@ -3248,8 +3288,8 @@ This data has been replaced with <filename>getrusage()</filename> data and corrected IO statistics. - You will probably need to update code that reads the - <filename>buildstats</filename> data. + You will probably need to update any custom code that reads + the <filename>buildstats</filename> data. </para></listitem> <listitem><para> The @@ -3272,8 +3312,622 @@ <filename>meta-yocto-bsp</filename> layer. Most modern x86 boards do not rely on this file and it only adds kernel error messages during startup. - If you do still need the file, you can simply add - <filename>v86d</filename> to your image. + If you do still need to support + <filename>uvesafb</filename>, you can + simply add <filename>v86d</filename> to your image. + </para></listitem> + <listitem><para> + Build sysroot paths are now removed from debug symbol + files. + Removing these paths means that remote GDB using an + unstripped build system sysroot will no longer work + (although this was never documented to work). + The supported method to accomplish something similar is + to set <filename>IMAGE_GEN_DEBUGFS</filename> to "1", + which will generate a companion debug image + containing unstripped binaries and associated debug + sources alongside the image. + </para></listitem> + </itemizedlist> + </para> + </section> +</section> + +<section id='moving-to-the-yocto-project-2.2-release'> + <title>Moving to the Yocto Project 2.2 Release</title> + + <para> + This section provides migration information for moving to the + Yocto Project 2.2 Release from the prior release. + </para> + + <section id='migration-2.2-minimum-kernel-version'> + <title>Minimum Kernel Version</title> + + <para> + The minimum kernel version for the target system and for SDK + is now 3.2.0, due to the upgrade + to <filename>glibc 2.24</filename>. + Specifically, for AArch64-based targets the version is + 3.14. + For Nios II-based targets, the minimum kernel version is 3.19. + <note> + For x86 and x86_64, you can reset + <link linkend='var-OLDEST_KERNEL'><filename>OLDEST_KERNEL</filename></link> + to anything down to 2.6.32 if desired. + </note> + </para> + </section> + + <section id='migration-2.2-staging-directories-in-sysroot-simplified'> + <title>Staging Directories in Sysroot Has Been Simplified</title> + + <para> + The way directories are staged in sysroot has been simplified and + introduces the new + <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>. + See the + <ulink url='http://lists.openembedded.org/pipermail/openembedded-core/2016-May/121365.html'>v2 patch series on the OE-Core Mailing List</ulink> + for additional information. + </para> + </section> + + <section id='migration-2.2-removal-of-old-images-from-tmp-deploy-now-enabled'> + <title>Removal of Old Images and Other Files in <filename>tmp/deploy</filename> Now Enabled</title> + + <para> + Removal of old images and other files in + <filename>tmp/deploy/</filename> is now enabled by default due + to a new staging method used for those files. + As a result of this change, the + <filename>RM_OLD_IMAGE</filename> variable is now redundant. + </para> + </section> + + <section id='migration-2.2-python-changes'> + <title>Python Changes</title> + + <para> + The following changes for Python occurred: + </para> + + <section id='migration-2.2-bitbake-now-requires-python-3.4'> + <title>BitBake Now Requires Python 3.4+</title> + + <para> + BitBake requires Python 3.4 or greater. + </para> + </section> + + <section id='migration-2.2-utf-8-locale-required-on-build-host'> + <title>UTF-8 Locale Required on Build Host</title> + + <para> + A UTF-8 locale is required on the build host due to Python 3. + Since C.UTF-8 is not a standard, the default is en_US.UTF-8. + </para> + </section> + + <section id='migration-2.2-metadata-now-must-use-python-3-syntax'> + <title>Metadata Must Now Use Python 3 Syntax</title> + + <para> + The metadata is now required to use Python 3 syntax. + For help preparing metadata, see any of the many Python 3 porting + guides available. + Alternatively, you can reference the conversion commits for Bitbake + and you can use OE-Core as a guide for changes. + Following are particular areas of interest: + <literallayout class='monospaced'> + * subprocess command-line pipes needing locale decoding + * the syntax for octal values changed + * the <filename>iter*()</filename> functions changed name + * iterators now return views, not lists + * changed names for Python modules + </literallayout> + </para> + </section> + + <section id='migration-2.2-target-python-recipes-switched-to-python-3'> + <title>Target Python Recipes Switched to Python 3</title> + + <para> + Most target Python recipes have now been switched to Python 3. + Unfortunately, systems using RPM as a package manager and + providing online package-manager support through SMART still + require Python 2. + <note> + Python 2 and recipes that use it can still be built for the + target as with previous versions. + </note> + </para> + </section> + + <section id='migration-2.2-buildtools-tarball-includes-python-3'> + <title><filename>buildtools-tarball</filename> Includes Python 3</title> + + <para> + <filename>buildtools-tarball</filename> now includes Python 3. + </para> + </section> + </section> + + <section id='migration-2.2-uclibc-replaced-by-musl'> + <title>uClibc Replaced by musl</title> + + <para> + uClibc has been removed in favor of musl. + Musl has matured, is better maintained, and is compatible with a + wider range of applications as compared to uClibc. + </para> + </section> + + <section id='migration-2.2-B-no-longer-default-working-directory-for-tasks'> + <title><filename>${B}</filename> No Longer Default Working Directory for Tasks</title> + + <para> + <filename>${</filename><link linkend='var-B'><filename>B</filename></link><filename>}</filename> + is no longer the default working directory for tasks. + Consequently, any custom tasks you define now need to either + have the + <filename>[</filename><ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>dirs</filename></ulink><filename>]</filename> flag set, or the task needs to change into the + appropriate working directory manually (e.g using + <filename>cd</filename> for a shell task). + <note> + The preferred method is to use the + <filename>[dirs]</filename> flag. + </note> + </para> + </section> + + <section id='migration-2.2-runqemu-ported-to-python'> + <title><filename>runqemu</filename> Ported to Python</title> + + <para> + <filename>runqemu</filename> has been ported to Python and has + changed behavior in some cases. + Previous usage patterns continued to be supported. + </para> + + <para> + The new <filename>runqemu</filename> is a Python script. + Machine knowledge is no longer hardcoded into + <filename>runqemu</filename>. + You can choose to use the <filename>qemuboot</filename> + configuration file to define the BSP's own arguments and to make + it bootable with <filename>runqemu</filename>. + If you use a configuration file, use the following form: + <literallayout class='monospaced'> + <replaceable>image-name</replaceable>-<replaceable>machine</replaceable>.qemuboot.conf + </literallayout> + The configuration file enables fine-grained tuning of options + passed to QEMU without the <filename>runqemu</filename> script + hard-coding any knowledge about different machines. + Using a configuration file is particularly convenient when trying + to use QEMU with machines other than the + <filename>qemu*</filename> machines in OE-Core. + The <filename>qemuboot.conf</filename> file is generated by the + <filename>qemuboot</filename> + class when the root filesystem is being build (i.e. + build rootfs). + QEMU boot arguments can be set in BSP's configuration file and + the <filename>qemuboot</filename> class will save them to + <filename>qemuboot.conf</filename>. + </para> + + + <para> + If you want to use <filename>runqemu</filename> without a + configuration file, use the following command form: + <literallayout class='monospaced'> + $ runqemu <replaceable>machine</replaceable> <replaceable>rootfs</replaceable> <replaceable>kernel</replaceable> [<replaceable>options</replaceable>] + </literallayout> + Supported <replaceable>machines</replaceable> are as follows: + <literallayout class='monospaced'> + qemuarm + qemuarm64 + qemux86 + qemux86-64 + qemuppc + qemumips + qemumips64 + qemumipsel + qemumips64el + </literallayout> + Consider the following example, which uses the + <filename>qemux86-64</filename> machine, + provides a root filesystem, provides an image, and uses + the <filename>nographic</filename> option: + <literallayout class='monospaced'> +$ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.ext4 tmp/deploy/images/qemux86-64/bzImage nographic + </literallayout> + </para> + + <para> + Following is a list of variables that can be set in configuration + files such as <filename>bsp.conf</filename> to enable the BSP + to be booted by <filename>runqemu</filename>: + <note> + "QB" means "QEMU Boot". + </note> + <literallayout class='monospaced'> + QB_SYSTEM_NAME: QEMU name (e.g. "qemu-system-i386") + QB_OPT_APPEND: Options to append to QEMU (e.g. "-show-cursor") + QB_DEFAULT_KERNEL: Default kernel to boot (e.g. "bzImage") + QB_DEFAULT_FSTYPE: Default FSTYPE to boot (e.g. "ext4") + QB_MEM: Memory (e.g. "-m 512") + QB_MACHINE: QEMU machine (e.g. "-machine virt") + QB_CPU: QEMU cpu (e.g. "-cpu qemu32") + QB_CPU_KVM: Similar to QB_CPU except used for kvm support (e.g. "-cpu kvm64") + QB_KERNEL_CMDLINE_APPEND: Options to append to the kernel's -append + option (e.g. "console=ttyS0 console=tty") + QB_DTB: QEMU dtb name + QB_AUDIO_DRV: QEMU audio driver (e.g. "alsa", set it when support audio) + QB_AUDIO_OPT: QEMU audio option (e.g. "-soundhw ac97,es1370"), which is used + when QB_AUDIO_DRV is set. + QB_KERNEL_ROOT: Kernel's root (e.g. /dev/vda) + QB_TAP_OPT: Network option for 'tap' mode (e.g. + "-netdev tap,id=net0,ifname=@TAP@,script=no,downscript=no -device virtio-net-device,netdev=net0"). + runqemu will replace "@TAP@" with the one that is used, such as tap0, tap1 ... + QB_SLIRP_OPT: Network option for SLIRP mode (e.g. "-netdev user,id=net0 -device virtio-net-device,netdev=net0") + QB_ROOTFS_OPT: Used as rootfs (e.g. + "-drive id=disk0,file=@ROOTFS@,if=none,format=raw -device virtio-blk-device,drive=disk0"). + runqemu will replace "@ROOTFS@" with the one which is used, such as + core-image-minimal-qemuarm64.ext4. + QB_SERIAL_OPT: Serial port (e.g. "-serial mon:stdio") + QB_TCPSERIAL_OPT: tcp serial port option (e.g. + " -device virtio-serial-device -chardev socket,id=virtcon,port=@PORT@,host=127.0.0.1 -device virtconsole,chardev=virtcon" + runqemu will replace "@PORT@" with the port number which is used. + </literallayout> + </para> + + <para> + To use <filename>runqemu</filename>, set + <link linkend='var-IMAGE_CLASSES'><filename>IMAGE_CLASSES</filename></link> + as follows and run <filename>runqemu</filename>: + <note> + For command-line syntax, use + <filename>runqemu help</filename>. + </note> + <literallayout class='monospaced'> + IMAGE_CLASSES += "qemuboot" + </literallayout> + </para> + </section> + + <section id='migration-2.2-default-linker-hash-style-changed'> + <title>Default Linker Hash Style Changed</title> + + <para> + The default linker hash style for <filename>gcc-cross</filename> + is now "sysv" in order to catch recipes that are building software + without using the OpenEmbedded + <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>. + This change could result in seeing some "No GNU_HASH in the elf + binary" QA issues when building such recipes. + You need to fix these recipes so that they use the expected + <filename>LDFLAGS</filename>. + Depending on how the software is built, the build system used by + the software (e.g. a Makefile) might need to be patched. + However, sometimes making this fix is as simple as adding the + following to the recipe: + <literallayout class='monospaced'> + TARGET_CC_ARCH += "${LDFLAGS}" + </literallayout> + </para> + </section> + + <section id='migration-2.2-bitbake-changes'> + <title>BitBake Changes</title> + + <para> + The following changes took place for BitBake: + <itemizedlist> + <listitem><para> + The "goggle" UI and standalone image-writer tool have + been removed as they both require GTK+ 2.0 and + were not being maintained. + </para></listitem> + <listitem><para> + The Perforce fetcher now supports + <link linkend='var-SRCREV'><filename>SRCREV</filename></link> + for specifying the source revision to use, be it + <filename>${</filename><link linkend='var-AUTOREV'><filename>AUTOREV</filename></link><filename>}</filename>, + changelist number, p4date, or label, in preference to + separate + <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link> + parameters to specify these. + This change is more in-line with how the other fetchers + work for source control systems. + Recipes that fetch from Perforce will need to be updated + to use <filename>SRCREV</filename> in place of specifying + the source revision within + <filename>SRC_URI</filename>. + </para></listitem> + <listitem><para> + Some of BitBake's internal code structures for accessing + the recipe cache needed to be changed to support the new + multi-configuration functionality. + These changes will affect external tools that use BitBake's + tinfoil module. + For information on these changes, see the changes made to + the scripts supplied with OpenEmbedded-Core: + <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=189371f8393971d00bca0fceffd67cc07784f6ee'>1</ulink> + and + <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=4a5aa7ea4d07c2c90a1654b174873abb018acc67'>2</ulink>. + </para></listitem> + <listitem><para> + The task management code has been rewritten to avoid using + ID indirection in order to improve performance. + This change is unlikely to cause any problems for most + users. + However, the setscene verification function as pointed to + 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> + has been added allowing multiple versions of BitBake + to work with suitably written metadata, which includes + OpenEmbedded-Core and Poky. + Anyone with custom BitBake task scheduler code might also + need to update the code to handle the new structure. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.2-swabber-has-been-removed'> + <title>Swabber has Been Removed</title> + + <para> + Swabber, a tool that was intended to detect host contamination in + the build process, has been removed, as it has been unmaintained + and unused for some time and was never particularly effective. + The OpenEmbedded build system has since incorporated a number of + mechanisms including enhanced QA checks that mean that there is + less of a need for such a tool. + </para> + </section> + + <section id='migration-2.2-removed-recipes'> + <title>Removed Recipes</title> + + <para> + The following recipes have been removed: + <itemizedlist> + <listitem><para> + <filename>augeas</filename>: + No longer needed and has been moved to + <filename>meta-oe</filename>. + </para></listitem> + <listitem><para> + <filename>directfb</filename>: + Unmaintained and has been moved to + <filename>meta-oe</filename>. + </para></listitem> + <listitem><para> + <filename>gcc</filename>: + Removed 4.9 version. + Versions 5.4 and 6.2 are still present. + </para></listitem> + <listitem><para> + <filename>gnome-doc-utils</filename>: + No longer needed. + </para></listitem> + <listitem><para> + <filename>gtk-doc-stub</filename>: + Replaced by <filename>gtk-doc</filename>. + </para></listitem> + <listitem><para> + <filename>gtk-engines</filename>: + No longer needed and has been moved to + <filename>meta-gnome</filename>. + </para></listitem> + <listitem><para> + <filename>gtk-sato-engine</filename>: + Became obsolete. + </para></listitem> + <listitem><para> + <filename>libglade</filename>: + No longer needed and has been moved to + <filename>meta-oe</filename>. + </para></listitem> + <listitem><para> + <filename>libmad</filename>: + Unmaintained and functionally replaced by + <filename>libmpg123</filename>. + <filename>libmad</filename> has been moved to + <filename>meta-oe</filename>. + </para></listitem> + <listitem><para> + <filename>libowl</filename>: + Became obsolete. + </para></listitem> + <listitem><para> + <filename>libxsettings-client</filename>: + No longer needed. + </para></listitem> + <listitem><para> + <filename>oh-puzzles</filename>: + Functionally replaced by + <filename>puzzles</filename>. + </para></listitem> + <listitem><para> + <filename>oprofileui</filename>: + Became obsolete. + OProfile has been largely supplanted by perf. + </para></listitem> + <listitem><para> + <filename>packagegroup-core-directfb.bb</filename>: + Removed. + </para></listitem> + <listitem><para> + <filename>core-image-directfb.bb</filename>: + Removed. + </para></listitem> + <listitem><para> + <filename>pointercal</filename>: + No longer needed and has been moved to + <filename>meta-oe</filename>. + </para></listitem> + <listitem><para> + <filename>python-imaging</filename>: + No longer needed and moved to + <filename>meta-python</filename> + </para></listitem> + <listitem><para> + <filename>python-pyrex</filename>: + No longer needed and moved to + <filename>meta-python</filename>. + </para></listitem> + <listitem><para> + <filename>sato-icon-theme</filename>: + Became obsolete. + </para></listitem> + <listitem><para> + <filename>swabber-native</filename>: + Swabber has been removed. + See the + <link linkend='migration-2.2-swabber-has-been-removed'>entry on Swabber</link>. + </para></listitem> + <listitem><para> + <filename>tslib</filename>: + No longer needed and has been moved to + <filename>meta-oe</filename>. + </para></listitem> + <listitem><para> + <filename>uclibc</filename>: + Removed in favor of musl. + </para></listitem> + <listitem><para> + <filename>xtscal</filename>: + No longer needed and moved to + <filename>meta-oe</filename> + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.2-removed-classes'> + <title>Removed Classes</title> + + <para> + The following classes have been removed: + <itemizedlist> + <listitem><para> + <filename>distutils-native-base</filename>: + No longer needed. + </para></listitem> + <listitem><para> + <filename>distutils3-native-base</filename>: + No longer needed. + </para></listitem> + <listitem><para> + <filename>sdl</filename>: + Only set + <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link> + and + <link linkend='var-SECTION'><filename>SECTION</filename></link>, + which are better set within the recipe instead. + </para></listitem> + <listitem><para> + <filename>sip</filename>: + Mostly unused. + </para></listitem> + <listitem><para> + <filename>swabber</filename>: + See the + <link linkend='migration-2.2-swabber-has-been-removed'>entry on Swabber</link>. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.2-minor-packaging-changes'> + <title>Minor Packaging Changes</title> + + <para> + The following minor packaging changes have occurred: + <itemizedlist> + <listitem><para> + <filename>grub</filename>: + Split <filename>grub-editenv</filename> into its own + package. + </para></listitem> + <listitem><para> + <filename>systemd</filename>: + Split container and vm related units into a new package, + systemd-container. + </para></listitem> + <listitem><para> + <filename>util-linux</filename>: + Moved <filename>prlimit</filename> to a separate + <filename>util-linux-prlimit</filename> package. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.2-miscellaneous-changes'> + <title>Miscellaneous Changes</title> + + <para> + The following miscellaneous changes have occurred: + <itemizedlist> + <listitem><para> + <filename>package_regex.inc</filename>: + Removed because the definitions + <filename>package_regex.inc</filename> previously contained + have been moved to their respective recipes. + </para></listitem> + <listitem><para> + Both <filename>devtool add</filename> and + <filename>recipetool create</filename> now use a fixed + <link linkend='var-SRCREV'><filename>SRCREV</filename></link> + by default when fetching from a Git repository. + You can override this in either case to use + <filename>${</filename><link linkend='var-AUTOREV'><filename>AUTOREV</filename></link><filename>}</filename> + instead by using the <filename>-a</filename> or + <filename>‐‐autorev</filename> command-line + option + </para></listitem> + <listitem><para> + <filename>distcc</filename>: + GTK+ UI is now disabled by default. + </para></listitem> + <listitem><para> + <filename>packagegroup-core-tools-testapps</filename>: + Removed Piglit. + </para></listitem> + <listitem><para> + <filename>image.bbclass</filename>: + Renamed COMPRESS(ION) to CONVERSION. + This change means that + <filename>COMPRESSIONTYPES</filename>, + <filename>COMPRESS_DEPENDS</filename> and + <filename>COMPRESS_CMD</filename> are deprecated in favor + of <filename>CONVERSIONTYPES</filename>, + <filename>CONVERSION_DEPENDS</filename> and + <filename>CONVERSION_CMD</filename>. + The <filename>COMPRESS*</filename> variable names will + still work in the 2.2 release but metadata that does not + need to be backwards-compatible should be changed to + use the new names as the <filename>COMPRESS*</filename> + ones will be removed in a future release. + </para></listitem> + <listitem><para> + <filename>gtk-doc</filename>: + A full version of <filename>gtk-doc</filename> is now + made available. + However, some old software might not be capable of using + the current version of <filename>gtk-doc</filename> + to build documentation. + You need to change recipes that build such software so that + they explicitly disable building documentation with + <filename>gtk-doc</filename>. </para></listitem> </itemizedlist> </para> 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 e919bd7eb..2344a0406 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/ref-classes.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/ref-classes.xml @@ -161,13 +161,17 @@ cross-compilation. You can pass additional parameters to <filename>configure</filename> through the - <filename><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link></filename> variable. + <filename><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link></filename> + or + <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link> + variables. </para></listitem> <listitem><para><link linkend='ref-tasks-compile'><filename>do_compile</filename></link> - Runs <filename>make</filename> with arguments that specify the compiler and linker. You can pass additional arguments through - the <filename><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></filename> variable. + the <filename><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></filename> + variable. </para></listitem> <listitem><para><link linkend='ref-tasks-install'><filename>do_install</filename></link> - Runs <filename>make install</filename> and passes in @@ -194,7 +198,14 @@ class or the <link linkend='ref-classes-package'><filename>package</filename></link> class. + </para> + + <para> The class also contains some commonly used functions such as + <filename>oe_runmake</filename>, which runs + <filename>make</filename> with the arguments specified in + <link linkend='var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></link> + variable as well as the arguments passed directly to <filename>oe_runmake</filename>. </para> </section> @@ -1092,36 +1103,6 @@ </para> </section> -<section id='ref-classes-gummiboot'> - <title><filename>gummiboot.bbclass</filename></title> - - <para> - The <filename>gummiboot</filename> class provides functions specific - to the gummiboot bootloader for building bootable images. - This is an internal class and is not intended to be - used directly. - Set the - <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link> - variable to "gummiboot" to use this class. - </para> - - <para> - For information on more variables used and supported in this class, - see the - <link linkend='var-GUMMIBOOT_CFG'><filename>GUMMIBOOT_CFG</filename></link>, - <link linkend='var-GUMMIBOOT_ENTRIES'><filename>GUMMIBOOT_ENTRIES</filename></link>, - and - <link linkend='var-GUMMIBOOT_TIMEOUT'><filename>GUMMIBOOT_TIMEOUT</filename></link> - variables. - </para> - - <para> - You can also see the - <ulink url='http://freedesktop.org/wiki/Software/gummiboot/'>Gummiboot documentation</ulink> - for more information. - </para> -</section> - <section id='ref-classes-gzipnative'> <title><filename>gzipnative.bbclass</filename></title> @@ -1381,22 +1362,6 @@ </para> </section> -<section id='ref-classes-image-swab'> - <title><filename>image-swab.bbclass</filename></title> - - <para> - The <filename>image-swab</filename> class enables the - <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/swabber'>Swabber</ulink> - tool in order to detect and log accesses to the host system during - the OpenEmbedded build process. - <note> - This class is currently unmaintained. - The <filename>strace</filename> package needs to be installed - in the build host as a dependency for this tool. - </note> - </para> -</section> - <section id='ref-classes-image-vm'> <title><filename>image-vm.bbclass</filename></title> @@ -1599,6 +1564,17 @@ <link linkend='var-FILES'><filename>FILES</filename></link> variable values that contain "//", which is invalid. </para></listitem> + <listitem><para><emphasis><filename>host-user-contaminated:</filename></emphasis> + Checks that no package produced by the recipe contains any + files outside of <filename>/home</filename> with a user or + group ID that matches the user running BitBake. + A match usually indicates that the files are being installed + with an incorrect UID/GID, since target IDs are independent + from host IDs. + For additional information, see the section describing the + <link linkend='ref-tasks-install'><filename>do_install</filename></link> + task. + </para></listitem> <listitem><para><emphasis><filename>incompatible-license:</filename></emphasis> Report when packages are excluded from being created due to being marked with a license that is in @@ -1626,6 +1602,25 @@ <filename>do_install</filename> if the files are not needed in any package. </para></listitem> + <listitem><para><emphasis><filename>invalid-chars:</filename></emphasis> + Checks that the recipe metadata variables + <link linkend='var-DESCRIPTION'><filename>DESCRIPTION</filename></link>, + <link linkend='var-SUMMARY'><filename>SUMMARY</filename></link>, + <link linkend='var-LICENSE'><filename>LICENSE</filename></link>, + and + <link linkend='var-SECTION'><filename>SECTION</filename></link> + do not contain non-UTF-8 characters. + Some package managers do not support such characters. + </para></listitem> + <listitem><para><emphasis><filename>invalid-packageconfig:</filename></emphasis> + Checks that no undefined features are being added to + <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link>. + For example, any name "foo" for which the following form + does not exist: + <literallayout class='monospaced'> + PACKAGECONFIG[foo] = "..." + </literallayout> + </para></listitem> <listitem><para><emphasis><filename>la:</filename></emphasis> Checks <filename>.la</filename> files for any <filename>TMPDIR</filename> paths. @@ -3294,6 +3289,43 @@ </para> </section> +<section id='ref-classes-systemd-boot'> + <title><filename>systemd-boot.bbclass</filename></title> + + <para> + The <filename>systemd-boot</filename> class provides functions specific + to the systemd-boot bootloader for building bootable images. + This is an internal class and is not intended to be used directly. + <note> + The <filename>systemd-boot</filename> class is a result from + merging the <filename>gummiboot</filename> class used in previous + Yocto Project releases with the <filename>systemd</filename> + project. + </note> + Set the + <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link> + variable to "systemd-boot" to use this class. + Doing so creates a standalone EFI bootloader that is not dependent + on systemd. + </para> + + <para> + For information on more variables used and supported in this class, + see the + <link linkend='var-SYSTEMD_BOOT_CFG'><filename>SYSTEMD_BOOT_CFG</filename></link>, + <link linkend='var-SYSTEMD_BOOT_ENTRIES'><filename>SYSTEMD_BOOT_ENTRIES</filename></link>, + and + <link linkend='var-SYSTEMD_BOOT_TIMEOUT'><filename>SYSTEMD_BOOT_TIMEOUT</filename></link> + variables. + </para> + + <para> + You can also see the + <ulink url='http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/'>Systemd-boot documentation</ulink> + for more information. + </para> +</section> + <section id='ref-classes-terminal'> <title><filename>terminal.bbclass</filename></title> @@ -3698,7 +3730,9 @@ software that uses the Waf build system. You can use the <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link> - variable to specify additional configuration options to be passed on + or + <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link> + variables to specify additional configuration options to be passed on the Waf command line. </para> </section> 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 new file mode 100644 index 000000000..1764f0196 --- /dev/null +++ b/import-layers/yocto-poky/documentation/ref-manual/ref-devtool-reference.xml @@ -0,0 +1,607 @@ +<!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-devtool-reference'> + <title><filename>devtool</filename> Quick Reference</title> + + <para> + The <filename>devtool</filename> command-line tool provides a number + of features that help you build, test, and package software. + This command is available alongside the <filename>bitbake</filename> + command. + Additionally, the <filename>devtool</filename> command is a key + part of the extensible SDK. + </para> + + <para> + This chapter provides a Quick Reference for the + <filename>devtool</filename> command. + For more information on how to apply the command when using the + extensible SDK, see the + "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-extensible'>Using the Extensible SDK</ulink>" + section in the Yocto Project Software Development Kit (SDK) Developer's + Guide. + </para> + + <section id='devtool-getting-help'> + <title>Getting Help</title> + + <para> + The <filename>devtool</filename> command line is organized + similarly to Git in that it has a number of sub-commands for + each function. + You can run <filename>devtool --help</filename> to see all + the commands: + <literallayout class='monospaced'> + $ devtool --help + usage: devtool [--basepath BASEPATH] [--bbpath BBPATH] [-d] [-q] + [--color COLOR] [-h] + <subcommand> ... + + OpenEmbedded development tool + + options: + --basepath BASEPATH Base directory of SDK / build directory + --bbpath BBPATH Explicitly specify the BBPATH, rather than getting it + from the metadata + -d, --debug Enable debug output + -q, --quiet Print only errors + --color COLOR Colorize output (where COLOR is auto, always, never) + -h, --help show this help message and exit + + subcommands: + Beginning work on a recipe: + add Add a new recipe + modify Modify the source for an existing recipe + upgrade Upgrade an existing recipe + Getting information: + status Show workspace status + search Search available recipes + Working on a recipe in the workspace: + edit-recipe Edit a recipe file in your workspace + configure-help Get help on configure script options + build Build a recipe + update-recipe Apply changes from external source tree to recipe + reset Remove a recipe from your workspace + finish Finish working on a recipe in your workspace + Testing changes on target: + deploy-target Deploy recipe output files to live target machine + undeploy-target Undeploy recipe output files in live target machine + build-image Build image including workspace recipe packages + Advanced: + create-workspace Set up workspace in an alternative location + extract Extract the source for an existing recipe + sync Synchronize the source tree for an existing recipe + Use devtool <subcommand> --help to get help on a specific command + </literallayout> + </para> + + <para> + As directed in the general help output, you can get more + syntax on a specific command by providing the command + name and using <filename>--help</filename>: + <literallayout class='monospaced'> + $ devtool add --help + usage: devtool add [-h] [--same-dir | --no-same-dir] [--fetch URI] + [--version VERSION] [--no-git] [--autorev] [--binary] + [--also-native] [--src-subdir SUBDIR] + [recipename] [srctree] [fetchuri] + + Adds a new recipe to the workspace to build a specified source tree. Can + optionally fetch a remote URI and unpack it to create the source tree. + + arguments: + recipename Name for new recipe to add (just name - no version, + path or extension). If not specified, will attempt to + auto-detect it. + srctree Path to external source tree. If not specified, a + subdirectory of + /home/scottrif/poky/build/workspace/sources will be + used. + fetchuri Fetch the specified URI and extract it to create the + source tree + + options: + -h, --help show this help message and exit + --same-dir, -s Build in same directory as source + --no-same-dir Force build in a separate build directory + --fetch URI, -f URI Fetch the specified URI and extract it to create the + source tree (deprecated - pass as positional argument + instead) + --version VERSION, -V VERSION + Version to use within recipe (PV) + --no-git, -g If fetching source, do not set up source tree as a git + repository + --autorev, -a When fetching from a git repository, set SRCREV in the + recipe to a floating revision instead of fixed + --binary, -b Treat the source tree as something that should be + installed verbatim (no compilation, same directory + structure). Useful with binary packages e.g. RPMs. + --also-native Also add native variant (i.e. support building recipe + for the build host as well as the target machine) + --src-subdir SUBDIR Specify subdirectory within source tree to use + </literallayout> + </para> + </section> + + <section id='devtool-the-workspace-layer-structure'> + <title>The Workspace Layer Structure</title> + + <para> + <filename>devtool</filename> uses a "Workspace" layer + in which to accomplish builds. + This layer is not specific to any single + <filename>devtool</filename> command but is rather a common + working area used across the tool. + </para> + + <para> + The following figure shows the workspace structure: + </para> + + <para> + <imagedata fileref="figures/build-workspace-directory.png" + width="6in" depth="5in" align="left" scale="70" /> + </para> + + <para> + <literallayout class='monospaced'> + attic - A directory created if devtool believes it preserve + anything when you run "devtool reset". For example, if you + run "devtool add", make changes to the recipe, and then + run "devtool reset", devtool takes notice that the file has + been changed and moves it into the attic should you still + want the recipe. + + README - Provides information on what is in workspace layer and how to + manage it. + + .devtool_md5 - A checksum file used by devtool. + + appends - A directory that contains *.bbappend files, which point to + external source. + + conf - A configuration directory that contains the layer.conf file. + + recipes - A directory containing recipes. This directory contains a + folder for each directory added whose name matches that of the + added recipe. devtool places the <replaceable>recipe</replaceable>.bb file + within that sub-directory. + + sources - A directory containing a working copy of the source files used + when building the recipe. This is the default directory used + as the location of the source tree when you do not provide a + source tree path. This directory contains a folder for each + set of source files matched to a corresponding recipe. + </literallayout> + </para> + </section> + + <section id='devtool-adding-a-new-recipe-to-the-workspace'> + <title>Adding a New Recipe to the Workspace Layer</title> + + <para> + Use the <filename>devtool add</filename> command to add a new recipe + to the workspace layer. + The recipe you add should not exist - + <filename>devtool</filename> creates it for you. + The source files the recipe uses should exist in an external + area. + </para> + + <para> + The following example creates and adds a new recipe named + <filename>jackson</filename> to a workspace layer the tool creates. + The source code built by the recipes resides in + <filename>/home/scottrif/sources/jackson</filename>: + <literallayout class='monospaced'> + $ devtool add jackson /home/scottrif/sources/jackson + </literallayout> + </para> + + <para> + If you add a recipe and the workspace layer does not exist, + the command creates the layer and populates it as + described in + "<link linkend='devtool-the-workspace-layer-structure'>The Workspace Layer Structure</link>" + section. + </para> + + <para> + Running <filename>devtool add</filename> when the + workspace layer exists causes the tool to add the recipe, + append files, and source files into the existing workspace layer. + The <filename>.bbappend</filename> file is created to point + to the external source tree. + </para> + </section> + + <section id='devtool-extracting-the-source-for-an-existing-recipe'> + <title>Extracting the Source for an Existing Recipe</title> + + <para> + Use the <filename>devtool extract</filename> command to + extract the source for an existing recipe. + When you use this command, you must supply the root name + of the recipe (i.e. no version, paths, or extensions), and + you must supply the directory to which you want the source + extracted. + </para> + + <para> + Additional command options let you control the name of a + development branch into which you can checkout the source + and whether or not to keep a temporary directory, which is + useful for debugging. + </para> + </section> + + <section id='devtool-synchronizing-a-recipes-extracted-source-tree'> + <title>Synchronizing a Recipe's Extracted Source Tree</title> + + <para> + Use the <filename>devtool sync</filename> command to + synchronize a previously extracted source tree for an + existing recipe. + When you use this command, you must supply the root name + of the recipe (i.e. no version, paths, or extensions), and + you must supply the directory to which you want the source + extracted. + </para> + + <para> + Additional command options let you control the name of a + development branch into which you can checkout the source + and whether or not to keep a temporary directory, which is + useful for debugging. + </para> + </section> + + <section id='devtool-modifying-a-recipe'> + <title>Modifying an Existing Recipe</title> + + <para> + Use the <filename>devtool modify</filename> command to begin + modifying the source of an existing recipe. + This command is very similar to the + <ulink url='&YOCTO_DOCS_DEV_URL;#devtool-adding-a-new-recipe-to-the-workspace'><filename>add</filename></ulink> + command except that it does not physically create the + recipe in the workspace layer because the recipe already + exists in an another layer. + </para> + + <para> + The <filename>devtool modify</filename> command extracts the + source for a recipe, sets it up as a Git repository if the + source had not already been fetched from Git, checks out a + branch for development, and applies any patches from the recipe + as commits on top. + You can use the following command to checkout the source + files: + <literallayout class='monospaced'> + $ devtool modify <replaceable>recipe</replaceable> + </literallayout> + Using the above command form, <filename>devtool</filename> uses + the existing recipe's + <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link> + statement to locate the upstream source, extracts the source + into the default sources location in the workspace. + The default development branch used is "devtool". + </para> + </section> + + <section id='devtool-edit-an-existing-recipe'> + <title>Edit an Existing Recipe</title> + + <para> + Use the <filename>devtool edit-recipe</filename> command + to run the default editor, which is identified using the + <filename>EDITOR</filename> variable, on the specified recipe. + </para> + + <para> + When you use the <filename>devtool edit-recipe</filename> + command, you must supply the root name of the recipe + (i.e. no version, paths, or extensions). + Also, the recipe file itself must reside in the workspace + as a result of the <filename>devtool add</filename> or + <filename>devtool upgrade</filename> commands. + However, you can override that requirement by using the + "-a" or "--any-recipe" option. + Using either of these options allows you to edit any recipe + regardless of its location. + </para> + </section> + + <section id='devtool-updating-a-recipe'> + <title>Updating a Recipe</title> + + <para> + Use the <filename>devtool update-recipe</filename> command to + update your recipe with patches that reflect changes you make + to the source files. + For example, if you know you are going to work on some + code, you could first use the + <ulink url='&YOCTO_DOCS_DEV_URL;#devtool-modifying-a-recipe'><filename>devtool modify</filename></ulink> + command to extract the code and set up the workspace. + After which, you could modify, compile, and test the code. + </para> + + <para> + When you are satisfied with the results and you have committed + your changes to the Git repository, you can then + run the <filename>devtool update-recipe</filename> to create the + patches and update the recipe: + <literallayout class='monospaced'> + $ devtool update-recipe <replaceable>recipe</replaceable> + </literallayout> + If you run the <filename>devtool update-recipe</filename> + without committing your changes, the command ignores the + changes. + </para> + + <para> + Often, you might want to apply customizations made to your + software in your own layer rather than apply them to the + original recipe. + If so, you can use the + <filename>-a</filename> or <filename>--append</filename> + option with the <filename>devtool update-recipe</filename> + command. + These options allow you to specify the layer into which to + write an append file: + <literallayout class='monospaced'> + $ devtool update-recipe <replaceable>recipe</replaceable> -a <replaceable>base-layer-directory</replaceable> + </literallayout> + The <filename>*.bbappend</filename> file is created at the + appropriate path within the specified layer directory, which + may or may not be in your <filename>bblayers.conf</filename> + file. + If an append file already exists, the command updates it + appropriately. + </para> + </section> + + <section id='devtool-upgrading-a-recipe'> + <title>Upgrading a Recipe</title> + + <para> + Use the <filename>devtool upgrade</filename> command + to upgrade an existing recipe to a new upstream version. + The command puts the upgraded recipe file into the + workspace along with any associated files, and extracts + the source tree to a specified location should patches + need rebased or added to as a result of the upgrade. + </para> + + <para> + When you use the <filename>devtool upgrade</filename> command, + you must supply the root name of the recipe (i.e. no version, + paths, or extensions), and you must supply the directory + to which you want the source extracted. + Additional command options let you control things such as + the version number to which you want to upgrade (i.e. the + <link linkend='var-PV'><filename>PV</filename></link>), + the source revision to which you want to upgrade (i.e. the + <link linkend='var-SRCREV'><filename>SRCREV</filename></link>, + whether or not to apply patches, and so forth. + </para> + </section> + + <section id='devtool-resetting-a-recipe'> + <title>Resetting a Recipe</title> + + <para> + Use the <filename>devtool reset</filename> command to remove a + recipe and its configuration (e.g. the corresponding + <filename>.bbappend</filename> file) from the workspace layer. + Realize that this command deletes the recipe and the + append file. + The command does not physically move them for you. + Consequently, you must be sure to physically relocate your + updated recipe and the append file outside of the workspace + layer before running the <filename>devtool reset</filename> + command. + </para> + + <para> + If the <filename>devtool reset</filename> command detects that + the recipe or the append files have been modified, the + command preserves the modified files in a separate "attic" + subdirectory under the workspace layer. + </para> + + <para> + Here is an example that resets the workspace directory that + contains the <filename>mtr</filename> recipe: + <literallayout class='monospaced'> + $ devtool reset mtr + NOTE: Cleaning sysroot for recipe mtr... + NOTE: Leaving source tree /home/scottrif/poky/build/workspace/sources/mtr as-is; if you no + longer need it then please delete it manually + $ + </literallayout> + </para> + </section> + + <section id='devtool-building-your-recipe'> + <title>Building Your Recipe</title> + + <para> + Use the <filename>devtool build</filename> command to cause the + OpenEmbedded build system to build your recipe. + The <filename>devtool build</filename> command is equivalent to + <filename>bitbake -c populate_sysroot</filename>. + </para> + + <para> + When you use the <filename>devtool build</filename> command, + you must supply the root name of the recipe (i.e. no version, + paths, or extensions). + You can use either the "-s" or the "--disable-parallel-make" + option to disable parallel makes during the build. + Here is an example: + <literallayout class='monospaced'> + $ devtool build <replaceable>recipe</replaceable> + </literallayout> + </para> + </section> + + <section id='devtool-building-your-image'> + <title>Building Your Image</title> + + <para> + Use the <filename>devtool build-image</filename> command + to build an image, extending it to include packages from + recipes in the workspace. + Using this command is useful when you want an image that + ready for immediate deployment onto a device for testing. + For proper integration into a final image, you need to + edit your custom image recipe appropriately. + </para> + + <para> + When you use the <filename>devtool build-image</filename> + command, you must supply the name of the image. + This command has no command line options: + <literallayout class='monospaced'> + $ devtool build-image <replaceable>image</replaceable> + </literallayout> + </para> + </section> + + <section id='devtool-deploying-your-software-on-the-target-machine'> + <title>Deploying Your Software on the Target Machine</title> + + <para> + Use the <filename>devtool deploy-target</filename> command to + deploy the recipe's build output to the live target machine: + <literallayout class='monospaced'> + $ devtool deploy-target <replaceable>recipe</replaceable> <replaceable>target</replaceable> + </literallayout> + The <replaceable>target</replaceable> is the address of the + target machine, which must be running an SSH server (i.e. + <filename>user@hostname[:destdir]</filename>). + </para> + + <para> + This command deploys all files installed during the + <link linkend='ref-tasks-install'><filename>do_install</filename></link> + task. + Furthermore, you do not need to have package management enabled + within the target machine. + If you do, the package manager is bypassed. + <note><title>Notes</title> + <para> + The <filename>deploy-target</filename> + functionality is for development only. + You should never use it to update an image that will be + used in production. + </para> + </note> + </para> + </section> + + <section id='devtool-removing-your-software-from-the-target-machine'> + <title>Removing Your Software from the Target Machine</title> + + <para> + Use the <filename>devtool undeploy-target</filename> command to + remove deployed build output from the target machine. + For the <filename>devtool undeploy-target</filename> command to + work, you must have previously used the + <ulink url='&YOCTO_DOCS_DEV_URL;#devtool-deploying-your-software-on-the-target-machine'><filename>devtool deploy-target</filename></ulink> + command. + <literallayout class='monospaced'> + $ devtool undeploy-target <replaceable>recipe</replaceable> <replaceable>target</replaceable> + </literallayout> + The <replaceable>target</replaceable> is the address of the + target machine, which must be running an SSH server (i.e. + <filename>user@hostname</filename>). + </para> + </section> + + <section id='devtool-creating-the-workspace'> + <title>Creating the Workspace Layer in an Alternative Location</title> + + <para> + Use the <filename>devtool create-workspace</filename> command to + create a new workspace layer in your + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. + When you create a new workspace layer, it is populated with the + <filename>README</filename> file and the + <filename>conf</filename> directory only. + </para> + + <para> + The following example creates a new workspace layer in your + current working and by default names the workspace layer + "workspace": + <literallayout class='monospaced'> + $ devtool create-workspace + </literallayout> + </para> + + <para> + You can create a workspace layer anywhere by supplying + a pathname with the command. + The following command creates a new workspace layer named + "new-workspace": + <literallayout class='monospaced'> + $ devtool create-workspace /home/scottrif/new-workspace + </literallayout> + </para> + </section> + + <section id='devtool-get-the-status-of-the-recipes-in-your-workspace'> + <title>Get the Status of the Recipes in Your Workspace</title> + + <para> + Use the <filename>devtool status</filename> command to + list the recipes currently in your workspace. + Information includes the paths to their respective + external source trees. + </para> + + <para> + The <filename>devtool status</filename> command has no + command-line options: + <literallayout class='monospaced'> + $ devtool status + </literallayout> + Following is sample output after using + <ulink url='&YOCTO_DOCS_DEV_URL;#devtool-adding-a-new-recipe-to-the-workspace'><filename>devtool add</filename></ulink> + to create and add the <filename>mtr_0.86.bb</filename> recipe + to the <filename>workspace</filename> directory: + <literallayout class='monospaced'> + $ devtool status + mtr: /home/scottrif/poky/build/workspace/sources/mtr (/home/scottrif/poky/build/workspace/recipes/mtr/mtr_0.86.bb) + $ + </literallayout> + </para> + </section> + + <section id='devtool-search-for-available-target-recipes'> + <title>Search for Available Target Recipes</title> + + <para> + Use the <filename>devtool search</filename> command to + search for available target recipes. + The command matches the recipe name, package name, + description, and installed files. + The command displays the recipe name as a result of a + match. + </para> + + <para> + When you use the <filename>devtool search</filename> command, + you must supply a <replaceable>keyword</replaceable>. + The command uses the <replaceable>keyword</replaceable> when + searching for a match. + </para> + </section> +</chapter> +<!-- +vim: expandtab tw=80 ts=4 +--> 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 fd7693500..cd1bcb024 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/ref-features.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/ref-features.xml @@ -144,6 +144,27 @@ </para></listitem> <listitem><para><emphasis>bluetooth:</emphasis> Include bluetooth support (integrated BT only).</para></listitem> + <listitem><para><emphasis>bluez5:</emphasis> Include + BlueZ Version 5, which provides core Bluetooth layers and + protocols support. + <note> + The default value for the + <link linkend='var-DISTRO_FEATURES'><filename>DISTRO FEATURES</filename></link> + variable includes "bluetooth", which causes bluez5 + to be backfilled in for bluetooth support. + If you do not want bluez5 backfilled and would rather + use bluez4, you need to use the + <link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename></link> + variable as follows: + <literallayout class='monospaced'> + DISTRO_FEATURES_BACKFILL_CONSIDERED = "bluez5" + </literallayout> + Setting this variable tells the OpenEmbedded build + system that you have considered but ruled + out using the bluez5 feature and that bluez4 will be + used. + </note> + </para></listitem> <listitem><para><emphasis>cramfs:</emphasis> Include CramFS support.</para></listitem> <listitem><para><emphasis>directfb:</emphasis> 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 6834d5f0a..09f34fb52 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/ref-manual.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/ref-manual.xml @@ -102,6 +102,11 @@ <date>April 2016</date> <revremark>Released with the Yocto Project 2.1 Release.</revremark> </revision> + <revision> + <revnumber>2.2</revnumber> + <date>October 2016</date> + <revremark>Released with the Yocto Project 2.2 Release.</revremark> + </revision> </revhistory> <copyright> @@ -140,6 +145,8 @@ <xi:include href="ref-tasks.xml"/> + <xi:include href="ref-devtool-reference.xml"/> + <xi:include href="ref-qa-checks.xml"/> <xi:include href="ref-images.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 4fcf1db61..86456bd42 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 @@ -918,7 +918,8 @@ can be found then it should be implemented. I can't find one at the moment. and the upstream change log or release notes. Once you have worked out what the appropriate change is, you can update - <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link> + <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>, + <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link>, or the individual <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link> option values accordingly. @@ -1107,7 +1108,7 @@ can be found then it should be implemented. I can't find one at the moment. <listitem> <para id='qa-issue-installed-vs-shipped'> <code> - <recipename>: Files/directories were installed but not shipped [installed-vs-shipped] + <recipename>: Files/directories were installed but not shipped in any package [installed-vs-shipped] </code> </para> 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 e51ceb1bf..541a47e55 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/ref-structure.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/ref-structure.xml @@ -660,9 +660,21 @@ <title><filename>build/tmp/cache/</filename></title> <para> - When BitBake parses the metadata, it creates a cache file of the result that can - be used when subsequently running commands. - BitBake stores these results here on a per-machine basis. + When BitBake parses the metadata (recipes and configuration files), + it caches the results in <filename>build/tmp/cache/</filename> + to speed up future builds. + The results are stored on a per-machine basis. + </para> + + <para> + During subsequent builds, BitBake checks each recipe (together + with, for example, any files included or appended to it) to see + if they have been modified. + Changes can be detected, for example, through file modification + time (mtime) changes and hashing of file contents. + If no changes to the file are detected, then the parsed result + stored in the cache is reused. + If the file has changed, it is reparsed. </para> </section> @@ -801,8 +813,9 @@ <title><filename>build/tmp/stamps/</filename></title> <para> - This directory holds information that BitBake uses for accounting purposes - to track what tasks have run and when they have run. + This directory holds information that BitBake uses for + accounting purposes to track what tasks have run and when they + have run. The directory is sub-divided by architecture, package name, and version. Following is an example: @@ -812,6 +825,13 @@ Although the files in the directory are empty of data, BitBake uses the filenames and timestamps for tracking purposes. </para> + + <para> + For information on how BitBake uses stamp files to determine if + a task should be rerun, see the + "<link linkend='stamp-files-and-the-rerunning-of-tasks'>Stamp Files and the Rerunning of Tasks</link>" + section. + </para> </section> <section id='structure-build-tmp-log'> 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 c46debb55..e9859c1fa 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/ref-tasks.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/ref-tasks.xml @@ -19,6 +19,10 @@ <para> The following sections describe normal tasks associated with building a recipe. + For more information on tasks and dependencies, see the + "<ulink url='&YOCTO_DOCS_BB_URL;#tasks'>Tasks</ulink>" and + "<ulink url='&YOCTO_DOCS_BB_URL;#dependencies'>Dependencies</ulink>" + sections in the BitBake User Manual. </para> <section id='ref-tasks-build'> @@ -31,43 +35,23 @@ </para> </section> - <section id='ref-tasks-checkpkg'> - <title><filename>do_checkpkg</filename></title> - - <para> - Provides information about the recipe including its upstream - version and status. - The upstream version and status reveals whether or not a version - of the recipe exists upstream and a status of not updated, updated, - or unknown. - </para> + <section id='ref-tasks-compile'> + <title><filename>do_compile</filename></title> <para> - The <filename>checkpkg</filename> task is included as part of the - <link linkend='ref-classes-distrodata'><filename>distrodata</filename></link> - class. + Compiles the source code. + This task runs with the current working directory set + to + <filename>${</filename><link linkend='var-B'><filename>B</filename></link><filename>}</filename>. </para> <para> - To build the <filename>checkpkg</filename> task, use the - <filename>bitbake</filename> command with the "-c" option and - task name: - <literallayout class='monospaced'> - $ bitbake core-image-minimal -c checkpkg - </literallayout> - By default, the results are stored in - <link linkend='var-LOG_DIR'><filename>$LOG_DIR</filename></link> - (e.g. <filename>$BUILD_DIR/tmp/log</filename>). - </para> - </section> - - <section id='ref-tasks-compile'> - <title><filename>do_compile</filename></title> - - <para> - Compiles the source in the compilation directory, which is pointed - to by the - <link linkend='var-B'><filename>B</filename></link> variable. + The default behavior of this task is to run the + <filename>oe_runmake</filename> function if a makefile + (<filename>Makefile</filename>, <filename>makefile</filename>, + or <filename>GNUmakefile</filename>) is found. + If no such file is found, the <filename>do_compile</filename> + task does nothing. </para> </section> @@ -86,6 +70,20 @@ <para> Configures the source by enabling and disabling any build-time and configuration options for the software being built. + The task runs with the current working directory set to + <filename>${</filename><link linkend='var-B'><filename>B</filename></link><filename>}</filename>. + </para> + + <para> + The default behavior of this task is to run + <filename>oe_runmake clean</filename> if a makefile + (<filename>Makefile</filename>, <filename>makefile</filename>, + or <filename>GNUmakefile</filename>) is found and + <link linkend='var-CLEANBROKEN'><filename>CLEANBROKEN</filename></link> + is not set to "1". + If no such file is found or the <filename>CLEANBROKEN</filename> + variable is set to "1", the <filename>do_configure</filename> + task does nothing. </para> </section> @@ -102,18 +100,62 @@ <title><filename>do_deploy</filename></title> <para> - Writes output files that are to be deployed to the deploy - directory, which is defined by the - <link linkend='var-DEPLOYDIR'><filename>DEPLOYDIR</filename></link> - variable. + Writes output files that are to be deployed to + <filename>${</filename><link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link><filename>}</filename>. + The task runs with the current working directory set to + <filename>${</filename><link linkend='var-B'><filename>B</filename></link><filename>}</filename>. </para> <para> - The <filename>do_deploy</filename> task is a - shared state (sstate) task, which means that the task can - be accelerated through sstate use. - Realize also that if the task is re-executed, any previous output - is removed (i.e. "cleaned"). + Recipes implementing this task should inherit the + <link linkend='ref-classes-deploy'><filename>deploy</filename></link> + class and should write the output to + <filename>${</filename><link linkend='var-DEPLOYDIR'><filename>DEPLOYDIR</filename></link><filename>}</filename>, + which is not to be confused with + <filename>${</filename><link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link><filename>}</filename>. + The <filename>deploy</filename> class sets up + <filename>do_deploy</filename> as a shared state (sstate) task that + can be accelerated through sstate use. + The sstate mechanism takes care of copying the output from + <filename>${DEPLOYDIR}</filename> to + <filename>${DEPLOY_DIR_IMAGE}</filename>. + <note> + <title>Caution</title> + Do not write the output directly to + <filename>${DEPLOY_DIR_IMAGE}</filename>, as this causes + the sstate mechanism to malfunction. + </note> + </para> + + <para> + The <filename>do_deploy</filename> task is not added as a task + by default and consequently needs to be added manually. + If you want the task to run after + <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>, + you can add it by doing the following: + <literallayout class='monospaced'> + addtask deploy after do_compile + </literallayout> + Adding <filename>do_deploy</filename> after other tasks works the + same way. + <note> + You do not need to add <filename>before do_build</filename> + to the <filename>addtask</filename> command (though it is + harmless), because the + <link linkend='ref-classes-base'><filename>base</filename></link> + class contains the following: + <literallayout class='monospaced'> + do_build[recrdeptask] += "do_deploy" + </literallayout> + See the + "<ulink url='&YOCTO_DOCS_BB_URL;#dependencies'>Dependencies</ulink>" + section in the BitBake User Manual for more information. + </note> + </para> + + <para> + If the <filename>do_deploy</filename> task re-executes, any + previous output is removed (i.e. "cleaned"). </para> </section> @@ -213,11 +255,59 @@ <title><filename>do_install</filename></title> <para> - Copies files from the compilation directory, which is defined by - the - <link linkend='var-B'><filename>B</filename></link> variable, - to a holding area defined by the - <link linkend='var-D'><filename>D</filename></link> variable. + Copies files that are to be packaged into the holding area + <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename>. + This task runs with the current working directory set to + <filename>${</filename><link linkend='var-B'><filename>B</filename></link><filename>}</filename>, + which is the compilation directory. + The <filename>do_install</filename> task, as well as other tasks + that either directly or indirectly depend on the installed files + (e.g. + <link linkend='ref-tasks-package'><filename>do_package</filename></link>, + <link linkend='ref-tasks-package_write_deb'><filename>do_package_write_*</filename></link>, + and + <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>), + run under + <link linkend='fakeroot-and-pseudo'>fakeroot</link>. + <note> + <title>Caution</title> + + <para> + When installing files, be careful not to set the owner and + group IDs of the installed files to unintended values. + Some methods of copying files, notably when using the + recursive <filename>cp</filename> command, can preserve the + UID and/or GID of the original file, which is usually not + what you want. + The + <link linkend='ref-classes-insane'><filename>host-user-contaminated</filename></link> + QA check checks for files that probably have the wrong + ownership. + </para> + + <para> + Safe methods for installing files include the following: + <itemizedlist> + <listitem><para> + The <filename>install</filename> utility. + This utility is the preferred method. + </para></listitem> + <listitem><para> + The <filename>cp</filename> command with the + "--no-preserve=ownership" option. + </para></listitem> + <listitem><para> + The <filename>tar</filename> command with the + "--no-same-owner" option. + See the <filename>bin_package.bbclass</filename> + file in the <filename>meta/classes</filename> + directory of the + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> + for an example. + </para></listitem> + </itemizedlist> + </para> + </note> </para> </section> @@ -234,8 +324,26 @@ <title><filename>do_package</filename></title> <para> - Analyzes the content of the holding area and splits it into subsets - based on available packages and files. + Analyzes the content of the holding area + <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename> + and splits the content into subsets based on available packages + and files. + This task makes use of the + <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link> + and + <link linkend='var-FILES'><filename>FILES</filename></link> + variables. + </para> + + <para> + The <filename>do_package</filename> task, in conjunction with the + <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link> + task, also saves some important package metadata. + For additional information, see the + <link linkend='var-PKGDESTWORK'><filename>PKGDESTWORK</filename></link> + variable and the + "<link linkend='automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</link>" + section. </para> </section> @@ -309,8 +417,11 @@ <title><filename>do_packagedata</filename></title> <para> - Creates package metadata used by the build system to generate the - final packages. + Saves package metadata generated by the + <link linkend='ref-tasks-package'><filename>do_package</filename></link> + task in + <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link> + to make it available globally. </para> </section> @@ -349,16 +460,25 @@ <title><filename>do_populate_sysroot</filename></title> <para> - Copies a subset of the files installed by the + Stages (copies) a subset of the files installed by the <link linkend='ref-tasks-install'><filename>do_install</filename></link> - task into the sysroot to make them available to other recipes. - Files that would typically not be needed by other recipes at build - time are skipped. - Skipped files include files installed into - <filename>/etc.</filename> - For information on what files are copied, see the - <link linkend='ref-classes-staging'><filename>staging</filename></link> - class. + task into the appropriate sysroot. + For information on how to access these files from other recipes, + see the + <link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR*</filename></link> + variables. + Directories that would typically not be needed by other recipes at + build time (e.g. <filename>/etc</filename>) are not copied by + default. + </para> + + <para> + For information on what directories are copied by default, see the + <link linkend='var-SYSROOT_DIRS'><filename>SYSROOT_DIRS*</filename></link> + variables. + You can change these variables inside your recipe if you need + to make additional (or fewer) directories available to other + recipes at build time. </para> <para> @@ -417,6 +537,36 @@ <filename>bitbake -c</filename> command-line option): </para> + <section id='ref-tasks-checkpkg'> + <title><filename>do_checkpkg</filename></title> + + <para> + Provides information about the recipe including its upstream + version and status. + The upstream version and status reveals whether or not a version + of the recipe exists upstream and a status of not updated, updated, + or unknown. + </para> + + <para> + The <filename>checkpkg</filename> task is included as part of the + <link linkend='ref-classes-distrodata'><filename>distrodata</filename></link> + class. + </para> + + <para> + To build the <filename>checkpkg</filename> task, use the + <filename>bitbake</filename> command with the "-c" option and + task name: + <literallayout class='monospaced'> + $ bitbake core-image-minimal -c checkpkg + </literallayout> + By default, the results are stored in + <link linkend='var-LOG_DIR'><filename>$LOG_DIR</filename></link> + (e.g. <filename>$BUILD_DIR/tmp/log</filename>). + </para> + </section> + <section id='ref-tasks-checkuri'> <title><filename>do_checkuri</filename></title> @@ -541,6 +691,22 @@ </para> </section> + <section id='ref-tasks-devpyshell'> + <title><filename>do_devpyshell</filename></title> + + <para> + Starts a shell in which an interactive Python interpreter allows + you to interact with the BitBake build environment. + From within this shell, you can directly examine and set + bits from the data store and execute functions as if within + the BitBake environment. + See the + "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devpyshell'>Using a Development Python Shell</ulink>" + section in the Yocto Project Development Manual for more + information about using <filename>devpyshell</filename>. + </para> + </section> + <section id='ref-tasks-devshell'> <title><filename>do_devshell</filename></title> 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 d55bccdc6..ce331d85b 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/ref-variables.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/ref-variables.xml @@ -536,7 +536,7 @@ By default, this directory is the same as the <link linkend='var-S'><filename>S</filename></link> directory, which is defined as: <literallayout class='monospaced'> - S = "${WORKDIR}/${BP}/" + S = "${WORKDIR}/${BP}" </literallayout> </para> @@ -995,6 +995,29 @@ BBCLASSEXTEND =+ "native nativesdk" BBCLASSEXTEND =+ "multilib:<replaceable>multilib_name</replaceable>" </literallayout> + <note> + <para> + Internally, the <filename>BBCLASSEXTEND</filename> + mechanism generates recipe variants by rewriting + variable values and applying overrides such as + <filename>_class-native</filename>. + For example, to generate a native version of a recipe, + a + <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link> + on "foo" is rewritten to a <filename>DEPENDS</filename> + on "foo-native". + </para> + + <para> + Even when using <filename>BBCLASSEXTEND</filename>, the + recipe is only parsed once. + Parsing once adds some limitations. + For example, it is not possible to + include a different file depending on the variant, + since <filename>include</filename> statements are + processed when the recipe is parsed. + </para> + </note> </para> </glossdef> </glossentry> @@ -1202,6 +1225,42 @@ </glossdef> </glossentry> + <glossentry id='var-BBMULTICONFIG'><glossterm>BBMULTICONFIG</glossterm> + <info> + BBMULTICONFIG[doc] = "Specifies each separate configuration when you are building targets with multiple configurations." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Specifies each separate configuration when you are + building targets with multiple configurations. + Use this variable in your + <filename>conf/local.conf</filename> configuration file. + Specify a <replaceable>multiconfigname</replaceable> for + each configuration file you are using. + For example, the following line specifies three + configuration files: + <literallayout class='monospaced'> + BBMULTIFONFIG = "configA configB configC" + </literallayout> + Each configuration file you use must reside in the + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory's</ulink> + <filename>conf/multiconfig</filename> directory + (e.g. + <replaceable>build_directory</replaceable><filename>/conf/multiconfig/configA.conf</filename>). + </para> + + <para> + For information on how to use + <filename>BBMULTICONFIG</filename> in an environment that + supports building targets with multiple configurations, + see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-building-targets-with-multiple-configurations'>Building Targets with Multiple Configurations</ulink>" + section in the Yocto Project Development Manual. + </para> + </glossdef> + </glossentry> + <glossentry id='var-BBPATH'><glossterm>BBPATH</glossterm> <info> BBPATH[doc] = "Used by BitBake to locate .bbclass and configuration files. This variable is analogous to the PATH variable." @@ -1336,28 +1395,25 @@ <glossentry id='var-BPN'><glossterm>BPN</glossterm> <info> - BPN[doc] = "The bare name of the recipe. This variable is a version of the PN variable but removes common suffixes and prefixes." + BPN[doc] = "This variable is a version of the PN variable but removes common suffixes and prefixes." </info> <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - The bare name of the recipe. This variable is a version of the <link linkend='var-PN'><filename>PN</filename></link> - variable but removes common suffixes such as - <filename>-native</filename> and - <filename>-cross</filename> as well - as removes common prefixes such as multilib's + variable with common prefixes and suffixes + removed, such as <filename>nativesdk-</filename>, + <filename>-cross</filename>, + <filename>-native</filename>, and multilib's <filename>lib64-</filename> and <filename>lib32-</filename>. - The exact list of suffixes removed is specified by the - <link linkend='var-SPECIAL_PKGSUFFIX'><filename>SPECIAL_PKGSUFFIX</filename></link> - variable. - The exact list of prefixes removed is specified by the + The exact lists of prefixes and suffixes removed are + specified by the <link linkend='var-MLPREFIX'><filename>MLPREFIX</filename></link> - variable. - Prefixes are removed for <filename>multilib</filename> - and <filename>nativesdk-</filename> cases. + and + <link linkend='var-SPECIAL_PKGSUFFIX'><filename>SPECIAL_PKGSUFFIX</filename></link> + variables, respectively. </para> </glossdef> </glossentry> @@ -1972,22 +2028,36 @@ An internal variable specifying the special class override that should currently apply (e.g. "class-target", "class-native", and so forth). - The classes that use this variable set it to - appropriate values. + The classes that use this variable (e.g. + <link linkend='ref-classes-native'><filename>native</filename></link>, + <link linkend='ref-classes-nativesdk'><filename>nativesdk</filename></link>, + and so forth) set the variable to appropriate values. + <note> + <filename>CLASSOVERRIDE</filename> gets its default + "class-target" value from the + <filename>bitbake.conf</filename> file. + </note> </para> <para> - You do not normally directly interact with this variable. - The value for the <filename>CLASSOVERRIDE</filename> - variable goes into - <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link> - and then can be used as an override. - Here is an example where "python-native" is added to - <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link> - only when building for the <filename>-native</filename> case: + As an example, the following override allows you to install + extra files, but only when building for the target: + <literallayout class='monospaced'> + do_install_append_class-target() { + install my-extra-file ${D}${sysconfdir} + } + </literallayout> + Here is an example where <filename>FOO</filename> + is set to "native" when building for the build host, and + to "other" when not building for the build host: <literallayout class='monospaced'> - DEPENDS_append_class-native = " python-native" + FOO_class-native = "native" + FOO = "other" </literallayout> + The underlying mechanism behind + <filename>CLASSOVERRIDE</filename> is simply that it is + included in the default value of + <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>. </para> </glossdef> </glossentry> @@ -2574,8 +2644,13 @@ task. This location defaults to: <literallayout class='monospaced'> - ${WORKDIR}/image + ${<link linkend='var-WORKDIR'>WORKDIR</link>}/image </literallayout> + <note><title>Caution</title> + Tasks that read from or write to this directory should + run under + <link linkend='fakeroot-and-pseudo'>fakeroot</link>. + </note> </para> </glossdef> </glossentry> @@ -2748,34 +2823,117 @@ <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - Lists a recipe's build-time dependencies - (i.e. other recipe files). - The system ensures that all the dependencies listed - have been built and have their contents in the appropriate - sysroots before the recipe's configure task is executed. + Lists a recipe's build-time dependencies. + These are dependencies on other recipes whose + contents (e.g. headers and shared libraries) are needed + by the recipe at build time. </para> <para> - Consider this simple example for two recipes named "a" and - "b" that produce similarly named packages. - In this example, the <filename>DEPENDS</filename> - statement appears in the "a" recipe: + As an example, consider a recipe <filename>foo</filename> + that contains the following assignment: <literallayout class='monospaced'> - DEPENDS = "b" + DEPENDS = "bar" </literallayout> - Here, the dependency is such that the + The practical effect of the previous assignment is that + all files installed by bar will be available in the + appropriate staging sysroot, given by the + <link linkend='var-STAGING_DIR'><filename>STAGING_DIR*</filename></link> + variables, by the time the <link linkend='ref-tasks-configure'><filename>do_configure</filename></link> - task for recipe "a" depends on the + task for <filename>foo</filename> runs. + This mechanism is implemented by having + <filename>do_configure</filename> depend on the <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link> - task of recipe "b". - This means anything that recipe "b" puts into sysroot - is available when recipe "a" is configuring itself. + task of each recipe listed in <filename>DEPENDS</filename>, + through a + <filename>[</filename><ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>deptask</filename></ulink><filename>]</filename> + declaration in the + <link linkend='ref-classes-base'><filename>base</filename></link> + class. + <note> + It seldom is necessary to reference, for example, + <filename>STAGING_DIR_HOST</filename> explicitly. + The standard classes and build-related variables are + configured to automatically use the appropriate staging + sysroots. + </note> + As another example, <filename>DEPENDS</filename> can also + be used to add utilities that run on the build machine + during the build. + For example, a recipe that makes use of a code generator + built by the recipe <filename>codegen</filename> might have + the following: + <literallayout class='monospaced'> + DEPENDS = "codegen-native" + </literallayout> + For more information, see the + <link linkend='ref-classes-native'><filename>native</filename></link> + class and the + <link linkend='var-EXTRANATIVEPATH'><filename>EXTRANATIVEPATH</filename></link> + variable. + <note> + <title>Notes</title> + <itemizedlist> + <listitem><para> + <filename>DEPENDS</filename> is a list of + recipe names. + Or, to be more precise, it is a list of + <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link> + names, which usually match recipe names. + Putting a package name such as "foo-dev" in + <filename>DEPENDS</filename> does not make + sense. + Use "foo" instead, as this will put files + from all the packages that make up + <filename>foo</filename>, which includes + those from <filename>foo-dev</filename>, into + the sysroot. + </para></listitem> + <listitem><para> + One recipe having another recipe in + <filename>DEPENDS</filename> does not by itself + add any runtime dependencies between the + packages produced by the two recipes. + However, as explained in the + "<link linkend='automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</link>" + section, runtime dependencies will often be + added automatically, meaning + <filename>DEPENDS</filename> alone is + sufficient for most recipes. + </para></listitem> + <listitem><para> + Counterintuitively, + <filename>DEPENDS</filename> is often necessary + even for recipes that install precompiled + components. + For example, if <filename>libfoo</filename> + is a precompiled library that links against + <filename>libbar</filename>, then + linking against <filename>libfoo</filename> + requires both <filename>libfoo</filename> + and <filename>libbar</filename> to be available + in the sysroot. + Without a <filename>DEPENDS</filename> from the + recipe that installs <filename>libfoo</filename> + to the recipe that installs + <filename>libbar</filename>, other recipes might + fail to link against + <filename>libfoo</filename>. + </para></listitem> + </itemizedlist> + </note> </para> <para> For information on runtime dependencies, see the <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> variable. + You can also see the + "<ulink url='&YOCTO_DOCS_BB_URL;#tasks'>Tasks</ulink>" and + "<ulink url='&YOCTO_DOCS_BB_URL;#dependencies'>Dependencies</ulink>" + sections in the BitBake User Manual for additional + information on tasks and dependencies. </para> </glossdef> </glossentry> @@ -3072,15 +3230,15 @@ by UUID to allow the kernel to locate the root device even if the device name changes due to differences in hardware configuration. - By default, <filename>SYSLINUX_ROOT</filename> is set + By default, <filename>ROOT_VM</filename> is set as follows: <literallayout class='monospaced'> - SYSLINUX_ROOT = "root=/dev/sda2" + ROOT_VM ?= "root=/dev/sda2" </literallayout> However, you can change this to locate the root device using the disk signature instead: <literallayout class='monospaced'> - SYSLINUX_ROOT = "root=PARTUUID=${DISK_SIGNATURE}-02" + ROOT_VM = "root=PARTUUID=${DISK_SIGNATURE}-02" </literallayout> </para> @@ -3341,20 +3499,28 @@ <glossentry id='var-DISTROOVERRIDES'><glossterm>DISTROOVERRIDES</glossterm> <info> - DISTROOVERRIDES[doc] = "Lists overrides specific to the current distribution. By default, the variable list includes the value of the DISTRO variable." + DISTROOVERRIDES[doc] = "A colon-separated list of overrides specific to the current distribution." </info> <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - This variable lists overrides specific to the current - distribution. - By default, the variable list includes the value of the - <filename><link linkend='var-DISTRO'>DISTRO</link></filename> - variable. - You can extend the variable to apply any variable overrides - you want as part of the distribution and are not - already in <filename>OVERRIDES</filename> through - some other means. + A colon-separated list of overrides specific to the + current distribution. + By default, this list includes the value of + <link linkend='var-DISTRO'><filename>DISTRO</filename></link>. + </para> + + <para> + You can extend <filename>DISTROOVERRIDES</filename> + to add extra overrides that should apply to + the distribution. + </para> + + <para> + The underlying mechanism behind + <filename>DISTROOVERRIDES</filename> is simply that it + is included in the default value of + <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>. </para> </glossdef> </glossentry> @@ -3463,13 +3629,13 @@ <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>), the <filename>EFI_PROVIDER</filename> variable specifies the EFI bootloader to use. - The default is "grub-efi", but "gummiboot" can be used + The default is "grub-efi", but "systemd-boot" can be used instead. </para> <para> See the - <link linkend='ref-classes-gummiboot'><filename>gummiboot</filename></link> + <link linkend='ref-classes-systemd-boot'><filename>systemd-boot</filename></link> class for more information. </para> </glossdef> @@ -3893,6 +4059,27 @@ </glossdef> </glossentry> + <glossentry id='var-EXTRANATIVEPATH'><glossterm>EXTRANATIVEPATH</glossterm> + <info> + EXTRANATIVEPATH[doc] = "A list of subdirectories of ${STAGING_BINDIR_NATIVE} added to the beginning of the environment variable PATH." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + A list of subdirectories of + <filename>${</filename><link linkend='var-STAGING_BINDIR_NATIVE'><filename>STAGING_BINDIR_NATIVE</filename></link><filename>}</filename> + added to the beginning of the environment variable + <filename>PATH</filename>. + As an example, the following prepends + "${STAGING_BINDIR_NATIVE}/foo:${STAGING_BINDIR_NATIVE}/bar:" + to <filename>PATH</filename>: + <literallayout class='monospaced'> + EXTRANATIVEPATH = "foo bar" + </literallayout> + </para> + </glossdef> + </glossentry> + <glossentry id='var-EXTRA_OECMAKE'><glossterm>EXTRA_OECMAKE</glossterm> <info> EXTRA_OECMAKE[doc] = "Additional cmake options." @@ -3913,6 +4100,10 @@ <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Additional <filename>configure</filename> script options. + See + <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link> + for additional information on passing configure script + options. </para> </glossdef> </glossentry> @@ -3932,6 +4123,15 @@ "", you need to set the variable to specify any required GNU options. </para> + + <para> + <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link> + and + <link linkend='var-PARALLEL_MAKEINST'><filename>PARALLEL_MAKEINST</filename></link> + also make use of + <filename>EXTRA_OEMAKE</filename> to pass the required + flags. + </para> </glossdef> </glossentry> @@ -4061,12 +4261,16 @@ <glossentry id='var-FILES'><glossterm>FILES</glossterm> <info> - FILES[doc] = "The list of directories or files that are placed in packages." + FILES[doc] = "The list of directories or files that are placed in a package." </info> <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - The list of directories or files that are placed in packages. + The list of files and directories that are placed in a + package. + The + <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link> + variable lists the packages generated by a recipe. </para> <para> @@ -4077,7 +4281,7 @@ resulting package. Here is an example: <literallayout class='monospaced'> - FILES_${PN} += "${bindir}/mydir1/ ${bindir}/mydir2/myfile" + FILES_${PN} += "${bindir}/mydir1 ${bindir}/mydir2/myfile" </literallayout> </para> @@ -4092,6 +4296,8 @@ You can find a list of these variables at the top of the <filename>meta/conf/bitbake.conf</filename> file in the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. + You will also find the default values of the various + <filename>FILES_*</filename> variables in this file. </note> <para> @@ -4106,7 +4312,6 @@ variable for information on how to identify these files to the PMS. </para> - </glossdef> </glossentry> @@ -4361,6 +4566,25 @@ </glossdef> </glossentry> + <glossentry id='var-FORCE_RO_REMOVE'><glossterm>FORCE_RO_REMOVE</glossterm> + <info> + FORCE_RO_REMOVE[doc] = "Forces the removal of the packages listed in ROOTFS_RO_UNNEEDED during the generation of the root filesystem." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Forces the removal of the packages listed in + <filename>ROOTFS_RO_UNNEEDED</filename> during the + generation of the root filesystem. + </para> + + <para> + Set the variable to "1" to force the removal of these + packages. + </para> + </glossdef> + </glossentry> + <glossentry id='var-FULL_OPTIMIZATION'><glossterm>FULL_OPTIMIZATION</glossterm> <info> FULL_OPTIMIZATION[doc]= "The options to pass in TARGET_CFLAGS and CFLAGS when compiling an optimized system. This variable defaults to '-fexpensive-optimizations -fomit-frame-pointer -frename-registers -O2'." @@ -4570,92 +4794,6 @@ </glossdef> </glossentry> - <glossentry id='var-GUMMIBOOT_CFG'><glossterm>GUMMIBOOT_CFG</glossterm> - <info> - GUMMIBOOT_CFG[doc] = "When EFI_PROVIDER is set to "gummiboot", the GUMMIBOOT_CFG variable specifies the configuration file that should be used." - </info> - <glossdef> - <para role="glossdeffirst"> -<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - When - <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link> - is set to "gummiboot", the - <filename>GUMMIBOOT_CFG</filename> variable specifies the - configuration file that should be used. - By default, the - <link linkend='ref-classes-gummiboot'><filename>gummiboot</filename></link> - class sets the <filename>GUMMIBOOT_CFG</filename> as - follows: - <literallayout class='monospaced'> - GUMMIBOOT_CFG ?= "${<link linkend='var-S'>S</link>}/loader.conf" - </literallayout> - </para> - - <para> - For information on Gummiboot, see the - <ulink url='http://freedesktop.org/wiki/Software/gummiboot/'>Gummiboot documentation</ulink>. - </para> - </glossdef> - </glossentry> - - <glossentry id='var-GUMMIBOOT_ENTRIES'><glossterm>GUMMIBOOT_ENTRIES</glossterm> - <info> - GUMMIBOOT_ENTRIES[doc] = "When EFI_PROVIDER is set to "gummiboot", the GUMMIBOOT_ENTRIES variable specifies a list of entry files (*.conf) to be installed containing one boot entry per file." - </info> - <glossdef> - <para role="glossdeffirst"> -<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - When - <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link> - is set to "gummiboot", the - <filename>GUMMIBOOT_ENTRIES</filename> variable specifies - a list of entry files - (<filename>*.conf</filename>) to be installed - containing one boot entry per file. - By default, the - <link linkend='ref-classes-gummiboot'><filename>gummiboot</filename></link> - class sets the <filename>GUMMIBOOT_ENTRIES</filename> as - follows: - <literallayout class='monospaced'> - GUMMIBOOT_ENTRIES ?= "" - </literallayout> - </para> - - <para> - For information on Gummiboot, see the - <ulink url='http://freedesktop.org/wiki/Software/gummiboot/'>Gummiboot documentation</ulink>. - </para> - </glossdef> - </glossentry> - - <glossentry id='var-GUMMIBOOT_TIMEOUT'><glossterm>GUMMIBOOT_TIMEOUT</glossterm> - <info> - GUMMIBOOT_TIMEOUT[doc] = "When EFI_PROVIDER is set to "gummiboot", the GUMMIBOOT_TIMEOUT variable specifies the boot menu timeout in seconds." - </info> - <glossdef> - <para role="glossdeffirst"> -<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - When - <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link> - is set to "gummiboot", the - <filename>GUMMIBOOT_TIMEOUT</filename> variable specifies - the boot menu timeout in seconds. - By default, the - <link linkend='ref-classes-gummiboot'><filename>gummiboot</filename></link> - class sets the <filename>GUMMIBOOT_TIMEOUT</filename> as - follows: - <literallayout class='monospaced'> - GUMMIBOOT_TIMEOUT ?= "10" - </literallayout> - </para> - - <para> - For information on Gummiboot, see the - <ulink url='http://freedesktop.org/wiki/Software/gummiboot/'>Gummiboot documentation</ulink>. - </para> - </glossdef> - </glossentry> - </glossdiv> <glossdiv id='var-glossary-h'><title>H</title> @@ -5940,7 +6078,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossentry id='var-INHIBIT_PACKAGE_DEBUG_SPLIT'><glossterm>INHIBIT_PACKAGE_DEBUG_SPLIT</glossterm> <info> - INHIBIT_PACKAGE_STRIP[doc] = "If set to "1", causes the build to not strip binaries in resulting packages." + INHIBIT_PACKAGE_DEBUG_SPLIT[doc] = "If set to "1", prevents the OpenEmbedded build system from splitting out debug information during packaging" </info> <glossdef> <para role="glossdeffirst"> @@ -5976,7 +6114,19 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - If set to "1", causes the build to not strip binaries in resulting packages. + If set to "1", causes the build to not strip binaries in + resulting packages and prevents the + <filename>-dbg</filename> package from containing the + source files. + </para> + + <para> + By default, the OpenEmbedded build system strips + binaries and puts the debugging symbols into + <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}-dbg</filename>. + Consequently, you should not set + <filename>INHIBIT_PACKAGE_STRIP</filename> when you plan + to debug in general. </para> </glossdef> </glossentry> @@ -5994,72 +6144,108 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link> variable. </para> + + <para> + The default value of this variable, which is set in the + <filename>meta/conf/bitbake.conf</filename> configuration + file in the + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>, + is "cpio.gz". + The Linux kernel's initramfs mechanism, as opposed to the + initial RAM disk + <ulink url='https://en.wikipedia.org/wiki/Initrd'>initrd</ulink> + mechanism, expects an optionally compressed cpio + archive. + </para> </glossdef> </glossentry> <glossentry id='var-INITRAMFS_IMAGE'><glossterm>INITRAMFS_IMAGE</glossterm> <info> - INITRAMFS_IMAGE[doc] = "Causes the OpenEmbedded build system to build an additional recipe as a dependency to your root filesystem recipe (e.g. core-image-sato)." + INITRAMFS_IMAGE[doc] = "Specifies the PROVIDES name of an image recipe that is used to build an initial RAM disk (initramfs) image." </info> <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - Causes the OpenEmbedded build system to build an additional - recipe as a dependency to your root filesystem recipe - (e.g. <filename>core-image-sato</filename>). - The additional recipe is used to create an initial RAM disk - (initramfs) that might be needed during the initial boot of - the target system to accomplish such things as loading - kernel modules prior to mounting the root file system. + Specifies the + <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link> + name of an image recipe that is used to build an initial + RAM disk (initramfs) image. + An initramfs provides a temporary root filesystem used for + early system initialization (e.g. loading of modules + needed to locate and mount the "real" root filesystem). + The specified recipe is added as a dependency of the root + filesystem recipe (e.g. + <filename>core-image-sato</filename>). + See the <filename>meta/recipes-core/images/core-image-minimal-initramfs.bb</filename> + recipe in the + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> + for an example initramfs recipe. + To select this recipe to provide the initramfs, + set <filename>INITRAMFS_IMAGE</filename> to + "core-image-minimal-initramfs". + <note> + The initramfs image recipe should set + <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link> + to + <link linkend='var-INITRAMFS_FSTYPES'><filename>INITRAMFS_FSTYPES</filename></link>. + </note> </para> <para> - When you set the variable, specify the name of the - initramfs you want created. - The following example, which is set in the - <filename>local.conf</filename> configuration file, causes - a separate recipe to be created that results in an - initramfs image named - <filename>core-image-sato-initramfs.bb</filename> to be - created: - <literallayout class='monospaced'> - INITRAMFS_IMAGE = "core-image-minimal-initramfs" - </literallayout> - By default, the + You can also find more information by referencing the + <filename>meta/poky/conf/local.conf.sample.extended</filename> + configuration file in the + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>, + the + <link linkend='ref-classes-image'><filename>image</filename></link> + class, and the <link linkend='ref-classes-kernel'><filename>kernel</filename></link> - class sets this variable to a null string as follows: - <literallayout class='monospaced'> - INITRAMFS_IMAGE = "" - </literallayout> + class to see how to use the + <filename>INITRAMFS_IMAGE</filename> variable. </para> <para> - See the - <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-poky/conf/local.conf.sample.extended'><filename>local.conf.sample.extended</filename></ulink> - file for additional information. - You can also reference the - <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/classes/kernel.bbclass'><filename>kernel.bbclass</filename></ulink> - file to see how the variable is used. + If <filename>INITRAMFS_IMAGE</filename> is empty, which is + the default, then no initramfs is built. + </para> + + <para> + Finally, for more information you can also see the + <link linkend='var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></link> + variable, which allows the generated image to be bundled + inside the kernel image. </para> </glossdef> </glossentry> <glossentry id='var-INITRAMFS_IMAGE_BUNDLE'><glossterm>INITRAMFS_IMAGE_BUNDLE</glossterm> <info> - INITRAMFS_IMAGE_BUNDLE[doc] = "Controls whether or not the image recipe specified by INITRAMFS_IMAGE is run through an extra pass during kernel compilation in order to build a single binary that contains both the kernel image and the initial RAM disk (initramfs)." + INITRAMFS_IMAGE_BUNDLE[doc] = "Controls whether or not the image recipe specified by INITRAMFS_IMAGE is run through an extra pass (do_bundle_initramfs) during kernel compilation in order to build a single binary that contains both the kernel image and the initial RAM disk (initramfs)." </info> <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Controls whether or not the image recipe specified by <link linkend='var-INITRAMFS_IMAGE'><filename>INITRAMFS_IMAGE</filename></link> - is run through an extra pass during kernel compilation - in order to build a single binary that contains both the - kernel image and the initial RAM disk (initramfs). - Using an extra compilation pass ensures that when a kernel - attempts to use an initramfs, it does not encounter - circular dependencies should the initramfs include kernel - modules. + is run through an extra pass + (<link linkend='ref-tasks-bundle_initramfs'><filename>do_bundle_initramfs</filename></link>) + during kernel compilation in order to build a single binary + that contains both the kernel image and the initial RAM disk + (initramfs). + This makes use of the + <link linkend='var-CONFIG_INITRAMFS_SOURCE'><filename>CONFIG_INITRAMFS_SOURCE</filename></link> + kernel feature. + <note> + Using an extra compilation pass to bundle the initramfs + avoids a circular dependency between the kernel recipe and + the initramfs recipe should the initramfs include kernel + modules. + Should that be the case, the initramfs recipe depends on + the kernel for the kernel modules, and the kernel depends + on the initramfs recipe since the initramfs is bundled + inside the kernel image. + </note> </para> <para> @@ -6070,9 +6256,11 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </para> <para> - Setting the variable to "1" in a configuration file causes - the OpenEmbedded build system to make the extra pass during - kernel compilation: + Setting the variable to "1" in a configuration file causes the + OpenEmbedded build system to generate a kernel image with the + initramfs specified in + <link linkend='var-INITRAMFS_IMAGE'><filename>INITRAMFS_IMAGE</filename></link> + bundled within: <literallayout class='monospaced'> INITRAMFS_IMAGE_BUNDLE = "1" </literallayout> @@ -6080,7 +6268,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <link linkend='ref-classes-kernel'><filename>kernel</filename></link> class sets this variable to a null string as follows: <literallayout class='monospaced'> - INITRAMFS_IMAGE_BUNDLE = "" + INITRAMFS_IMAGE_BUNDLE ?= "" </literallayout> <note> You must set the @@ -7727,36 +7915,41 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossentry id='var-MACHINEOVERRIDES'><glossterm>MACHINEOVERRIDES</glossterm> <info> - MACHINEOVERRIDES[doc] = "Lists overrides specific to the current machine. By default, this list includes the value of MACHINE." + MACHINEOVERRIDES[doc] = "A colon-separated list of overrides that apply to the current machine." </info> <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - Lists overrides specific to the current machine. - By default, this list includes the value - of <filename><link linkend='var-MACHINE'>MACHINE</link></filename>. - You can extend the list to apply variable overrides for - classes of machines. - For example, all QEMU emulated machines (e.g. qemuarm, - qemux86, and so forth) include a common file named - <filename>meta/conf/machine/include/qemu.inc</filename> - that prepends <filename>MACHINEOVERRIDES</filename> with - the following variable override: - <literallayout class='monospaced'> - MACHINEOVERRIDES =. "qemuall:" - </literallayout> + A colon-separated list of overrides that apply to the + current machine. + By default, this list includes the value of + <link linkend='var-MACHINE'><filename>MACHINE</filename></link>. </para> <para> - Applying an override like <filename>qemuall</filename> - affects all QEMU emulated machines elsewhere. - Here is an example from the - <filename>connman-conf</filename> recipe: + You can extend <filename>MACHINEOVERRIDES</filename> + to add extra overrides that should apply to a machine. + For example, all machines emulated in QEMU (e.g. + <filename>qemuarm</filename>, <filename>qemux86</filename>, + and so forth) include a file named + <filename>meta/conf/machine/include/qemu.inc</filename> + that prepends the following override to + <filename>MACHINEOVERRIDES</filename>: + <literallayout class='monospaced'> + MACHINEOVERRIDES =. "qemuall:" + </literallayout> + This override allows variables to be overriden for all + machines emulated in QEMU, like in the following example + from the <filename>connman-conf</filename> recipe: <literallayout class='monospaced'> - SRC_URI_append_qemuall = "file://wired.config \ - file://wired-setup \ - " + SRC_URI_append_qemuall = "file://wired.config \ + file://wired-setup \ + " </literallayout> + The underlying mechanism behind + <filename>MACHINEOVERRIDES</filename> is simply that it is + included in the default value of + <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>. </para> </glossdef> </glossentry> @@ -7817,6 +8010,39 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <link linkend='var-BPN'><filename>BPN</filename></link> variable). <filename>MLPREFIX</filename> gets set when a prefix has been added to <filename>PN</filename>. + <note> + The "ML" in <filename>MLPREFIX</filename> stands for + "MultiLib". + This representation is historical and comes from + a time when <filename>nativesdk</filename> was a suffix + rather than a prefix on the recipe name. + When <filename>nativesdk</filename> was turned into a + prefix, it made sense to set + <filename>MLPREFIX</filename> for it as well. + </note> + </para> + + <para> + To help understand when <filename>MLPREFIX</filename> + might be needed, consider when + <link linkend='var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link> + is used to provide a <filename>nativesdk</filename> version + of a recipe in addition to the target version. + If that recipe declares build-time dependencies on tasks in + other recipes by using + <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>, + then a dependency on "foo" will automatically get rewritten + to a dependency on "nativesdk-foo". + However, dependencies like the following will not get + rewritten automatically: + <literallayout class='monospaced'> + do_foo[depends] += "<replaceable>recipe</replaceable>:do_foo" + </literallayout> + If you want such a dependency to also get transformed, + you can do the following: + <literallayout class='monospaced'> + do_foo[depends] += "${MLPREFIX}<replaceable>recipe</replaceable>:do_foo" + </literallayout> </para> </glossdef> </glossentry> @@ -7956,6 +8182,31 @@ 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 + "HOST" and a "TARGET" system. + See the + <link linkend='var-STAGING_DIR_TARGET'><filename>STAGING_DIR_TARGET</filename></link> + variable for more information. + </para> + + <para> + The default value of this variable is: + <literallayout class='monospaced'> + ${PACKAGE_ARCH}${HOST_VENDOR}-${HOST_OS} + </literallayout> + </para> + </glossdef> + </glossentry> + <glossentry id='var-MULTIMACH_TARGET_SYS'><glossterm>MULTIMACH_TARGET_SYS</glossterm> <info> MULTIMACH_TARGET_SYS[doc] = "Separates files for different machines such that you can build for multiple target machines using the same output directories." @@ -7963,10 +8214,33 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - Separates files for different machines such that you can build - for multiple target machines using the same output directories. - See the <link linkend='var-STAMP'><filename>STAMP</filename></link> variable - for an example. + Uniquely identifies the type of the target system for + which packages are being built. + This variable allows output for different types of target + systems to be put into different subdirectories of the same + output directory. + </para> + + <para> + The default value of this variable is: + <literallayout class='monospaced'> + ${PACKAGE_ARCH}${TARGET_VENDOR}-${TARGET_OS} + </literallayout> + Some classes (e.g. + <link linkend='ref-classes-cross-canadian'><filename>cross-canadian</filename></link>) + modify the <filename>MULTIMACH_TARGET_SYS</filename> value. + </para> + + <para> + 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. </para> </glossdef> </glossentry> @@ -8304,18 +8578,60 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossentry id='var-OVERRIDES'><glossterm>OVERRIDES</glossterm> <info> - OVERRIDES[doc] = "BitBake uses OVERRIDES to control what variables are overridden after BitBake parses recipes and configuration files." + OVERRIDES[doc] = "A colon-separated list of overrides that currently apply." </info> <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - BitBake uses <filename>OVERRIDES</filename> to control - what variables are overridden after BitBake parses - recipes and configuration files. - You can find more information on how overrides are handled - in the + A colon-separated list of overrides that currently apply. + Overrides are a BitBake mechanism that allows variables to + be selectively overridden at the end of parsing. + The set of overrides in <filename>OVERRIDES</filename> + represents the "state" during building, which includes + the current recipe being built, the machine for which + it is being built, and so forth. + </para> + + <para> + As an example, if the string "an-override" appears as an + element in the colon-separated list in + <filename>OVERRIDES</filename>, then the following + assignment will override <filename>FOO</filename> with the + value "overridden" at the end of parsing: + <literallayout class='monospaced'> + FOO_an-override = "overridden" + </literallayout> + See the "<ulink url='&YOCTO_DOCS_BB_URL;#conditional-syntax-overrides'>Conditional Syntax (Overrides)</ulink>" - section of the BitBake User Manual. + section in the BitBake User Manual for more information on + the overrides mechanism. + </para> + + <para> + The default value of <filename>OVERRIDES</filename> + includes the values of the + <link linkend='var-CLASSOVERRIDE'><filename>CLASSOVERRIDE</filename></link>, + <link linkend='var-MACHINEOVERRIDES'><filename>MACHINEOVERRIDES</filename></link>, + and + <link linkend='var-DISTROOVERRIDES'><filename>DISTROOVERRIDES</filename></link> + variables. + Another important override included by default is + <filename>pn-${PN}</filename>. + This override allows variables to be set for a single + recipe within configuration (<filename>.conf</filename>) + files. + Here is an example: + <literallayout class='monospaced'> + FOO_pn-myrecipe = "myrecipe-specific value" + </literallayout> + <note><title>Tip</title> + An easy way to see what overrides apply is to search for + <filename>OVERRIDES</filename> in the output of the + <filename>bitbake -e</filename> command. + See the + "<link linkend='usingpoky-debugging-viewing-variable-values'>Viewing Variable Values</link>" + section for more information. + </note> </para> </glossdef> </glossentry> @@ -8863,10 +9179,13 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <listitem><para>Extra arguments that should be added to the configure script argument list - (<link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>) + (<link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link> + or + <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link>) if the feature is enabled.</para></listitem> <listitem><para>Extra arguments that should be added to <filename>EXTRA_OECONF</filename> + or <filename>PACKAGECONFIG_CONFARGS</filename> if the feature is disabled. </para></listitem> <listitem><para>Additional build dependencies @@ -8950,6 +9269,50 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> + <glossentry id='var-PACKAGECONFIG_CONFARGS'><glossterm>PACKAGECONFIG_CONFARGS</glossterm> + <info> + PACKAGECONFIG_CONFARGS[doc] = "A space-separated list of configuration options generated from PACKAGECONFIG." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + A space-separated list of configuration options generated + 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>. + </para> + + <para> + For additional information, see the + <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link> + variable. + </para> + </glossdef> + </glossentry> + <glossentry id='var-PACKAGEGROUP_DISABLE_COMPLEMENTARY'><glossterm>PACKAGEGROUP_DISABLE_COMPLEMENTARY</glossterm> <info> PACKAGEGROUP_DISABLE_COMPLEMENTARY[doc] = "Prevents automatic creation of the normal complementary packages such as -dev and -dbg in a packagegroup recipe." @@ -8984,6 +9347,31 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN} </literallayout> </para> + + <para> + During packaging, the + <link linkend='ref-tasks-package'><filename>do_package</filename></link> + task goes through <filename>PACKAGES</filename> and uses + the + <link linkend='var-FILES'><filename>FILES</filename></link> + variable corresponding to each package to assign files to + the package. + If a file matches the <filename>FILES</filename> variable + for more than one package in <filename>PACKAGES</filename>, + it will be assigned to the earliest (leftmost) package. + </para> + + <para> + Packages in the variable's list that are empty (i.e. where + none of the patterns in + <filename>FILES_</filename><replaceable>pkg</replaceable> + match any files installed by the + <link linkend='ref-tasks-install'><filename>do_install</filename></link> + task) are not generated, unless generation is forced through + the + <link linkend='var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></link> + variable. + </para> </glossdef> </glossentry> @@ -9068,6 +9456,14 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" where <replaceable>x</replaceable> represents the maximum number of parallel threads <filename>make</filename> can run. + <note><title>Caution</title> + In order for <filename>PARALLEL_MAKE</filename> to be + effective, <filename>make</filename> must be called + with + <filename>${</filename><link linkend='var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></link><filename>}</filename>. + An easy way to ensure this is to use the + <filename>oe_runmake</filename> function. + </note> </para> <para> @@ -9114,16 +9510,24 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" task in order to specify parallel installation. This variable defaults to the value of <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>. - <note> - If the software being built experiences dependency - issues during the + <note><title>Notes and Cautions</title> + <para>In order for <filename>PARALLEL_MAKEINST</filename> + to be + effective, <filename>make</filename> must be called + with + <filename>${</filename><link linkend='var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></link><filename>}</filename>. + An easy way to ensure this is to use the + <filename>oe_runmake</filename> function.</para> + + <para>If the software being built experiences + dependency issues during the <filename>do_install</filename> task that result in race conditions, you can clear the <filename>PARALLEL_MAKEINST</filename> variable within the recipe as a workaround. For information on addressing race conditions, see the "<ulink url='&YOCTO_DOCS_DEV_URL;#debugging-parallel-make-races'>Debugging Parallel Make Races</ulink>" - section in the Yocto Project Development Manual. + section in the Yocto Project Development Manual.</para> </note> </para> </glossdef> @@ -9201,6 +9605,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" versioning scheme changes in some backwards incompatible way. </para> + + <para> + <filename>PE</filename> is the default value of the + <link linkend='var-PKGE'><filename>PKGE</filename></link> + variable. + </para> </glossdef> </glossentry> @@ -9316,14 +9726,16 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link> task packages data for each recipe and installs it into this temporary, shared area. - This directory defaults to the following: + This directory defaults to the following, which you should + not change: <literallayout class='monospaced'> ${STAGING_DIR_HOST}/pkgdata </literallayout> - </para> - - <para> - Do not change this default. + For examples of how this data is used, see the + "<link linkend='automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</link>" + section and the + "<link linkend='viewing-package-information-with-oe-pkgdata-util'>Viewing Package Information with <filename>oe-pkgdata-util</filename></link>" + section. </para> </glossdef> </glossentry> @@ -9354,45 +9766,41 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossentry id='var-PKGDESTWORK'><glossterm>PKGDESTWORK</glossterm> <info> - PKGDESTWORK[doc] = "Points to a temporary work area used by the do_package task to write output from the do_packagedata task." + PKGDESTWORK[doc] = "Points to a temporary work area where the do_package task saves package metadata." </info> <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - Points to a temporary work area used by the + Points to a temporary work area where the <link linkend='ref-tasks-package'><filename>do_package</filename></link> - task to write output from the - <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link> - task. + task saves package metadata. The <filename>PKGDESTWORK</filename> location defaults to the following: <literallayout class='monospaced'> ${WORKDIR}/pkgdata </literallayout> + Do not change this default. </para> <para> - The <filename>do_packagedata</filename> task then packages - the data in the temporary work area and installs it into a - shared directory pointed to by - <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>. - </para> - - <para> - Do not change this default. + The + <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link> + task copies the package metadata from + <filename>PKGDESTWORK</filename> to + <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link> + to make it available globally. </para> </glossdef> </glossentry> <glossentry id='var-PKGE'><glossterm>PKGE</glossterm> <info> - PKGE[doc] = "The epoch of the output package built by the OpenEmbedded build system." + PKGE[doc] = "The epoch of the package(s) built by the recipe." </info> <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - The epoch of the output package built by the - OpenEmbedded build system. + The epoch of the package(s) built by the recipe. By default, <filename>PKGE</filename> is set to <link linkend='var-PE'><filename>PE</filename></link>. </para> @@ -9401,13 +9809,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossentry id='var-PKGR'><glossterm>PKGR</glossterm> <info> - PKGR[doc] = "The revision of the output package built by the OpenEmbedded build system." + PKGR[doc] = "The revision of the package(s) built by the recipe." </info> <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - The revision of the output package built by the - OpenEmbedded build system. + The revision of the package(s) built by the recipe. By default, <filename>PKGR</filename> is set to <link linkend='var-PR'><filename>PR</filename></link>. </para> @@ -9416,13 +9823,13 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossentry id='var-PKGV'><glossterm>PKGV</glossterm> <info> - PKGV[doc] = "The version of the output package built by the OpenEmbedded build system." + PKGV[doc] = "The version of the package(s) built by the recipe." </info> <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - The version of the output package built by the - OpenEmbedded build system. + The version of the package(s) built by the + recipe. By default, <filename>PKGV</filename> is set to <link linkend='var-PV'><filename>PV</filename></link>. </para> @@ -9559,8 +9966,50 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - The revision of the recipe. - The default value for this variable is "r0". + The revision of the recipe. The default value for this + variable is "r0". + Subsequent revisions of the recipe conventionally have the + values "r1", "r2", and so forth. + When + <link linkend='var-PV'><filename>PV</filename></link> + increases, <filename>PR</filename> is conventionally reset + to "r0". + <note> + The OpenEmbedded build system does not need the aid of + <filename>PR</filename> to know when to rebuild a + recipe. + The build system uses the task + <ulink url='&YOCTO_DOCS_BB_URL;#checksums'>input checksums</ulink> + along with the + <link linkend='structure-build-tmp-stamps'>stamp</link> + and + <link linkend='shared-state-cache'>shared state cache</link> + mechanisms. + </note> + The <filename>PR</filename> variable primarily becomes + significant when a package manager dynamically installs + packages on an already built image. + In this case, <filename>PR</filename>, which is the default + value of + <link linkend='var-PKGR'><filename>PKGR</filename></link>, + helps the package manager distinguish which package is the + most recent one in cases where many packages have the same + <filename>PV</filename> (i.e. <filename>PKGV</filename>). + A component having many packages with the same + <filename>PV</filename> usually means that the packages all + install the same upstream version, but with later + (<filename>PR</filename>) version packages including + packaging fixes. + <note> + <filename>PR</filename> does not need to be increased + for changes that do not change the package contents or + metadata. + </note> + Because manually managing <filename>PR</filename> can be + cumbersome and error-prone, an automated solution exists. + See the + "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>Working With a PR Service</ulink>" + section for more information. </para> </glossdef> </glossentry> @@ -9619,9 +10068,34 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" numbers that could potentially change. Here are two examples: <literallayout class='monospaced'> - PREFERRED_VERSION_python = "2.7.3" + PREFERRED_VERSION_python = "3.4.0" PREFERRED_VERSION_linux-yocto = "3.19%" </literallayout> + <note> + The specified version is matched against + <link linkend='var-PV'><filename>PV</filename></link>, + which does not necessarily match the version part of + the recipe's filename. + For example, consider two recipes + <filename>foo_1.2.bb</filename> and + <filename>foo_git.bb</filename> where + <filename>foo_git.bb</filename> contains the following + assignment: + <literallayout class='monospaced'> + PV = "1.1+git${SRCPV}" + </literallayout> + In this case, the correct way to select + <filename>foo_git.bb</filename> is by using an + assignment such as the following: + <literallayout class='monospaced'> + PREFERRED_VERSION_foo = "1.1+git%" + </literallayout> + Compare that previous example against the following + incorrect example, which does not work: + <literallayout class='monospaced'> + PREFERRED_VERSION_foo = "git" + </literallayout> + </note> Sometimes the <filename>PREFERRED_VERSION</filename> variable can be set by configuration files in a way that is hard to change. @@ -9639,6 +10113,13 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <literallayout class='monospaced'> PREFERRED_VERSION_linux-yocto_forcevariable = "3.4%" </literallayout> + <note> + The <filename>_forcevariable</filename> override is + not handled specially. + This override only works because the default value of + <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link> + includes "forcevariable". + </note> </para> </glossdef> </glossentry> @@ -9751,6 +10232,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" libplds4.so" </literallayout> </para> + + <para> + For more information, see the + "<link linkend='automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</link>" + section. + </para> </glossdef> </glossentry> @@ -9784,6 +10271,51 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" The <filename>PROVIDES</filename> statement results in the "libav" recipe also being known as "libpostproc". </para> + + <para> + In addition to providing recipes under alternate names, + the <filename>PROVIDES</filename> mechanism is also used + to implement virtual targets. + A virtual target is a name that corresponds to some + particular functionality (e.g. a Linux kernel). + Recipes that provide the functionality in question list the + virtual target in <filename>PROVIDES</filename>. + Recipes that depend on the functionality in question can + include the virtual target in + <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link> + to leave the choice of provider open. + </para> + + <para> + Conventionally, virtual targets have names on the form + "virtual/function" (e.g. "virtual/kernel"). + The slash is simply part of the name and has no + syntactical significance. + </para> + + <para> + The + <link linkend='var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></link> + variable is used to select which particular recipe + provides a virtual target. + <note> + <para>A corresponding mechanism for virtual runtime + dependencies (packages) exists. + However, the mechanism does not depend on any special + functionality beyond ordinary variable assignments. + For example, + <filename>VIRTUAL-RUNTIME_dev_manager</filename> + refers to the package of the component that manages + the <filename>/dev</filename> directory.</para> + + <para>Setting the "preferred provider" for runtime + dependencies is as simple as using the following + assignment in a configuration file:</para> + <literallayout class='monospaced'> + VIRTUAL-RUNTIME_dev_manager = "udev" + </literallayout> + </note> + </para> </glossdef> </glossentry> @@ -9846,12 +10378,19 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" The version of the recipe. The version is normally extracted from the recipe filename. For example, if the recipe is named - <filename>expat_2.0.1.bb</filename>, then the default value of <filename>PV</filename> - will be "2.0.1". + <filename>expat_2.0.1.bb</filename>, then the default value + of <filename>PV</filename> will be "2.0.1". <filename>PV</filename> is generally not overridden within - a recipe unless it is building an unstable (i.e. development) version from a source code repository + a recipe unless it is building an unstable (i.e. + development) version from a source code repository (e.g. Git or Subversion). </para> + + <para> + <filename>PV</filename> is the default value of the + <link linkend='var-PKGV'><filename>PKGV</filename></link> + variable. + </para> </glossdef> </glossentry> @@ -9993,40 +10532,59 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm> <info> - RDEPENDS[doc] = "Lists a package's runtime dependencies (i.e. other packages) that must be installed for the package to be built. They must be the names of other packages as listed in the PACKAGES variable, not recipe names (PN)." + RDEPENDS[doc] = "Lists runtime dependencies of a package." </info> <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - Lists a package's runtime dependencies (i.e. other packages) - that must be installed in order for the built package to run - correctly. - If a package in this list cannot be found during the build, - you will get a build error. + Lists runtime dependencies of a package. + These dependencies are other packages that must be + installed in order for the package to function correctly. + As an example, the following assignment declares that the + package <filename>foo</filename> needs the packages + <filename>bar</filename> and <filename>baz</filename> to + be installed: + <literallayout class='monospaced'> + RDEPENDS_foo = "bar baz" + </literallayout> + The most common types of package runtime dependencies are + automatically detected and added. + Therefore, most recipes do not need to set + <filename>RDEPENDS</filename>. + For more information, see the + "<link linkend='automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</link>" + section. </para> <para> - When you use the <filename>RDEPENDS</filename> variable - in a recipe, you are essentially stating that the recipe's + The practical effect of the above + <filename>RDEPENDS</filename> assignment is that + <filename>bar</filename> and <filename>baz</filename> + will be declared as dependencies inside the package + <filename>foo</filename> when it is written out by one of + the + <link linkend='ref-tasks-package_write_deb'><filename>do_package_write_*</filename></link> + tasks. + Exactly how this is done depends on which package format + is used, which is determined by + <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>. + When the corresponding package manager installs the + package, it will know to also install the packages on + which it depends. + </para> + + <para> + To ensure that the packages <filename>bar</filename> and + <filename>baz</filename> get built, the previous + <filename>RDEPENDS</filename> assignment also causes a task + dependency to be added. + This dependency is from the recipe's <link linkend='ref-tasks-build'><filename>do_build</filename></link> - task depends on the existence of a specific package. - Consider this simple example for two recipes named "a" and - "b" that produce similarly named IPK packages. - In this example, the <filename>RDEPENDS</filename> - statement appears in the "a" recipe: - <literallayout class='monospaced'> - RDEPENDS_${PN} = "b" - </literallayout> - Here, the dependency is such that the - <filename>do_build</filename> task for recipe "a" depends - on the - <link linkend='ref-tasks-package_write_ipk'><filename>do_package_write_ipk</filename></link> - task of recipe "b". - This means the package file for "b" must be available when - the output for recipe "a" has been completely built. - More importantly, package "a" will be marked as depending - on package "b" in a manner that is understood by the - package manager. + (not to be confused with + <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>) + task to the <filename>do_package_write_*</filename> + task of the recipes that build <filename>bar</filename> and + <filename>baz</filename>. </para> <para> @@ -10046,7 +10604,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <para> Because the <filename>RDEPENDS</filename> variable applies to packages being built, you should always use the variable - in a form with an attached package name. + in a form with an attached package name (remember that a + single recipe can build multiple packages). For example, suppose you are building a development package that depends on the <filename>perl</filename> package. In this case, you would use the following @@ -10059,38 +10618,33 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" Thus, the <filename>RDEPENDS</filename> variable has the <filename>${PN}-dev</filename> package name as part of the variable. + <note> + <title>Caution</title> + <filename>RDEPENDS_${PN}-dev</filename> includes + <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename> + by default. + This default is set in the BitBake configuration file + (<filename>meta/conf/bitbake.conf</filename>). + Be careful not to accidentally remove + <filename>${PN}</filename> when modifying + <filename>RDEPENDS_${PN}-dev</filename>. + Use the "+=" operator rather than the "=" operator. + </note> </para> <para> - The package name you attach to the - <filename>RDEPENDS</filename> variable must appear - as it would in the <filename>PACKAGES</filename> - namespace before any renaming of the output package by - classes like - <link linkend='ref-classes-debian'><filename>debian</filename></link>. - </para> - - <para> - In many cases you do not need to explicitly add - runtime dependencies using - <filename>RDEPENDS</filename> since some automatic - handling occurs: - <itemizedlist> - <listitem><para><emphasis><filename>shlibdeps</filename></emphasis>: If - a runtime package contains a shared library - (<filename>.so</filename>), the build - processes the library in order to determine other - libraries to which it is dynamically linked. - The build process adds these libraries to - <filename>RDEPENDS</filename> when creating the runtime - package.</para></listitem> - <listitem><para><emphasis><filename>pcdeps</filename></emphasis>: If - the package ships a <filename>pkg-config</filename> - information file, the build process uses this file - to add items to the <filename>RDEPENDS</filename> - variable to create the runtime packages. - </para></listitem> - </itemizedlist> + The package names you use with + <filename>RDEPENDS</filename> must appear as they would in + the <filename>PACKAGES</filename> variable. + The + <link linkend='var-PKG'><filename>PKG</filename></link> + variable allows a different name to be used for + the final package (e.g. the + <link linkend='ref-classes-debian'><filename>debian</filename></link> + class uses this to rename packages), but this final package + name cannot be used with <filename>RDEPENDS</filename>, + which makes sense as <filename>RDEPENDS</filename> is meant + to be independent of the package format used. </para> <para> @@ -10123,6 +10677,11 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" For information on build-time dependencies, see the <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link> variable. + You can also see the + "<ulink url='&YOCTO_DOCS_BB_URL;#tasks'>Tasks</ulink>" and + "<ulink url='&YOCTO_DOCS_BB_URL;#dependencies'>Dependencies</ulink>" + sections in the BitBake User Manual for additional + information on tasks and dependencies. </para> </glossdef> </glossentry> @@ -10150,28 +10709,6 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-RM_OLD_IMAGE'><glossterm>RM_OLD_IMAGE</glossterm> - <info> - RM_OLD_IMAGE[doc] = "Reclaims disk space by removing previously built versions of the same image from the images directory pointed to by the DEPLOY_DIR variable." - </info> - <glossdef> - <para role="glossdeffirst"> -<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - Reclaims disk space by removing previously built - versions of the same image from the - <filename>images</filename> directory pointed to by the - <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link> - variable. - </para> - - <para> - Set this variable to "1" in your - <filename>local.conf</filename> file to remove these - images. - </para> - </glossdef> - </glossentry> - <glossentry id='var-RM_WORK_EXCLUDE'><glossterm>RM_WORK_EXCLUDE</glossterm> <info> RM_WORK_EXCLUDE[doc] = "With rm_work enabled, this variable specifies a list of packages whose work directories should not be removed." @@ -10802,6 +11339,33 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> + <glossentry id='var-SDK_INCLUDE_TOOLCHAIN'><glossterm>SDK_INCLUDE_TOOLCHAIN</glossterm> + <info> + SDK_INCLUDE_TOOLCHAIN[doc] = "When set to "1", specifies to include the toolchain in the extensible SDK." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + When set to "1", specifies to include the toolchain in the + extensible SDK. + Including the toolchain is useful particularly when + <link linkend='var-SDK_EXT_TYPE'><filename>SDK_EXT_TYPE</filename></link> + is set to "minimal" to keep the SDK reasonably small + but you still want to provide a usable toolchain. + For example, suppose you want to use the toolchain from an + IDE (e.g. Eclipse) or from other tools and you do not + want to perform additional steps to install the toolchain. + </para> + + <para> + The <filename>SDK_INCLUDE_TOOLCHAIN</filename> variable + defaults to "0" if <filename>SDK_EXT_TYPE</filename> + is set to "minimal", and defaults to "1" if + <filename>SDK_EXT_TYPE</filename> is set to "full". + </para> + </glossdef> + </glossentry> + <glossentry id='var-SDK_INHERIT_BLACKLIST'><glossterm>SDK_INHERIT_BLACKLIST</glossterm> <info> SDK_INHERIT_BLACKLIST[doc] = "A list of classes to remove from the INHERIT value globally within the extensible SDK configuration." @@ -11336,15 +11900,24 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossentry id='var-SERIAL_CONSOLES_CHECK'><glossterm>SERIAL_CONSOLES_CHECK</glossterm> <info> - SERIAL_CONSOLES_CHECK[doc] = "Similar to SERIAL_CONSOLES except the device is checked for existence before attempting to enable it. Supported only by SysVinit." + SERIAL_CONSOLES_CHECK[doc] = "Selected SERIAL_CONSOLES to check against /proc/console before enabling using getty. Supported only by SysVinit." </info> <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - Similar to - <link linkend='var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></link> - except the device is checked for existence before attempting - to enable it. + Specifies serial consoles, which must be listed in + <link linkend='var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></link>, + to check against <filename>/proc/console</filename> + before enabling them using getty. + This variable allows aliasing in the format: + <device>:<alias>. + If a device was listed as "sclp_line0" + in <filename>/dev/</filename> and "ttyS0" was listed + in <filename>/proc/console</filename>, you would do the + following: + <literallayout class='monospaced'> + SERIAL_CONSOLES_CHECK = "slcp_line0:ttyS0" + </literallayout> This variable is currently only supported with SysVinit (i.e. not with systemd). </para> @@ -11982,7 +12555,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" directory structure. <literallayout class='monospaced'> SSTATE_MIRRORS ?= "\ - file://.* http://<replaceable>someserver</replaceable>.tld/share/sstate/PATH \n \ + file://.* http://<replaceable>someserver</replaceable>.tld/share/sstate/PATH;downloadfilename=PATH \n \ file://.* file:///<replaceable>some-local-dir</replaceable>/sstate/PATH" </literallayout> </para> @@ -12129,28 +12702,71 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossentry id='var-STAGING_DIR_HOST'><glossterm>STAGING_DIR_HOST</glossterm> <info> - STAGING_DIR_HOST[doc] = "Specifies the path to the primary sysroot directory for which the target is being built." + STAGING_DIR_HOST[doc] = "Specifies the path to the sysroot directory for the system that the component is built to run on." </info> <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - Specifies the path to the primary sysroot directory for - which the target is being built. - Depending on the type of recipe and the build target, the - recipe's value is as follows: + Specifies the path to the sysroot directory for the system + that the component is built to run on (the system that hosts + the component). + For most recipes, this sysroot is the one that the recipe's + <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link> + task copies files into. + Exceptions include <filename>-native</filename> recipes, + where the <filename>do_populate_sysroot</filename> task + instead uses + <link linkend='var-STAGING_DIR_NATIVE'><filename>STAGING_DIR_NATIVE</filename></link>. + Depending on the type of recipe and the build target, + <filename>STAGING_DIR_HOST</filename> can have the + following values: <itemizedlist> <listitem><para>For recipes building for the target - machine, the value is "${STAGING_DIR}/${MACHINE}". - </para></listitem> + machine, the value is + "${<link linkend='var-STAGING_DIR'>STAGING_DIR</link>}/${<link linkend='var-MACHINE'>MACHINE</link>}". + </para></listitem> <listitem><para>For native recipes building - for the build host, the value is empty given the - assumption that when building for the build host, - the build host's own directories should be used. + for the build host, the value is empty given the + assumption that when building for the build host, + the build host's own directories should be used. + <note><para> + <filename>-native</filename> recipes are not + installed into host paths like such as + <filename>/usr</filename>. + Rather, these recipes are installed into + <filename>STAGING_DIR_NATIVE</filename>. + When compiling <filename>-native</filename> + recipes, standard build environment variables + such as + <link linkend='var-CPPFLAGS'><filename>CPPFLAGS</filename></link> + and + <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link> + are set up so that both host paths and + <filename>STAGING_DIR_NATIVE</filename> are + searched for libraries and headers using, for + example, GCC's <filename>-isystem</filename> + option.</para> + + <para>This emphasizes that the + <filename>STAGING_DIR*</filename> variables + should be viewed as input variables by tasks + such as + <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>, + <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>, + and + <link linkend='ref-tasks-install'><filename>do_install</filename></link>. + Having the real system root correspond to + <filename>STAGING_DIR_HOST</filename> makes + conceptual sense for + <filename>-native</filename> recipes, as + 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}/${MULTIMACH_HOST_SYS}". + "${STAGING_DIR}/${<link linkend='var-MULTIMACH_HOST_SYS'>MULTIMACH_HOST_SYS</link>}". </para></listitem> </itemizedlist> </para> @@ -12159,27 +12775,29 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossentry id='var-STAGING_DIR_NATIVE'><glossterm>STAGING_DIR_NATIVE</glossterm> <info> - STAGING_DIR_NATIVE[doc] = "Specifies the path to the sysroot directory for the build host." + STAGING_DIR_NATIVE[doc] = "Specifies the path to the sysroot directory used when building components that run on the build host itself." </info> <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - Specifies the path to the sysroot directory for the - build host. + Specifies the path to the sysroot directory used when + building components that run on the build host itself. </para> </glossdef> </glossentry> <glossentry id='var-STAGING_DIR_TARGET'><glossterm>STAGING_DIR_TARGET</glossterm> <info> - STAGING_DIR_TARGET[doc] = "Specifies the path to the sysroot directory for the target for which the current recipe is being built." + STAGING_DIR_TARGET[doc] = "Specifies the path to the sysroot used for the system for which the component generates code." </info> <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - Specifies the path to the sysroot directory for the - target for which the current recipe is being built. - In most cases, this path is the + Specifies the path to the sysroot used for the system for + which the component generates code. + For components that do not generate code, which is the + majority, <filename>STAGING_DIR_TARGET</filename> is set + to match <link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>. </para> @@ -12190,10 +12808,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" Using terminology from GNU, the primary system is referred to as the "HOST" and the secondary, or different, system is referred to as the "TARGET". - Thus, the binaries run on the "HOST" system and + Thus, the binaries run on the "HOST" system and generate binaries for the "TARGET" system. - <filename>STAGING_DIR_TARGET</filename> points to the - sysroot used for the "TARGET" system. + The <filename>STAGING_DIR_HOST</filename> variable points + to the sysroot used for the "HOST" system, while + <filename>STAGING_DIR_TARGET</filename> + points to the sysroot used for the "TARGET" system. </para> </glossdef> </glossentry> @@ -12335,6 +12955,13 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </para> <para> + For information on how BitBake uses stamp files to determine + if a task should be rerun, see the + "<link linkend='stamp-files-and-the-rerunning-of-tasks'>Stamp Files and the Rerunning of Tasks</link>" + section. + </para> + + <para> See <link linkend='var-STAMPS_DIR'><filename>STAMPS_DIR</filename></link>, <link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>, <link linkend='var-PN'><filename>PN</filename></link>, @@ -12519,6 +13146,95 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </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." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Directories that are staged into the sysroot by the + <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link> + task. + By default, the following directories are staged: + <literallayout class='monospaced'> + SYSROOT_DIRS = " \ + ${includedir} \ + ${libdir} \ + ${base_libdir} \ + ${nonarch_base_libdir} \ + ${datadir} \ + " + </literallayout> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-SYSROOT_DIRS_BLACKLIST'><glossterm>SYSROOT_DIRS_BLACKLIST</glossterm> + <info> + SYSROOT_DIRS_BLACKLIST[doc] = "Directories that are not staged into the sysroot by the do_populate_sysroot task." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Directories that are not staged into the sysroot by the + <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link> + task. + You can use this variable to exclude certain subdirectories + of directories listed in + <link linkend='var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></link> + from staging. + By default, the following directories are not staged: + <literallayout class='monospaced'> + SYSROOT_DIRS_BLACKLIST = " \ + ${mandir} \ + ${docdir} \ + ${infodir} \ + ${datadir}/locale \ + ${datadir}/applications \ + ${datadir}/fonts \ + ${datadir}/pixmaps \ + " + </literallayout> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-SYSROOT_DIRS_NATIVE'><glossterm>SYSROOT_DIRS_NATIVE</glossterm> + <info> + SYSROOT_DIRS_NATIVE[doc] = "Extra directories staged into the sysroot by the do_populate_sysroot task for -native recipes, in addition to those specified in SYSROOT_DIRS." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Extra directories staged into the sysroot by the + <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link> + task for <filename>-native</filename> recipes, in addition + to those specified in + <link linkend='var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></link>. + By default, the following extra directories are staged: + <literallayout class='monospaced'> + SYSROOT_DIRS_NATIVE = " \ + ${bindir} \ + ${sbindir} \ + ${base_bindir} \ + ${base_sbindir} \ + ${libexecdir} \ + ${sysconfdir} \ + ${localstatedir} \ + " + </literallayout> + <note> + Programs built by <filename>-native</filename> recipes + run directly from the sysroot + (<link linkend='var-STAGING_DIR_NATIVE'><filename>STAGING_DIR_NATIVE</filename></link>), + which is why additional directories containing program + executables and supporting files need to be staged. + </note> + </para> + </glossdef> + </glossentry> + <glossentry id='var-SYSROOT_PREPROCESS_FUNCS'><glossterm>SYSROOT_PREPROCESS_FUNCS</glossterm> <info> SYSROOT_PREPROCESS_FUNCS[doc] = "A list of functions to execute after files are staged into the sysroot. These functions are usually used to apply additional processing on the staged files, or to stage additional files." @@ -12565,6 +13281,92 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> + <glossentry id='var-SYSTEMD_BOOT_CFG'><glossterm>SYSTEMD_BOOT_CFG</glossterm> + <info> + SYSTEMD_BOOT_CFG[doc] = "When EFI_PROVIDER is set to "systemd-boot", the SYSTEMD_BOOT_CFG variable specifies the configuration file that should be used." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + When + <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link> + is set to "systemd-boot", the + <filename>SYSTEMD_BOOT_CFG</filename> variable specifies the + configuration file that should be used. + By default, the + <link linkend='ref-classes-systemd-boot'><filename>systemd-boot</filename></link> + class sets the <filename>SYSTEMD_BOOT_CFG</filename> as + follows: + <literallayout class='monospaced'> + SYSTEMD_BOOT_CFG ?= "${<link linkend='var-S'>S</link>}/loader.conf" + </literallayout> + </para> + + <para> + For information on Systemd-boot, see the + <ulink url='http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/'>Systemd-boot documentation</ulink>. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-SYSTEMD_BOOT_ENTRIES'><glossterm>SYSTEMD_BOOT_ENTRIES</glossterm> + <info> + SYSTEMD_BOOT_ENTRIES[doc] = "When EFI_PROVIDER is set to "systemd-boot", the SYSTEMD_BOOT_ENTRIES variable specifies a list of entry files (*.conf) to be installed containing one boot entry per file." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + When + <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link> + is set to "systemd-boot", the + <filename>SYSTEMD_BOOT_ENTRIES</filename> variable specifies + a list of entry files + (<filename>*.conf</filename>) to be installed + containing one boot entry per file. + By default, the + <link linkend='ref-classes-systemd-boot'><filename>systemd-boot</filename></link> + class sets the <filename>SYSTEMD_BOOT_ENTRIES</filename> as + follows: + <literallayout class='monospaced'> + SYSTEMD_BOOT_ENTRIES ?= "" + </literallayout> + </para> + + <para> + For information on Systemd-boot, see the + <ulink url='http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/'>Systemd-boot documentation</ulink>. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-SYSTEMD_BOOT_TIMEOUT'><glossterm>SYSTEMD_BOOT_TIMEOUT</glossterm> + <info> + SYSTEMD_BOOT_TIMEOUT[doc] = "When EFI_PROVIDER is set to "systemd-boot", the SYSTEMD_BOOT_TIMEOUT variable specifies the boot menu timeout in seconds." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + When + <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link> + is set to "systemd-boot", the + <filename>SYSTEMD_BOOT_TIMEOUT</filename> variable specifies + the boot menu timeout in seconds. + By default, the + <link linkend='ref-classes-systemd-boot'><filename>systemd-boot</filename></link> + class sets the <filename>SYSTEMD_BOOT_TIMEOUT</filename> as + follows: + <literallayout class='monospaced'> + SYSTEMD_BOOT_TIMEOUT ?= "10" + </literallayout> + </para> + + <para> + For information on Systemd-boot, see the + <ulink url='http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/'>Systemd-boot documentation</ulink>. + </para> + </glossdef> + </glossentry> + <glossentry id='var-SYSTEMD_PACKAGES'><glossterm>SYSTEMD_PACKAGES</glossterm> <info> SYSTEMD_PACKAGES[doc] = "For recipes that inherit the systemd class, this variable locates the systemd unit files when they are not found in the main recipe's package." @@ -14255,7 +15057,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" task. Normally, invalid configure options are simply not passed to the configure script (e.g. should be removed from - <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>). + <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link> + or + <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link>). However, common options, for example, exist that are passed to all configure scripts at a class level that might not be valid for some configure scripts. @@ -14300,6 +15104,84 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> + <glossentry id='var-UPSTREAM_CHECK_GITTAGREGEX'><glossterm>UPSTREAM_CHECK_GITTAGREGEX</glossterm> + <info> + UPSTREAM_CHECK_GITTAGREGEX[doc] = "Filters relevant Git tags when fetching source from an upstream Git repository." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + When the + <link linkend='ref-classes-distrodata'><filename>distrodata</filename></link> + class is enabled globally, you can perform a per-recipe + check for what the latest upstream source code version is + by calling + <filename>bitbake -c checkpkg</filename> <replaceable>recipe</replaceable>. + If the recipe source code is provided from Git + repositories, the OpenEmbedded build system determines the + latest upstream version by picking the latest tag from the + list of all repository tags. + You can use the + <filename>UPSTREAM_CHECK_GITTAGREGEX</filename> + variable to provide a regular expression to filter only the + relevant tags should the default filter not work + correctly. + <literallayout class='monospaced'> + UPSTREAM_CHECK_GITTAGREGEX = "git_tag_regex" + </literallayout> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-UPSTREAM_CHECK_REGEX'><glossterm>UPSTREAM_CHECK_REGEX</glossterm> + <info> + UPSTREAM_CHECK_REGEX[doc] = "The regular expression the package checking system uses to parse the page pointed to by UPSTREAM_CHECK_URI." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + When the + <link linkend='ref-classes-distrodata'><filename>distrodata</filename></link> + class is enabled globally, use the + <filename>UPSTREAM_CHECK_REGEX</filename> variable to + specify a different regular expression instead of the + default one when the package checking system is parsing + the page found using + <link linkend='var-UPSTREAM_CHECK_URI'><filename>UPSTREAM_CHECK_URI</filename></link>. + <literallayout class='monospaced'> + UPSTREAM_CHECK_REGEX = "package_regex" + </literallayout> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-UPSTREAM_CHECK_URI'><glossterm>UPSTREAM_CHECK_URI</glossterm> + <info> + UPSTREAM_CHECK_URI[doc] = "The URL used by the package checking system to get the latest version of the package when source files are fetched from an upstream Git repository." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + When the + <link linkend='ref-classes-distrodata'><filename>distrodata</filename></link> + class is enabled globally, you can perform a per-recipe + check for what the latest upstream source code version is + by calling <filename>bitbake -c checkpkg</filename> + <replaceable>recipe</replaceable>. + If the source code is provided from tarballs, the latest + version is determined by fetching the directory listing + where the tarball is and attempting to find a later tarball. + When this approach does not work, you can use + <filename>UPSTREAM_CHECK_URI</filename> to + provide a different URI that contains the link to the + latest tarball. + <literallayout class='monospaced'> + UPSTREAM_CHECK_URI = "recipe_url" + </literallayout> + </para> + </glossdef> + </glossentry> + <glossentry id='var-USE_DEVFS'><glossterm>USE_DEVFS</glossterm> <info> USE_DEVFS[doc] = "Determines if devtmpfs is used for /dev population." @@ -14381,16 +15263,18 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossentry id='var-USERADD_ERROR_DYNAMIC'><glossterm>USERADD_ERROR_DYNAMIC</glossterm> <info> - USERADD_ERROR_DYNAMIC[doc] = "Forces the OpenEmbedded build system to produce an error if the user identification (uid) and group identification (gid) values are not defined in files/passwd and files/group files." + USERADD_ERROR_DYNAMIC[doc] = "If set to 'error', forces the OpenEmbedded build system to produce an error if the user identification (uid) and group identification (gid) values are not defined in files/passwd and files/group files. If set to 'warn', a warning will be issued instead." </info> <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - Forces the OpenEmbedded build system to produce an error - if the user identification (<filename>uid</filename>) and - group identification (<filename>gid</filename>) values - are not defined in <filename>files/passwd</filename> + If set to "error", forces the OpenEmbedded build system to + produce an error if the user identification + (<filename>uid</filename>) and group identification + (<filename>gid</filename>) values are not defined + in <filename>files/passwd</filename> and <filename>files/group</filename> files. + If set to "warn", a warning will be issued instead. </para> <para> @@ -14406,7 +15290,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" your <filename>local.conf</filename> file as follows: <literallayout class='monospaced'> - USERADD_ERROR_DYNAMIC = "1" + USERADD_ERROR_DYNAMIC = "error" </literallayout> Overriding the default behavior implies you are going to also take steps to set static <filename>uid</filename> and @@ -14562,7 +15446,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossentry id='var-USERADDEXTENSION'><glossterm>USERADDEXTENSION</glossterm> <info> - USERADDEXTENSION[doc] = "When set to "useradd-staticids", causes the OpenEmbedded build system to base all user and group additions on a static passwd and group files found in BBPATH." + USERADDEXTENSION[doc] = "When set to 'useradd-staticids', causes the OpenEmbedded build system to base all user and group additions on a static passwd and group files found in BBPATH." </info> <glossdef> <para role="glossdeffirst"> diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-varlocality.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-varlocality.xml index d3f873298..54524d5b6 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/ref-varlocality.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/ref-varlocality.xml @@ -176,16 +176,18 @@ <para> This section lists variables that define extra build information for recipes. <itemizedlist> + <listitem><para><filename><link linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE + </link></filename></para></listitem> <listitem><para><filename><link linkend='var-EXTRA_OECMAKE'>EXTRA_OECMAKE</link> </filename></para></listitem> <listitem><para><filename><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link> </filename></para></listitem> <listitem><para><filename><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link> </filename></para></listitem> + <listitem><para><filename><link linkend='var-PACKAGECONFIG_CONFARGS'>PACKAGECONFIG_CONFARGS</link> + </filename></para></listitem> <listitem><para><filename><link linkend='var-PACKAGES'>PACKAGES</link></filename> </para></listitem> - <listitem><para><filename><link linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE - </link></filename></para></listitem> </itemizedlist> </para> </section> 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 f06382ab5..9bb09fb94 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/technical-details.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/technical-details.xml @@ -690,6 +690,125 @@ addtask do_deploy_setscene do_deploy[dirs] = "${DEPLOYDIR} ${B}" </literallayout> + The following list explains the previous example: + <itemizedlist> + <listitem><para> + Adding "do_deploy" to <filename>SSTATETASKS</filename> + adds some required sstate-related processing, which is + implemented in the + <link linkend='ref-classes-sstate'><filename>sstate</filename></link> + class, to before and after the + <link linkend='ref-tasks-deploy'><filename>do_deploy</filename></link> + task. + </para></listitem> + <listitem><para> + The + <filename>do_deploy[sstate-inputdirs] = "${DEPLOYDIR}"</filename> + declares that <filename>do_deploy</filename> places its + output in <filename>${DEPLOYDIR}</filename> when run + normally (i.e. when not using the sstate cache). + This output becomes the input to the shared state cache. + </para></listitem> + <listitem><para> + The + <filename>do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}"</filename> + line causes the contents of the shared state cache to be + copied to <filename>${DEPLOY_DIR_IMAGE}</filename>. + <note> + If <filename>do_deploy</filename> is not already in + the shared state cache or if its input checksum + (signature) has changed from when the output was + cached, the task will be run to populate the shared + state cache, after which the contents of the shared + state cache is copied to + <filename>${DEPLOY_DIR_IMAGE}</filename>. + If <filename>do_deploy</filename> is in the shared + state cache and its signature indicates that the + cached output is still valid (i.e. if no + relevant task inputs have changed), then the contents + of the shared state cache will be copied directly to + <filename>${DEPLOY_DIR_IMAGE}</filename> by the + <filename>do_deploy_setscene</filename> task instead, + skipping the <filename>do_deploy</filename> task. + </note> + </para></listitem> + <listitem><para> + The following task definition is glue logic needed to make + the previous settings effective: + <literallayout class='monospaced'> + python do_deploy_setscene () { + sstate_setscene(d) + } + addtask do_deploy_setscene + </literallayout> + <filename>sstate_setscene()</filename> takes the flags + above as input and accelerates the + <filename>do_deploy</filename> task through the + shared state cache if possible. + If the task was accelerated, + <filename>sstate_setscene()</filename> returns True. + Otherwise, it returns False, and the normal + <filename>do_deploy</filename> task runs. + For more information, see the + "<ulink url='&YOCTO_DOCS_BB_URL;#setscene'>setscene</ulink>" + section in the BitBake User Manual. + </para></listitem> + <listitem><para> + The <filename>do_deploy[dirs] = "${DEPLOYDIR} ${B}"</filename> + line creates <filename>${DEPLOYDIR}</filename> and + <filename>${B}</filename> before the + <filename>do_deploy</filename> task runs, and also sets + the current working directory of + <filename>do_deploy</filename> to + <filename>${B}</filename>. + For more information, see the + "<ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'>Variable Flags</ulink>" + section in the BitBake User Manual. + <note> + In cases where + <filename>sstate-inputdirs</filename> and + <filename>sstate-outputdirs</filename> would be the + same, you can use + <filename>sstate-plaindirs</filename>. + For example, to preserve the + <filename>${PKGD}</filename> and + <filename>${PKGDEST}</filename> output from the + <link linkend='ref-tasks-package'><filename>do_package</filename></link> + task, use the following: + <literallayout class='monospaced'> + do_package[sstate-plaindirs] = "${PKGD} ${PKGDEST}" + </literallayout> + </note> + </para></listitem> + <listitem><para> + <filename>sstate-inputdirs</filename> and + <filename>sstate-outputdirs</filename> can also be used + with multiple directories. + For example, the following declares + <filename>PKGDESTWORK</filename> and + <filename>SHLIBWORK</filename> as shared state + input directories, which populates the shared state + cache, and <filename>PKGDATA_DIR</filename> and + <filename>SHLIBSDIR</filename> as the corresponding + shared state output directories: + <literallayout class='monospaced'> + do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}" + do_package[sstate-outputdirs] = "${PKGDATA_DIR} ${SHLIBSDIR}" + </literallayout> + </para></listitem> + <listitem><para> + These methods also include the ability to take a lockfile + when manipulating shared state directory structures, + for cases where file additions or removals are sensitive: + <literallayout class='monospaced'> + do_package[sstate-lockfile] = "${PACKAGELOCK}" + </literallayout> + </para></listitem> + </itemizedlist> + </para> + +<!-- + <para> In this example, we add some extra flags to the task, a name field ("deploy"), an input directory where the task sends data, and the output directory where the data from the task should eventually be copied. @@ -713,6 +832,7 @@ shared state directory structures since some cases are sensitive to file additions or removals. </para> +--> <para> Behind the scenes, the shared state code works by looking in @@ -722,7 +842,7 @@ Here is an example: <literallayout class='monospaced'> SSTATE_MIRRORS ?= "\ - file://.* http://someserver.tld/share/sstate/PATH \n \ + file://.* http://someserver.tld/share/sstate/PATH;downloadfilename=PATH \n \ file://.* file:///some/local/dir/sstate/PATH" </literallayout> <note> @@ -781,56 +901,15 @@ <title>Debugging</title> <para> - When things go wrong, debugging needs to be straightforward. - Because of this, the Yocto Project includes strong debugging - tools: - <itemizedlist> - <listitem><para>Whenever a shared state package is written - out into the - <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>, - a corresponding <filename>.siginfo</filename> file is - also written. - This file contains a pickled Python database of all - the Metadata that went into creating the hash for a - given shared state package. - Whenever a stamp is written into the stamp directory - <link linkend='var-STAMP'><filename>STAMP</filename></link>, - a corresponding <filename>.sigdata</filename> file - is created that contains the same hash data that - represented the executed task. - </para></listitem> - <listitem><para>You can use BitBake to dump out the - signature construction information without executing - tasks by using either of the following BitBake - command-line options: - <literallayout class='monospaced'> - ‐‐dump-signatures=<replaceable>SIGNATURE_HANDLER</replaceable> - -S <replaceable>SIGNATURE_HANDLER</replaceable> - </literallayout> - <note> - Two common values for - <replaceable>SIGNATURE_HANDLER</replaceable> are - "none" and "printdiff" to only dump the signature - or to compare the dumped signature with the - cached one, respectively. - </note> - Using BitBake with either of these options causes - BitBake to dump out <filename>.sigdata</filename> files - in the stamp directory for every task it would have - executed instead of building the specified target - package. - </para></listitem> - <listitem><para>There is a - <filename>bitbake-diffsigs</filename> command that - can process <filename>.sigdata</filename> and - <filename>.siginfo</filename> files. - If you specify one of these files, BitBake dumps out - the dependency information in the file. - If you specify two files, BitBake compares the two - files and dumps out the differences between the two. - This more easily helps answer the question of "What - changed between X and Y?"</para></listitem> - </itemizedlist> + Seeing what metadata went into creating the input signature + of a shared state (sstate) task can be a useful debugging aid. + This information is available in signature information + (<filename>siginfo</filename>) files in + <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>. + For information on how to view and interpret information in + <filename>siginfo</filename> files, see the + "<link linkend='usingpoky-viewing-task-variable-dependencies'>Viewing Task Variable Dependencies</link>" + section. </para> </section> @@ -900,6 +979,222 @@ </section> </section> +<section id='automatically-added-runtime-dependencies'> + <title>Automatically Added Runtime Dependencies</title> + + <para> + The OpenEmbedded build system automatically adds common types of + runtime dependencies between packages, which means that you do not + need to explicitly declare the packages using + <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>. + Three automatic mechanisms exist (<filename>shlibdeps</filename>, + <filename>pcdeps</filename>, and <filename>depchains</filename>) that + handle shared libraries, package configuration (pkg-config) modules, + and <filename>-dev</filename> and <filename>-dbg</filename> packages, + respectively. + For other types of runtime dependencies, you must manually declare + the dependencies. + <itemizedlist> + <listitem><para> + <filename>shlibdeps</filename>: + During the + <link linkend='ref-tasks-package'><filename>do_package</filename></link> + task of each recipe, all shared libraries installed by the + recipe are located. + For each shared library, the package that contains the shared + library is registered as providing the shared library. + More specifically, the package is registered as providing the + <ulink url='https://en.wikipedia.org/wiki/Soname'>soname</ulink> + of the library. + The resulting shared-library-to-package mapping + is saved globally in + <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link> + by the + <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link> + task.</para> + + <para>Simultaneously, all executables and shared libraries + installed by the recipe are inspected to see what shared + libraries they link against. + For each shared library dependency that is found, + <filename>PKGDATA_DIR</filename> is queried to + see if some package (likely from a different recipe) contains + the shared library. + If such a package is found, a runtime dependency is added from + the package that depends on the shared library to the package + that contains the library.</para> + + <para>The automatically added runtime dependency also includes + a version restriction. + This version restriction specifies that at least the current + version of the package that provides the shared library must be + used, as if + "<replaceable>package</replaceable> (>= <replaceable>version</replaceable>)" + had been added to + <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>. + This forces an upgrade of the package containing the shared + library when installing the package that depends on the + library, if needed.</para> + + <para>If you want to avoid a package being registered as + providing a particular shared library (e.g. because the library + is for internal use only), then add the library to + <link linkend='var-PRIVATE_LIBS'><filename>PRIVATE_LIBS</filename></link> + inside the package's recipe. + </para></listitem> + <listitem><para> + <filename>pcdeps</filename>: + During the + <link linkend='ref-tasks-package'><filename>do_package</filename></link> + task of each recipe, all pkg-config modules + (<filename>*.pc</filename> files) installed by the recipe are + located. + For each module, the package that contains the module is + registered as providing the module. + The resulting module-to-package mapping is saved globally in + <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link> + by the + <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link> + task.</para> + + <para>Simultaneously, all pkg-config modules installed by the + recipe are inspected to see what other pkg-config modules they + depend on. + A module is seen as depending on another module if it contains + a "Requires:" line that specifies the other module. + For each module dependency, + <filename>PKGDATA_DIR</filename> is queried to see if some + package contains the module. + If such a package is found, a runtime dependency is added from + the package that depends on the module to the package that + contains the module. + <note> + The <filename>pcdeps</filename> mechanism most often infers + dependencies between <filename>-dev</filename> packages. + </note> + </para></listitem> + <listitem><para> + <filename>depchains</filename>: + If a package <filename>foo</filename> depends on a package + <filename>bar</filename>, then <filename>foo-dev</filename> + and <filename>foo-dbg</filename> are also made to depend on + <filename>bar-dev</filename> and <filename>bar-dbg</filename>, + respectively. + Taking the <filename>-dev</filename> packages as an example, + the <filename>bar-dev</filename> package might provide + headers and shared library symlinks needed by + <filename>foo-dev</filename>, which shows the need + for a dependency between the packages.</para> + + <para>The dependencies added by <filename>depchains</filename> + are in the form of + <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>. + <note> + By default, <filename>foo-dev</filename> also has an + <filename>RDEPENDS</filename>-style dependency on + <filename>foo</filename>, because the default value of + <filename>RDEPENDS_${PN}-dev</filename> (set in + <filename>bitbake.conf</filename>) includes + "${PN}". + </note></para> + + <para>To ensure that the dependency chain is never broken, + <filename>-dev</filename> and <filename>-dbg</filename> + packages are always generated by default, even if the packages + turn out to be empty. + See the + <link linkend='var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></link> + variable for more information. + </para></listitem> + </itemizedlist> + </para> + + <para> + The <filename>do_package</filename> task depends on the + <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link> + task of each recipe in + <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link> + through use of a + <filename>[</filename><ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>deptask</filename></ulink><filename>]</filename> + declaration, which guarantees that the required + shared-library/module-to-package mapping information will be available + when needed as long as <filename>DEPENDS</filename> has been + correctly set. + </para> +</section> + +<section id='fakeroot-and-pseudo'> + <title>Fakeroot and Pseudo</title> + + <para> + Some tasks are easier to implement when allowed to perform certain + operations that are normally reserved for the root user. + For example, the + <link linkend='ref-tasks-install'><filename>do_install</filename></link> + task benefits from being able to set the UID and GID of installed files + to arbitrary values. + </para> + + <para> + One approach to allowing tasks to perform root-only operations + would be to require BitBake to run as root. + However, this method is cumbersome and has security issues. + The approach that is actually used is to run tasks that benefit from + root privileges in a "fake" root environment. + Within this environment, the task and its child processes believe that + they are running as the root user, and see an internally consistent + view of the filesystem. + As long as generating the final output (e.g. a package or an image) + does not require root privileges, the fact that some earlier steps ran + in a fake root environment does not cause problems. + </para> + + <para> + The capability to run tasks in a fake root environment is known as + "fakeroot", which is derived from the BitBake keyword/variable + flag that requests a fake root environment for a task. + In current versions of the OpenEmbedded build system, + the program that implements fakeroot is known as Pseudo. + </para> + + <para> + Pseudo overrides system calls through the + <filename>LD_PRELOAD</filename> mechanism to give the + illusion of running as root. + To keep track of "fake" file ownership and permissions resulting from + operations that require root permissions, an sqlite3 + database is used. + This database is stored in + <filename>${</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link><filename>}/pseudo/files.db</filename> + for individual recipes. + Storing the database in a file as opposed to in memory + gives persistence between tasks, and even between builds. + <note><title>Caution</title> + If you add your own task that manipulates the same files or + directories as a fakeroot task, then that task should also run + under fakeroot. + Otherwise, the task will not be able to run root-only operations, + and will not see the fake file ownership and permissions set by the + other task. + You should also add a dependency on + <filename>virtual/fakeroot-native:do_populate_sysroot</filename>, + giving the following: + <literallayout class='monospaced'> + fakeroot do_mytask () { + ... + } + do_mytask[depends] += "virtual/fakeroot-native:do_populate_sysroot" + </literallayout> + </note> + For more information, see the + <ulink url='&YOCTO_DOCS_BB_URL;#var-FAKEROOT'><filename>FAKEROOT*</filename></ulink> + variables in the BitBake User Manual. + You can also reference this + <ulink url='http://www.ibm.com/developerworks/opensource/library/os-aapseudo1/index.html'>Pseudo</ulink> + article. + </para> +</section> + <section id='x32'> <title>x32</title> diff --git a/import-layers/yocto-poky/documentation/ref-manual/usingpoky.xml b/import-layers/yocto-poky/documentation/ref-manual/usingpoky.xml index a7bf32d45..f7345547c 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/usingpoky.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/usingpoky.xml @@ -119,8 +119,8 @@ </para> </section> -<section id='usingpoky-debugging'> - <title>Debugging Build Failures</title> +<section id='usingpoky-debugging-tools-and-techniques'> + <title>Debugging Tools and Techniques</title> <para> The exact method for debugging build failures depends on the nature of @@ -163,23 +163,420 @@ <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual'>BitBake User Manual</ulink>. </note> + <section id='usingpoky-debugging-viewing-logs-from-failed-tasks'> + <title>Viewing Logs from Failed Tasks</title> - <section id='usingpoky-debugging-taskfailures'> - <title>Task Failures</title> + <para> + You can find the log for a task in the file + <filename>${</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link><filename>}/temp/log.do_</filename><replaceable>taskname</replaceable>. + For example, the log for the + <link linkend='ref-tasks-compile'><filename>do_compile</filename></link> + task of the QEMU minimal image for the x86 machine + (<filename>qemux86</filename>) might be in + <filename>tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/temp/log.do_compile</filename>. + To see the commands + <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink> ran + to generate a log, look at the corresponding + <filename>run.do_</filename><replaceable>taskname</replaceable> + file in the same directory. + </para> + + <para> + <filename>log.do_</filename><replaceable>taskname</replaceable> and + <filename>run.do_</filename><replaceable>taskname</replaceable> + are actually symbolic links to + <filename>log.do_</filename><replaceable>taskname</replaceable><filename>.</filename><replaceable>pid</replaceable> + and + <filename>log.run_</filename><replaceable>taskname</replaceable><filename>.</filename><replaceable>pid</replaceable>, + where <replaceable>pid</replaceable> is the PID the task had when + it ran. + The symlinks always point to the files corresponding to the most + recent run. + </para> + </section> + + <section id='usingpoky-debugging-viewing-variable-values'> + <title>Viewing Variable Values</title> + <para> + BitBake's <filename>-e</filename> option is used to display + variable values after parsing. + The following command displays the variable values after the + configuration files (i.e. <filename>local.conf</filename>, + <filename>bblayers.conf</filename>, + <filename>bitbake.conf</filename> and so forth) have been + parsed: + <literallayout class='monospaced'> + $ bitbake -e + </literallayout> + The following command displays variable values after a specific + recipe has been parsed. + The variables include those from the configuration as well: + <literallayout class='monospaced'> + $ bitbake -e recipename + </literallayout> + <note><para> + Each recipe has its own private set of variables (datastore). + Internally, after parsing the configuration, a copy of the + resulting datastore is made prior to parsing each recipe. + This copying implies that variables set in one recipe will + not be visible to other recipes.</para> + + <para>Likewise, each task within a recipe gets a private + datastore based on the recipe datastore, which means that + variables set within one task will not be visible to + other tasks.</para> + </note> + </para> + + <para> + In the output of <filename>bitbake -e</filename>, each variable is + preceded by a description of how the variable got its value, + including temporary values that were later overriden. + This description also includes variable flags (varflags) set on + the variable. + The output can be very helpful during debugging. + </para> + + <para> + Variables that are exported to the environment are preceded by + <filename>export</filename> in the output of + <filename>bitbake -e</filename>. + See the following example: + <literallayout class='monospaced'> + export CC="i586-poky-linux-gcc -m32 -march=i586 --sysroot=/home/ulf/poky/build/tmp/sysroots/qemux86" + </literallayout> + </para> + + <para> + In addition to variable values, the output of the + <filename>bitbake -e</filename> and + <filename>bitbake -e</filename> <replaceable>recipe</replaceable> + commands includes the following information: + <itemizedlist> + <listitem><para> + The output starts with a tree listing all configuration + files and classes included globally, recursively listing + the files they include or inherit in turn. + Much of the behavior of the OpenEmbedded build system + (including the behavior of the + <link linkend='normal-recipe-build-tasks'>normal recipe build tasks</link>) + is implemented in the + <link linkend='ref-classes-base'><filename>base</filename></link> + class and the classes it inherits, rather than being built + into BitBake itself. + </para></listitem> + <listitem><para> + After the variable values, all functions appear in the + output. + For shell functions, variables referenced within the + function body are expanded. + If a function has been modified using overrides or + using override-style operators like + <filename>_append</filename> and + <filename>_prepend</filename>, then the final assembled + function body appears in the output. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='viewing-package-information-with-oe-pkgdata-util'> + <title>Viewing Package Information with <filename>oe-pkgdata-util</filename></title> + + <para> + You can use the <filename>oe-pkgdata-util</filename> command-line + utility to query + <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link> + and display various package-related information. + When you use the utility, you must use it to view information + on packages that have already been built. + </para> + + <para> + Following are a few of the available + <filename>oe-pkgdata-util</filename> subcommands. + <note> + You can use the standard * and ? globbing wildcards as part of + package names and paths. + </note> + <itemizedlist> + <listitem><para> + <filename>oe-pkgdata-util list-pkgs [</filename><replaceable>pattern</replaceable><filename>]</filename>: + Lists all packages that have been built, optionally + limiting the match to packages that match + <replaceable>pattern</replaceable>. + </para></listitem> + <listitem><para> + <filename>oe-pkgdata-util list-pkg-files </filename><replaceable>package</replaceable><filename> ...</filename>: + Lists the files and directories contained in the given + packages. + <note> + <para> + A different way to view the contents of a package is + to look at the + <filename>${</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link><filename>}/packages-split</filename> + directory of the recipe that generates the + package. + This directory is created by the + <link linkend='ref-tasks-package'><filename>do_package</filename></link> + task and has one subdirectory for each package the + recipe generates, which contains the files stored in + that package.</para> + <para> + If you want to inspect the + <filename>${WORKDIR}/packages-split</filename> + directory, make sure that + <link linkend='ref-classes-rm-work'><filename>rm_work</filename></link> + is not enabled when you build the recipe. + </para> + </note> + </para></listitem> + <listitem><para> + <filename>oe-pkgdata-util find-path </filename><replaceable>path</replaceable><filename> ...</filename>: + Lists the names of the packages that contain the given + paths. + For example, the following tells us that + <filename>/usr/share/man/man1/make.1</filename> + is contained in the <filename>make-doc</filename> + package: + <literallayout class='monospaced'> + $ oe-pkgdata-util find-path /usr/share/man/man1/make.1 + make-doc: /usr/share/man/man1/make.1 + </literallayout> + </para></listitem> + <listitem><para> + <filename>oe-pkgdata-util lookup-recipe </filename><replaceable>package</replaceable><filename> ...</filename>: + Lists the name of the recipes that + produce the given packages. + </para></listitem> + </itemizedlist> + </para> - <para>The log file for shell tasks is available in - <filename>${WORKDIR}/temp/log.do_<replaceable>taskname</replaceable>.pid</filename>. - For example, the <filename>do_compile</filename> task for the QEMU minimal image for the x86 - machine (<filename>qemux86</filename>) might be - <filename>tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/temp/log.do_compile.20830</filename>. - To see what - <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink> - runs to generate that log, look at the corresponding - <filename>run.do_<replaceable>taskname</replaceable>.pid</filename> file located in the same directory. + <para> + For more information on the <filename>oe-pkgdata-util</filename> + command, use the help facility: + <literallayout class='monospaced'> + $ oe-pkgdata-util ‐‐help + $ oe-pkgdata-util <replaceable>subcommand</replaceable> --help + </literallayout> </para> + </section> + + <section id='usingpoky-viewing-dependencies-between-recipes-and-tasks'> + <title>Viewing Dependencies Between Recipes and Tasks</title> <para> - Presently, the output from Python tasks is sent directly to the console. + Sometimes it can be hard to see why BitBake wants to build other + recipes before the one you have specified. + Dependency information can help you understand why a recipe is + built. + </para> + + <para> + To generate dependency information for a recipe, run the following + command: + <literallayout class='monospaced'> + $ bitbake -g <replaceable>recipename</replaceable> + </literallayout> + This command writes the following files in the current directory: + <itemizedlist> + <listitem><para> + <filename>pn-buildlist</filename>: A list of + recipes/targets involved in building + <replaceable>recipename</replaceable>. + "Involved" here means that at least one task from the + recipe needs to run when building + <replaceable>recipename</replaceable> from scratch. + Targets that are in + <link linkend='var-ASSUME_PROVIDED'><filename>ASSUME_PROVIDED</filename></link> + 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> + </itemizedlist> + </para> + + <para> + The graphs are in + <ulink url='https://en.wikipedia.org/wiki/DOT_%28graph_description_language%29'>DOT</ulink> + format and can be converted to images (e.g. using the + <filename>dot</filename> tool from + <ulink url='http://www.graphviz.org/'>Graphviz</ulink>). + <note><title>Notes</title> + <itemizedlist> + <listitem><para> + DOT files use a plain text format. + The graphs generated using the + <filename>bitbake -g</filename> command are often so + large as to be difficult to read without special + pruning (e.g. with Bitbake's + <filename>-I</filename> option) and processing. + Despite the form and size of the graphs, the + corresponding <filename>.dot</filename> files can still + be possible to read and provide useful information. + </para> + + <para>As an example, the + <filename>task-depends.dot</filename> file contains + lines such as the following: + <literallayout class='monospaced'> + "libxslt.do_configure" -> "libxml2.do_populate_sysroot" + </literallayout> + The above example line reveals that the + <link linkend='ref-tasks-configure'><filename>do_configure</filename></link> + task in <filename>libxslt</filename> depends on the + <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link> + task in <filename>libxml2</filename>, which is a normal + <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link> + dependency between the two recipes. + </para></listitem> + <listitem><para> + For an example of how <filename>.dot</filename> files + can be processed, see the + <filename>scripts/contrib/graph-tool</filename> Python + script, which finds and displays paths between graph + nodes. + </para></listitem> + </itemizedlist> + </note> + </para> + + <para> + 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> + </literallayout> + This command displays a GUI window from which you can view + build-time and runtime dependencies for the recipes involved in + building <replaceable>recipename</replaceable>. + </para> + </section> + + <section id='usingpoky-viewing-task-variable-dependencies'> + <title>Viewing Task Variable Dependencies</title> + + <para> + As mentioned in the + "<ulink url='&YOCTO_DOCS_BB_URL;#checksums'>Checksums (Signatures)</ulink>" + section of the BitBake User Manual, BitBake tries to automatically + determine what variables a task depends on so that it can rerun + the task if any values of the variables change. + This determination is usually reliable. + However, if you do things like construct variable names at runtime, + then you might have to manually declare dependencies on those + variables using <filename>vardeps</filename> as described in the + "<ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'>Variable Flags</ulink>" + section of the BitBake User Manual. + </para> + + <para> + If you are unsure whether a variable dependency is being picked up + automatically for a given task, you can list the variable + dependencies BitBake has determined by doing the following: + <orderedlist> + <listitem><para> + Build the recipe containing the task: + <literallayout class='monospaced'> + $ bitbake <replaceable>recipename</replaceable> + </literallayout> + </para></listitem> + <listitem><para> + Inside the + <link linkend='var-STAMPS_DIR'><filename>STAMPS_DIR</filename></link> + directory, find the signature data + (<filename>sigdata</filename>) file that corresponds to the + task. + The <filename>sigdata</filename> files contain a pickled + Python database of all the metadata that went into creating + the input checksum for the task. + As an example, for the + <link linkend='ref-tasks-fetch'><filename>do_fetch</filename></link> + task of the <filename>db</filename> recipe, the + <filename>sigdata</filename> file might be found in the + following location: + <literallayout class='monospaced'> + ${BUILDDIR}/tmp/stamps/i586-poky-linux/db/6.0.30-r1.do_fetch.sigdata.7c048c18222b16ff0bcee2000ef648b1 + </literallayout> + For tasks that are accelerated through the shared state + (<link linkend='shared-state-cache'>sstate</link>) + cache, an additional <filename>siginfo</filename> file is + written into + <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link> + along with the cached task output. + The <filename>siginfo</filename> files contain exactly the + same information as <filename>sigdata</filename> files. + </para></listitem> + <listitem><para> + Run <filename>bitbake-dumpsig</filename> on the + <filename>sigdata</filename> or + <filename>siginfo</filename> file. + Here is an example: + <literallayout class='monospaced'> + $ bitbake-dumpsig ${BUILDDIR}/tmp/stamps/i586-poky-linux/db/6.0.30-r1.do_fetch.sigdata.7c048c18222b16ff0bcee2000ef648b1 + </literallayout> + In the output of the above command, you will find a line + like the following, which lists all the (inferred) variable + dependencies for the task. + This list also includes indirect dependencies from + variables depending on other variables, recursively. + <literallayout class='monospaced'> + Task dependencies: ['PV', 'SRCREV', 'SRC_URI', 'SRC_URI[md5sum]', 'SRC_URI[sha256sum]', 'base_do_fetch'] + </literallayout> + <note> + Functions (e.g. <filename>base_do_fetch</filename>) + also count as variable dependencies. + These functions in turn depend on the variables they + reference. + </note> + The output of <filename>bitbake-dumpsig</filename> also includes + the value each variable had, a list of dependencies for each + variable, and + <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_HASHBASE_WHITELIST'><filename>BB_HASHBASE_WHITELIST</filename></ulink> + information. + </para></listitem> + </orderedlist> + </para> + + <para> + There is also a <filename>bitbake-diffsigs</filename> command for + comparing two <filename>siginfo</filename> or + <filename>sigdata</filename> files. + This command can be helpful when trying to figure out what changed + between two versions of a task. + If you call <filename>bitbake-diffsigs</filename> with just one + file, the command behaves like + <filename>bitbake-dumpsig</filename>. + </para> + + <para> + You can also use BitBake to dump out the signature construction + information without executing tasks by using either of the + following BitBake command-line options: + <literallayout class='monospaced'> + ‐‐dump-signatures=<replaceable>SIGNATURE_HANDLER</replaceable> + -S <replaceable>SIGNATURE_HANDLER</replaceable> + </literallayout> + <note> + Two common values for + <replaceable>SIGNATURE_HANDLER</replaceable> are "none" and + "printdiff", which dump only the signature or compare the + dumped signature with the cached one, respectively. + </note> + Using BitBake with either of these options causes BitBake to dump + out <filename>sigdata</filename> files in the + <filename>stamps</filename> directory for every task it would have + executed instead of building the specified target package. </para> </section> @@ -187,7 +584,7 @@ <title>Running Specific Tasks</title> <para> - Any given package consists of a set of tasks. + Any given recipe consists of a set of tasks. The standard BitBake behavior in most cases is: <filename>do_fetch</filename>, <filename>do_unpack</filename>, @@ -209,15 +606,39 @@ </para> <para> - If you wish to rerun a task, use the <filename>-f</filename> force - option. - For example, the following sequence forces recompilation after - changing files in the work directory. + The <filename>-c</filename> option respects task dependencies, + which means that all other tasks (including tasks from other + recipes) that the specified task depends on will be run before the + task. + Even when you manually specify a task to run with + <filename>-c</filename>, BitBake will only run the task if it + considers it "out of date". + See the + "<link linkend='stamp-files-and-the-rerunning-of-tasks'>Stamp Files and the Rerunning of Tasks</link>" + section for how BitBake determines whether a task is "out of date". + </para> + + <para> + If you want to force an up-to-date task to be rerun (e.g. + because you made manual modifications to the recipe's + <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link> + that you want to try out), then you can use the + <filename>-f</filename> option. + <note> + The reason <filename>-f</filename> is never required when + running the + <link linkend='ref-tasks-devshell'><filename>do_devshell</filename></link> + task is because the + <filename>[</filename><ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>nostamp</filename></ulink><filename>]</filename> + variable flag is already set for the task. + </note> + The following example shows one way you can use the + <filename>-f</filename> option: <literallayout class='monospaced'> $ bitbake matchbox-desktop . . - <replaceable>make some changes to the source code in the work directory</replaceable> + make some changes to the source code in the work directory . . $ bitbake matchbox-desktop -c compile -f @@ -236,6 +657,50 @@ </para> <para> + Another, shorter way to rerun a task and all + <link linkend='normal-recipe-build-tasks'>normal recipe build tasks</link> + that depend on it is to use the <filename>-C</filename> + option. + <note> + This option is upper-cased and is separate from the + <filename>-c</filename> option, which is lower-cased. + </note> + Using this option invalidates the given task and then runs the + <link linkend='ref-tasks-build'><filename>do_build</filename></link> + task, which is the default task if no task is given, and the + tasks on which it depends. + You could replace the final two commands in the previous example + with the following single command: + <literallayout class='monospaced'> + $ bitbake matchbox-desktop -C compile + </literallayout> + Internally, the <filename>-f</filename> and + <filename>-C</filename> options work by tainting (modifying) the + input checksum of the specified task. + This tainting indirectly causes the task and its + dependent tasks to be rerun through the normal task dependency + mechanisms. + <note> + BitBake explicitly keeps track of which tasks have been + tainted in this fashion, and will print warnings such as the + following for builds involving such tasks: + <literallayout class='monospaced'> + WARNING: /home/ulf/poky/meta/recipes-sato/matchbox-desktop/matchbox-desktop_2.1.bb.do_compile is tainted from a forced run + </literallayout> + The purpose of the warning is to let you know that the work + directory and build output might not be in the clean state they + would be in for a "normal" build, depending on what actions + you took. + To get rid of such warnings, you can remove the work directory + and rebuild the recipe, as follows: + <literallayout class='monospaced'> + $ bitbake matchbox-desktop -c clean + $ bitbake matchbox-desktop + </literallayout> + </note> + </para> + + <para> You can view a list of tasks in a given package by running the <filename>do_listtasks</filename> task as follows: <literallayout class='monospaced'> @@ -246,24 +711,77 @@ </para> </section> - <section id='usingpoky-debugging-dependencies'> - <title>Dependency Graphs</title> + <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> - Sometimes it can be hard to see why BitBake wants to build - other packages before building a given package you have specified. - The <filename>bitbake -g <replaceable>targetname</replaceable></filename> command - creates the <filename>pn-buildlist</filename>, - <filename>pn-depends.dot</filename>, - <filename>package-depends.dot</filename>, and - <filename>task-depends.dot</filename> files in the current - directory. - These files show what will be built and the package and task - dependencies, which are useful for debugging problems. - You can use the - <filename>bitbake -g -u depexp <replaceable>targetname</replaceable></filename> - command to display the results in a more human-readable form. + 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'> @@ -336,48 +854,76 @@ </para> </section> - <section id='usingpoky-debugging-variables'> - <title>Variables</title> - <para> - You can use the <filename>-e</filename> BitBake option to - display the parsing environment for a configuration. - The following displays the general parsing environment: - <literallayout class='monospaced'> - $ bitbake -e - </literallayout> - This next example shows the parsing environment for a specific - recipe: - <literallayout class='monospaced'> - $ bitbake -e <replaceable>recipename</replaceable> - </literallayout> - </para> - </section> - <section id='recipe-logging-mechanisms'> <title>Recipe Logging Mechanisms</title> <para> - Best practices exist while writing recipes that both log build progress and - act on build conditions such as warnings and errors. - Both Python and Bash language bindings exist for the logging mechanism: + The Yocto Project provides several logging functions for producing + debugging output and reporting errors and warnings. + For Python functions, the following logging functions exist. + All of these functions log to + <filename>${T}/log.do_</filename><replaceable>task</replaceable>, + and can also log to standard output (stdout) with the right + settings: <itemizedlist> - <listitem><para><emphasis>Python:</emphasis> For Python functions, BitBake - supports several loglevels: <filename>bb.fatal</filename>, - <filename>bb.error</filename>, <filename>bb.warn</filename>, - <filename>bb.note</filename>, <filename>bb.plain</filename>, - and <filename>bb.debug</filename>.</para></listitem> - <listitem><para><emphasis>Bash:</emphasis> For Bash functions, the same set - of loglevels exist and are accessed with a similar syntax: - <filename>bbfatal</filename>, <filename>bberror</filename>, - <filename>bbwarn</filename>, <filename>bbnote</filename>, - <filename>bbplain</filename>, and <filename>bbdebug</filename>.</para></listitem> + <listitem><para> + <filename>bb.plain(</filename><replaceable>msg</replaceable><filename>)</filename>: + Writes <replaceable>msg</replaceable> as is to the log while + also logging to stdout. + </para></listitem> + <listitem><para> + <filename>bb.note(</filename><replaceable>msg</replaceable><filename>)</filename>: + Writes "NOTE: <replaceable>msg</replaceable>" to the log. + Also logs to stdout if BitBake is called with "-v". + </para></listitem> + <listitem><para> + <filename>bb.debug(</filename><replaceable>level</replaceable><filename>, </filename><replaceable>msg</replaceable><filename>)</filename>: + Writes "DEBUG: <replaceable>msg</replaceable>" to the log. + Also logs to stdout if the log level is greater than or + equal to <replaceable>level</replaceable>. + See the + "<ulink url='&YOCTO_DOCS_BB_URL;#usage-and-syntax'>-D</ulink>" + option in the BitBake User Manual for more information. + </para></listitem> + <listitem><para> + <filename>bb.warn(</filename><replaceable>msg</replaceable><filename>)</filename>: + Writes "WARNING: <replaceable>msg</replaceable>" to the log + while also logging to stdout. + </para></listitem> + <listitem><para> + <filename>bb.error(</filename><replaceable>msg</replaceable><filename>)</filename>: + Writes "ERROR: <replaceable>msg</replaceable>" to the log + while also logging to stdout. + <note> + Calling this function does not cause the task to fail. + </note> + </para></listitem> + <listitem><para> + <filename>bb.fatal(</filename><replaceable>msg</replaceable><filename>)</filename>: + This logging function is similar to + <filename>bb.error(</filename><replaceable>msg</replaceable><filename>)</filename> + but also causes the calling task to fail. + <note> + <filename>bb.fatal()</filename> raises an exception, + which means you do not need to put a "return" + statement after the function. + </note> + </para></listitem> </itemizedlist> </para> <para> - For guidance on how logging is handled in both Python and Bash recipes, see the - <filename>logging.bbclass</filename> file in the + The same logging functions are also available in shell functions, + under the names + <filename>bbplain</filename>, <filename>bbnote</filename>, + <filename>bbdebug</filename>, <filename>bbwarn</filename>, + <filename>bberror</filename>, and <filename>bbfatal</filename>. + The + <link linkend='ref-classes-logging'><filename>logging</filename></link> + class implements these functions. + See that class in the <filename>meta/classes</filename> folder of the - <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> + for information. </para> <section id='logging-with-python'> @@ -456,18 +1002,92 @@ <para> Here are some other tips that you might find useful: <itemizedlist> - <listitem><para>When adding new packages, it is worth watching for - undesirable items making their way into compiler command lines. - For example, you do not want references to local system files like - <filename>/usr/lib/</filename> or <filename>/usr/include/</filename>. + <listitem><para> + When adding new packages, it is worth watching for + undesirable items making their way into compiler command + lines. + For example, you do not want references to local system + files like + <filename>/usr/lib/</filename> or + <filename>/usr/include/</filename>. </para></listitem> - <listitem><para>If you want to remove the <filename>psplash</filename> + <listitem><para> + If you want to remove the <filename>psplash</filename> boot splashscreen, - add <filename>psplash=false</filename> to the kernel command line. + add <filename>psplash=false</filename> to the kernel + command line. Doing so prevents <filename>psplash</filename> from loading and thus allows you to see the console. It is also possible to switch out of the splashscreen by - switching the virtual console (e.g. Fn+Left or Fn+Right on a Zaurus). + switching the virtual console (e.g. Fn+Left or Fn+Right + on a Zaurus). + </para></listitem> + <listitem><para> + Removing + <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> + (usually <filename>tmp/</filename>, within the + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>) + can often fix temporary build issues. + Removing <filename>TMPDIR</filename> is usually a + relatively cheap operation, because task output will be + cached in + <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link> + (usually <filename>sstate-cache/</filename>, which is + also in the Build Directory). + <note> + Removing <filename>TMPDIR</filename> might be a + workaround rather than a fix. + Consequently, trying to determine the underlying cause + of an issue before removing the directory is a good + idea. + </note> + </para></listitem> + <listitem><para> + Understanding how a feature is used in practice within + existing recipes can be very helpful. + It is recommended that you configure some method that + allows you to quickly search through files.</para> + + <para>Using GNU Grep, you can use the following shell + function to recursively search through common + recipe-related files, skipping binary files, + <filename>.git</filename> directories, and the + Build Directory (assuming its name starts with + "build"): + <literallayout class='monospaced'> + g() { + grep -Ir \ + --exclude-dir=.git \ + --exclude-dir='build*' \ + --include='*.bb*' \ + --include='*.inc*' \ + --include='*.conf*' \ + --include='*.py*' \ + "$@" + } + </literallayout> + Following are some usage examples: + <literallayout class='monospaced'> + $ g FOO # Search recursively for "FOO" + $ g -i foo # Search recursively for "foo", ignoring case + $ g -w FOO # Search recursively for "FOO" as a word, ignoring e.g. "FOOBAR" + </literallayout> + If figuring out how some feature works requires a lot of + searching, it might indicate that the documentation should + be extended or improved. + In such cases, consider filing a documentation bug using + the Yocto Project implementation of + <ulink url='https://bugzilla.yoctoproject.org/'>Bugzilla</ulink>. + For general information on how to submit a bug against + the Yocto Project, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#tracking-bugs'>Tracking Bugs</ulink>" + section in the Yocto Project Development Manual. + <note> + The manuals might not be the right place to document + variables that are purely internal and have a limited + scope (e.g. internal variables used to implement a + single <filename>.bbclass</filename> file). + </note> </para></listitem> </itemizedlist> </para> @@ -951,6 +1571,19 @@ * PR changed from "r0" to "r1" * PV changed from "0.1.10" to "0.1.12" </literallayout> + <note> + The <filename>buildhistory-diff</filename> tool requires + the <filename>GitPython</filename> package. + Be sure to install it using Pip3 as follows: + <literallayout class='monospaced'> + $ pip3 install GitPython --user + </literallayout> + Alternatively, you can install + <filename>python3-git</filename> using the appropriate + distribution package manager (e.g. + <filename>apt-get</filename>, <filename>dnf</filename>, or + <filename>zipper</filename>). + </note> </para> <para> |
