diff options
Diffstat (limited to 'documentation')
53 files changed, 6498 insertions, 1735 deletions
diff --git a/documentation/Makefile b/documentation/Makefile index 3bc9a213ee..78a2e8e155 100644 --- a/documentation/Makefile +++ b/documentation/Makefile @@ -1,22 +1,22 @@ # This is a single Makefile to handle all generated Yocto Project documents. -# The Makefile needs to live in the documents directory and all figures used -# in any manuals must be .PNG files and live in the individual book's figures -# directory as well as in the figures directory for the mega-manual. +# The Makefile needs to live in the documentation/ directory and all figures +# used in any manuals must be .PNG files and live in the individual book's +# figures/ directory as well as in the figures/ directory for the mega-manual. # Note that the figures for the Yocto Project Development Manual # differ depending on the BRANCH being built. # # The Makefile has these targets: # -# pdf: generates a PDF version of a manual. Not valid for the Quick Start -# or the mega-manual (single, large HTML file comprised of all -# Yocto Project manuals). -# html: generates an HTML version of a manual. -# eclipse: generates an HTML version of a manual that can be used as -# eclipse help (including necessary metadata files). -# tarball: creates a tarball for the doc files. -# validate: validates -# publish: pushes generated files to the Yocto Project website -# clean: removes files +# pdf: generates a PDF version of a manual. Not valid for the +# Quick Start or the mega-manual (single, large HTML file +# comprised of all Yocto Project manuals). +# html: generates an HTML version of a manual. +# eclipse: generates an HTML version of a manual that can be used as +# eclipse help (including necessary metadata files). +# tarball: creates a tarball for the doc files. +# validate: validates +# publish: pushes generated files to the Yocto Project website +# clean: removes files # # The Makefile generates an HTML and PDF version of every document except the # Yocto Project Quick Start and the single, HTML mega-manual, which is comprised @@ -33,7 +33,7 @@ # To build a manual, you must invoke Makefile with the DOC argument. If you # are going to publish the manual, then you must invoke Makefile with both the # DOC and the VER argument. Furthermore, if you are building or publishing -# the edison or denzil versions of the Yocto Poject Development Manual or +# the edison or denzil versions of the Yocto Project Development Manual or # the mega-manual, you must also use the BRANCH argument. # # Examples: @@ -45,18 +45,19 @@ # make DOC=mega-manual BRANCH=denzil # # The first example generates the HTML and PDF versions of the BSP Guide. -# The second example generates the HTML version only of the Quick Start. Note that -# the Quick Start only has an HTML version available. The third example generates -# both the PDF and HTML versions of the Yocto Project Reference Manual. The -# fourth example generates both the PDF and HTML 'edison' versions of the YP -# Development Manual. The last exmample generates the HTML version of the -# mega-manual and uses the 'denzil' branch when choosing figures for the +# The second example generates the HTML version only of the Quick Start. Note +# that the Quick Start only has an HTML version available. The third example +# generates just the PDF version of the Yocto Project Reference Manual. +# The fourth example generates both the PDF and HTML 'edison' versions +# of the YP Development Manual. The last example generates the HTML version +# of the mega-manual and uses the 'denzil' branch when choosing figures for the # tarball of figures. Any example that does not use the BRANCH argument # builds the current version of the manual set. # # Use the publish target to push the generated manuals to the Yocto Project -# website. All files needed for the manual's HTML form are pushed as well as the -# PDF version (if applicable). +# website. All files needed for the manual's HTML form are pushed as well as +# the PDF version (if applicable). +# # Examples: # # make publish DOC=bsp-guide VER=1.3 @@ -64,11 +65,11 @@ # make publish DOC=dev-manual VER=1.1.1 BRANCH=edison # make publish DOC=dev-manual VER=1.2 BRANCH=denzil # -# The first example publishes the 1.3 version of both the PDF and HTML versions of -# the BSP Guide. The second example publishes the 1.3 version of both the PDF and -# HTML versions of the ADT Manual. The third example publishes the PDF and HTML -# 'edison' versions of the YP Development Manual. The fourth example publishes -# the PDF and HTML 'denzil' versions of the YP Development Manual. +# The first example publishes the 1.3 version of both the PDF and HTML versions +# of the BSP Guide. The second example publishes the 1.3 version of both the +# PDF and HTML versions of the ADT Manual. The third example publishes the PDF +# and HTML 'edison' versions of the YP Development Manual. The fourth example +# publishes the PDF and HTML 'denzil' versions of the YP Development Manual. # ifeq ($(DOC),bsp-guide) @@ -86,16 +87,18 @@ ifeq ($(DOC),dev-manual) XSLTOPTS = --xinclude ALLPREQ = html pdf eclipse tarball # -# Note that the tarfile might produce the "Cannot stat: No such file or directory" error -# message for .PNG files that are not present when building a particular branch. The -# list of files is all-inclusive for all branches. Note, if you don't provide a BRANCH -# option, it defaults to the latest stuff. This would be appropriate for "master" branch. +# Note that the tarfile might produce the "Cannot stat: No such file or +# directory" error message for .PNG files that are not present when building +# a particular branch. The list of files is all-inclusive for all branches. +# Note, if you don't provide a BRANCH option, it defaults to the latest stuff. +# This would be appropriate for "master" branch. # ifeq ($(BRANCH),edison) TARFILES = dev-style.css dev-manual.html dev-manual.pdf \ - figures/app-dev-flow.png figures/bsp-dev-flow.png figures/dev-title.png \ - figures/git-workflow.png figures/index-downloads.png figures/kernel-dev-flow.png \ + figures/app-dev-flow.png figures/bsp-dev-flow.png \ + figures/dev-title.png figures/git-workflow.png \ + figures/index-downloads.png figures/kernel-dev-flow.png \ figures/kernel-example-repos-edison.png \ figures/kernel-overview-1.png figures/kernel-overview-2.png \ figures/kernel-overview-3-edison.png \ @@ -103,8 +106,9 @@ TARFILES = dev-style.css dev-manual.html dev-manual.pdf \ figures/wip.png else ifeq ($(BRANCH),denzil) TARFILES = dev-style.css dev-manual.html dev-manual.pdf \ - figures/app-dev-flow.png figures/bsp-dev-flow.png figures/dev-title.png \ - figures/git-workflow.png figures/index-downloads.png figures/kernel-dev-flow.png \ + figures/app-dev-flow.png figures/bsp-dev-flow.png \ + figures/dev-title.png figures/git-workflow.png \ + figures/index-downloads.png figures/kernel-dev-flow.png \ figures/kernel-example-repos-denzil.png \ figures/kernel-overview-1.png figures/kernel-overview-2.png \ figures/kernel-overview-3-denzil.png \ @@ -112,10 +116,12 @@ TARFILES = dev-style.css dev-manual.html dev-manual.pdf \ figures/wip.png else TARFILES = dev-style.css dev-manual.html dev-manual.pdf \ - figures/app-dev-flow.png figures/bsp-dev-flow.png figures/dev-title.png \ - figures/git-workflow.png figures/index-downloads.png figures/kernel-dev-flow.png \ + figures/app-dev-flow.png figures/bsp-dev-flow.png \ + figures/dev-title.png figures/git-workflow.png \ + figures/index-downloads.png figures/kernel-dev-flow.png \ figures/kernel-overview-1.png figures/kernel-overview-2-generic.png \ - figures/source-repos.png figures/yp-download.png figures/recipe-workflow.png \ + figures/source-repos.png figures/yp-download.png \ + figures/recipe-workflow.png \ eclipse endif @@ -146,61 +152,82 @@ XSLTOPTS = --stringparam html.stylesheet mega-style.css \ ALLPREQ = html tarball ifeq ($(BRANCH),edison) -TARFILES = mega-manual.html mega-style.css figures/yocto-environment.png figures/building-an-image.png \ +TARFILES = mega-manual.html mega-style.css figures/yocto-environment.png \ + figures/building-an-image.png \ figures/using-a-pre-built-image.png \ figures/poky-title.png \ figures/adt-title.png figures/bsp-title.png \ figures/kernel-title.png figures/kernel-architecture-overview.png \ - figures/app-dev-flow.png figures/bsp-dev-flow.png figures/dev-title.png \ - figures/git-workflow.png figures/index-downloads.png figures/kernel-dev-flow.png \ + figures/app-dev-flow.png figures/bsp-dev-flow.png \ + figures/dev-title.png figures/git-workflow.png \ + figures/index-downloads.png figures/kernel-dev-flow.png \ figures/kernel-example-repos-edison.png \ figures/kernel-overview-1.png figures/kernel-overview-2.png \ figures/kernel-overview-3-edison.png \ figures/source-repos.png figures/yp-download.png \ figures/wip.png else ifeq ($(BRANCH),denzil) -TARFILES = mega-manual.html mega-style.css figures/yocto-environment.png figures/building-an-image.png \ +TARFILES = mega-manual.html mega-style.css figures/yocto-environment.png \ + figures/building-an-image.png \ figures/using-a-pre-built-image.png \ figures/poky-title.png \ figures/adt-title.png figures/bsp-title.png \ figures/kernel-title.png figures/kernel-architecture-overview.png \ - figures/app-dev-flow.png figures/bsp-dev-flow.png figures/dev-title.png \ - figures/git-workflow.png figures/index-downloads.png figures/kernel-dev-flow.png \ + figures/app-dev-flow.png figures/bsp-dev-flow.png \ + figures/dev-title.png figures/git-workflow.png \ + figures/index-downloads.png figures/kernel-dev-flow.png \ figures/kernel-example-repos-denzil.png \ figures/kernel-overview-1.png figures/kernel-overview-2.png \ figures/kernel-overview-3-denzil.png \ figures/source-repos.png figures/yp-download.png \ figures/wip.png else -TARFILES = mega-manual.html mega-style.css figures/yocto-environment.png figures/building-an-image.png \ +TARFILES = mega-manual.html mega-style.css figures/yocto-environment.png \ + figures/building-an-image.png \ figures/using-a-pre-built-image.png \ - figures/poky-title.png figures/buildhistory.png figures/buildhistory-web.png \ + figures/poky-title.png figures/buildhistory.png \ + figures/buildhistory-web.png \ figures/adt-title.png figures/bsp-title.png \ figures/kernel-dev-title.png figures/kernel-architecture-overview.png \ - figures/app-dev-flow.png figures/bsp-dev-flow.png figures/dev-title.png \ - figures/git-workflow.png figures/index-downloads.png figures/kernel-dev-flow.png \ + figures/app-dev-flow.png figures/bsp-dev-flow.png \ + figures/dev-title.png \ + figures/git-workflow.png figures/index-downloads.png \ + figures/kernel-dev-flow.png \ figures/kernel-overview-1.png figures/kernel-overview-2-generic.png \ figures/source-repos.png figures/yp-download.png \ figures/profile-title.png figures/kernelshark-all.png \ - figures/kernelshark-choose-events.png figures/kernelshark-i915-display.png \ + figures/kernelshark-choose-events.png \ + figures/kernelshark-i915-display.png \ figures/kernelshark-output-display.png figures/lttngmain0.png \ figures/oprofileui-busybox.png figures/oprofileui-copy-to-user.png \ figures/oprofileui-downloading.png figures/oprofileui-processes.png \ - figures/perf-probe-do_fork-profile.png figures/perf-report-cycles-u.png \ + figures/perf-probe-do_fork-profile.png \ + figures/perf-report-cycles-u.png \ figures/perf-systemwide.png figures/perf-systemwide-libc.png \ - figures/perf-wget-busybox-annotate-menu.png figures/perf-wget-busybox-annotate-udhcpc.png \ - figures/perf-wget-busybox-debuginfo.png figures/perf-wget-busybox-dso-zoom.png \ - figures/perf-wget-busybox-dso-zoom-menu.png figures/perf-wget-busybox-expanded-stripped.png \ - figures/perf-wget-flat-stripped.png figures/perf-wget-g-copy-from-user-expanded-stripped.png \ - figures/perf-wget-g-copy-to-user-expanded-debuginfo.png figures/perf-wget-g-copy-to-user-expanded-stripped.png \ - figures/perf-wget-g-copy-to-user-expanded-stripped-unresolved-hidden.png figures/pybootchartgui-linux-yocto.png \ - figures/pychart-linux-yocto-rpm.png figures/pychart-linux-yocto-rpm-nostrip.png \ + figures/perf-wget-busybox-annotate-menu.png \ + figures/perf-wget-busybox-annotate-udhcpc.png \ + figures/perf-wget-busybox-debuginfo.png \ + figures/perf-wget-busybox-dso-zoom.png \ + figures/perf-wget-busybox-dso-zoom-menu.png \ + figures/perf-wget-busybox-expanded-stripped.png \ + figures/perf-wget-flat-stripped.png \ + figures/perf-wget-g-copy-from-user-expanded-stripped.png \ + figures/perf-wget-g-copy-to-user-expanded-debuginfo.png \ + figures/perf-wget-g-copy-to-user-expanded-stripped.png \ + figures/perf-wget-g-copy-to-user-expanded-stripped-unresolved-hidden.png \ + figures/pybootchartgui-linux-yocto.png \ + figures/pychart-linux-yocto-rpm.png \ + figures/pychart-linux-yocto-rpm-nostrip.png \ figures/sched-wakeup-profile.png figures/sysprof-callers.png \ - figures/sysprof-copy-from-user.png figures/sysprof-copy-to-user.png figures/cross-development-toolchains.png \ - figures/yocto-environment-ref.png figures/user-configuration.png figures/source-input.png \ - figures/package-feeds.png figures/layer-input.png figures/images.png figures/sdk.png \ - figures/source-fetching.png figures/patching.png figures/configuration-compile-autoreconf.png \ - figures/analysis-for-package-splitting.png figures/image-generation.png \ + figures/sysprof-copy-from-user.png figures/sysprof-copy-to-user.png \ + figures/cross-development-toolchains.png \ + figures/yocto-environment-ref.png figures/user-configuration.png \ + figures/source-input.png figures/package-feeds.png \ + figures/layer-input.png figures/images.png figures/sdk.png \ + figures/source-fetching.png figures/patching.png \ + figures/configuration-compile-autoreconf.png \ + figures/analysis-for-package-splitting.png \ + figures/image-generation.png \ figures/sdk-generation.png figures/recipe-workflow.png endif @@ -243,19 +270,28 @@ XSLTOPTS = --xinclude ALLPREQ = html pdf eclipse tarball TARFILES = profile-manual.html profile-manual.pdf profile-manual-style.css \ figures/profile-title.png figures/kernelshark-all.png \ - figures/kernelshark-choose-events.png figures/kernelshark-i915-display.png \ + figures/kernelshark-choose-events.png \ + figures/kernelshark-i915-display.png \ figures/kernelshark-output-display.png figures/lttngmain0.png \ figures/oprofileui-busybox.png figures/oprofileui-copy-to-user.png \ figures/oprofileui-downloading.png figures/oprofileui-processes.png \ - figures/perf-probe-do_fork-profile.png figures/perf-report-cycles-u.png \ + figures/perf-probe-do_fork-profile.png \ + figures/perf-report-cycles-u.png \ figures/perf-systemwide.png figures/perf-systemwide-libc.png \ - figures/perf-wget-busybox-annotate-menu.png figures/perf-wget-busybox-annotate-udhcpc.png \ - figures/perf-wget-busybox-debuginfo.png figures/perf-wget-busybox-dso-zoom.png \ - figures/perf-wget-busybox-dso-zoom-menu.png figures/perf-wget-busybox-expanded-stripped.png \ - figures/perf-wget-flat-stripped.png figures/perf-wget-g-copy-from-user-expanded-stripped.png \ - figures/perf-wget-g-copy-to-user-expanded-debuginfo.png figures/perf-wget-g-copy-to-user-expanded-stripped.png \ - figures/perf-wget-g-copy-to-user-expanded-stripped-unresolved-hidden.png figures/pybootchartgui-linux-yocto.png \ - figures/pychart-linux-yocto-rpm.png figures/pychart-linux-yocto-rpm-nostrip.png \ + figures/perf-wget-busybox-annotate-menu.png \ + figures/perf-wget-busybox-annotate-udhcpc.png \ + figures/perf-wget-busybox-debuginfo.png \ + figures/perf-wget-busybox-dso-zoom.png \ + figures/perf-wget-busybox-dso-zoom-menu.png \ + figures/perf-wget-busybox-expanded-stripped.png \ + figures/perf-wget-flat-stripped.png \ + figures/perf-wget-g-copy-from-user-expanded-stripped.png \ + figures/perf-wget-g-copy-to-user-expanded-debuginfo.png \ + figures/perf-wget-g-copy-to-user-expanded-stripped.png \ + figures/perf-wget-g-copy-to-user-expanded-stripped-unresolved-hidden.png \ + figures/pybootchartgui-linux-yocto.png \ + figures/pychart-linux-yocto-rpm.png \ + figures/pychart-linux-yocto-rpm-nostrip.png \ figures/sched-wakeup-profile.png figures/sysprof-callers.png \ figures/sysprof-copy-from-user.png figures/sysprof-copy-to-user.png \ eclipse @@ -267,7 +303,8 @@ endif ifeq ($(DOC),kernel-dev) XSLTOPTS = --xinclude ALLPREQ = html pdf eclipse tarball -TARFILES = kernel-dev.html kernel-dev.pdf kernel-dev-style.css figures/kernel-dev-title.png \ +TARFILES = kernel-dev.html kernel-dev.pdf kernel-dev-style.css \ + figures/kernel-dev-title.png \ figures/kernel-architecture-overview.png \ eclipse MANUALS = $(DOC)/$(DOC).html $(DOC)/$(DOC).pdf $(DOC)/eclipse @@ -278,7 +315,7 @@ endif ## # These URI should be rewritten by your distribution's xml catalog to -# match your localy installed XSL stylesheets. +# match your locally installed XSL stylesheets. XSL_BASE_URI = http://docbook.sourceforge.net/release/xsl/current XSL_XHTML_URI = $(XSL_BASE_URI)/xhtml/docbook.xsl diff --git a/documentation/adt-manual/adt-command.xml b/documentation/adt-manual/adt-command.xml index 9aa25fad40..164b1efbff 100644 --- a/documentation/adt-manual/adt-command.xml +++ b/documentation/adt-manual/adt-command.xml @@ -177,7 +177,7 @@ Thus, the following command works: <literallayout class='monospaced'> $ ./configure --host=armv5te-poky-linux-gnueabi \ - --with-libtool-sysroot=<sysroot-dir> + --with-libtool-sysroot=<replaceable>sysroot-dir</replaceable> </literallayout> </para> @@ -186,13 +186,13 @@ cross-toolchain tools. <note> If the <filename>configure</filename> script results in problems recognizing the - <filename>--with-libtool-sysroot=<sysroot-dir></filename> option, + <filename>--with-libtool-sysroot=</filename><replaceable>sysroot-dir</replaceable> option, regenerate the script to enable the support by doing the following and then run the script again: <literallayout class='monospaced'> $ libtoolize --automake $ aclocal -I ${OECORE_NATIVE_SYSROOT}/usr/share/aclocal \ - [-I <dir_containing_your_project-specific_m4_macros>] + [-I <replaceable>dir_containing_your_project-specific_m4_macros</replaceable>] $ autoconf $ autoheader $ automake -a diff --git a/documentation/adt-manual/adt-manual-customization.xsl b/documentation/adt-manual/adt-manual-customization.xsl index e7892fdd26..f08087d93f 100644 --- a/documentation/adt-manual/adt-manual-customization.xsl +++ b/documentation/adt-manual/adt-manual-customization.xsl @@ -1,7 +1,7 @@ <?xml version='1.0'?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0"> - <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl" /> + <xsl:import href="http://docbook.sourceforge.net/release/xsl/1.76.1/xhtml/docbook.xsl" /> <xsl:include href="../template/permalinks.xsl"/> <xsl:include href="../template/section.title.xsl"/> diff --git a/documentation/adt-manual/adt-manual.xml b/documentation/adt-manual/adt-manual.xml index 31695b0387..5492c6ff09 100644 --- a/documentation/adt-manual/adt-manual.xml +++ b/documentation/adt-manual/adt-manual.xml @@ -78,9 +78,14 @@ </revision> <revision> <revnumber>1.7</revnumber> - <date>Fall of 2014</date> + <date>October 2014</date> <revremark>Released with the Yocto Project 1.7 Release.</revremark> </revision> + <revision> + <revnumber>1.8</revnumber> + <date>Sometime in 2015</date> + <revremark>Released with the Yocto Project 1.8 Release.</revremark> + </revision> </revhistory> <copyright> diff --git a/documentation/adt-manual/adt-package.xml b/documentation/adt-manual/adt-package.xml index da032eee5b..5c3196ea91 100644 --- a/documentation/adt-manual/adt-package.xml +++ b/documentation/adt-manual/adt-package.xml @@ -80,17 +80,17 @@ Next, source the environment setup script found in the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. Follow that by setting up the installation destination to point to your - sysroot as <filename><sysroot_dir></filename>. - Finally, have an OPKG configuration file <filename><conf_file></filename> + sysroot as <replaceable>sysroot_dir</replaceable>. + Finally, have an OPKG configuration file <replaceable>conf_file</replaceable> that corresponds to the <filename>opkg</filename> repository you have just created. The following command forms should now work: <literallayout class='monospaced'> - $ opkg-cl –f <conf_file> -o <sysroot_dir> update - $ opkg-cl –f <cconf_file> -o <sysroot_dir> \ + $ opkg-cl –f <replaceable>conf_file</replaceable> -o <replaceable>sysroot_dir</replaceable> update + $ opkg-cl –f <replaceable>cconf_file</replaceable> -o <replaceable>sysroot_dir</replaceable> \ --force-overwrite install libglade - $ opkg-cl –f <cconf_file> -o <sysroot_dir> \ + $ opkg-cl –f <replaceable>cconf_file</replaceable> -o <replaceable>sysroot_dir</replaceable> \ --force-overwrite install libglade-dbg - $ opkg-cl –f <conf_file> -o <sysroot_dir> \ + $ opkg-cl –f <replaceable>conf_file> -o </replaceable>sysroot_dir> \ --force-overwrite install libglade-dev </literallayout> </para> diff --git a/documentation/adt-manual/adt-prepare.xml b/documentation/adt-manual/adt-prepare.xml index 89ef09fb24..7faf39b9e2 100644 --- a/documentation/adt-manual/adt-prepare.xml +++ b/documentation/adt-manual/adt-prepare.xml @@ -183,20 +183,20 @@ Please make sure you understand the security implications of doing this. You might also have to modify your firewall settings to allow NFS booting to work.</note></para></listitem> - <listitem><para><filename>YOCTOADT_ROOTFS_<arch></filename>: The root + <listitem><para><filename>YOCTOADT_ROOTFS_</filename><replaceable>arch</replaceable>: The root filesystem images you want to download from the <filename>YOCTOADT_IPKG_REPO</filename> repository.</para></listitem> - <listitem><para><filename>YOCTOADT_TARGET_SYSROOT_IMAGE_<arch></filename>: The + <listitem><para><filename>YOCTOADT_TARGET_SYSROOT_IMAGE_</filename><replaceable>arch</replaceable>: The particular root filesystem used to extract and create the target sysroot. The value of this variable must have been specified with - <filename>YOCTOADT_ROOTFS_<arch></filename>. + <filename>YOCTOADT_ROOTFS_</filename><replaceable>arch</replaceable>. For example, if you downloaded both <filename>minimal</filename> and <filename>sato-sdk</filename> images by setting - <filename>YOCTOADT_ROOTFS_<arch></filename> - to "minimal sato-sdk", then <filename>YOCTOADT_ROOTFS_<arch></filename> + <filename>YOCTOADT_ROOTFS_</filename><replaceable>arch</replaceable> + to "minimal sato-sdk", then <filename>YOCTOADT_ROOTFS_</filename><replaceable>arch</replaceable> must be set to either "minimal" or "sato-sdk". </para></listitem> - <listitem><para><filename>YOCTOADT_TARGET_SYSROOT_LOC_<arch></filename>: The + <listitem><para><filename>YOCTOADT_TARGET_SYSROOT_LOC_</filename><replaceable>arch</replaceable>: The location on the development host where the target sysroot is created. </para></listitem> </itemizedlist> @@ -212,7 +212,7 @@ Once the installer begins to run, you are asked to enter the location for cross-toolchain installation. The default location is - <filename>/opt/poky/<release></filename>. + <filename>/opt/poky/</filename><replaceable>release</replaceable>. After either accepting the default location or selecting your own location, you are prompted to run the installation script interactively or in silent mode. @@ -230,7 +230,7 @@ <filename>adt-installer</filename> directory according to your installer configurations, and the target sysroot located according to the - <filename>YOCTOADT_TARGET_SYSROOT_LOC_<arch></filename> + <filename>YOCTOADT_TARGET_SYSROOT_LOC_</filename><replaceable>arch</replaceable> variable also in your configuration file. </para> </section> @@ -593,7 +593,7 @@ section. </para></listitem> <listitem><para> - Use <filename>bitbake <image> -c populate_sdk</filename>. + Use <filename>bitbake</filename> <replaceable>image</replaceable> <filename>-c populate_sdk</filename>. This method has significant advantages over the previous method because it results in a toolchain installer that contains the sysroot that matches your target root filesystem. diff --git a/documentation/bsp-guide/bsp-guide-customization.xsl b/documentation/bsp-guide/bsp-guide-customization.xsl index 53e50b1ba0..3da37be06f 100644 --- a/documentation/bsp-guide/bsp-guide-customization.xsl +++ b/documentation/bsp-guide/bsp-guide-customization.xsl @@ -1,7 +1,7 @@ <?xml version='1.0'?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0"> - <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl" /> + <xsl:import href="http://docbook.sourceforge.net/release/xsl/1.76.1/xhtml/docbook.xsl" /> <xsl:include href="../template/permalinks.xsl"/> <xsl:include href="../template/section.title.xsl"/> diff --git a/documentation/bsp-guide/bsp-guide.xml b/documentation/bsp-guide/bsp-guide.xml index af4ea64f43..0fd4728807 100644 --- a/documentation/bsp-guide/bsp-guide.xml +++ b/documentation/bsp-guide/bsp-guide.xml @@ -90,9 +90,14 @@ </revision> <revision> <revnumber>1.7</revnumber> - <date>Fall of 2014</date> + <date>October 2014</date> <revremark>Released with the Yocto Project 1.7 Release.</revremark> </revision> + <revision> + <revnumber>1.8</revnumber> + <date>Sometime in 2015</date> + <revremark>Released with the Yocto Project 1.8 Release.</revremark> + </revision> </revhistory> <copyright> diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml index fd143ede14..3cda0f6b70 100644 --- a/documentation/bsp-guide/bsp.xml +++ b/documentation/bsp-guide/bsp.xml @@ -35,12 +35,12 @@ Collectively, you can think of the base directory, its file structure, and the contents as a BSP Layer. Although not a strict requirement, layers in the Yocto Project use the - following well established naming convention: + following well-established naming convention: <literallayout class='monospaced'> - meta-<bsp_name> + meta-<replaceable>bsp_name</replaceable> </literallayout> The string "meta-" is prepended to the machine or platform name, which is - "bsp_name" in the above form. + <replaceable>bsp_name</replaceable> in the above form. </para> <para> @@ -50,7 +50,7 @@ <ulink url='&YOCTO_DOCS_DEV_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink> through a web interface at <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'></ulink>. - If you go to that interface you will find near the bottom of the list + If you go to that interface, you will find near the bottom of the list under "Yocto Metadata Layers" several BSP layers all of which are supported by the Yocto Project (e.g. <filename>meta-minnow</filename>, <filename>meta-raspberrypi</filename>, and @@ -58,7 +58,7 @@ Each of these layers is a repository unto itself and clicking on a layer reveals information that includes two links from which you can choose to set up a clone of the layer's repository on your local host system. - Here is an example that clones the Minnow Board BSP layer: + Here is an example that clones the MinnowBoard BSP layer: <literallayout class='monospaced'> $ git clone git://git.yoctoproject.org/meta-minnow </literallayout> @@ -72,7 +72,7 @@ </para> <para> - The layer's base directory (<filename>meta-<bsp_name></filename>) is the root + The layer's base directory (<filename>meta-<replaceable>bsp_name</replaceable></filename>) is the root of the BSP Layer. This root is what you add to the <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink> @@ -115,8 +115,9 @@ <para> Some layers function as a layer to hold other BSP layers. - An example of this type of layer is the <filename>meta-intel</filename> layer. - The <filename>meta-intel</filename> layer contains many individual BSP layers. + An example of this type of layer is the <filename>meta-intel</filename> layer, + which contains a number of individual BSP sub-layers, as well as a directory + named <filename>common/</filename> full of common content across those layers. </para> <para> @@ -131,8 +132,8 @@ <title>Example Filesystem Layout</title> <para> - Providing a common form allows end-users to understand and become familiar - with the layout. + Defining a common BSP directory structure allows end-users to understand and + become familiar with that structure. A common format also encourages standardization of software support of hardware. </para> @@ -175,17 +176,17 @@ for specific BSPs could differ. <literallayout class='monospaced'> - meta-<bsp_name>/ - meta-<bsp_name>/<bsp_license_file> - meta-<bsp_name>/README - meta-<bsp_name>/README.sources - meta-<bsp_name>/binary/<bootable_images> - meta-<bsp_name>/conf/layer.conf - meta-<bsp_name>/conf/machine/*.conf - meta-<bsp_name>/recipes-bsp/* - meta-<bsp_name>/recipes-core/* - meta-<bsp_name>/recipes-graphics/* - meta-<bsp_name>/recipes-kernel/linux/linux-yocto_<kernel_rev>.bbappend + meta-<replaceable>bsp_name</replaceable>/ + meta-<replaceable>bsp_name</replaceable>/<replaceable>bsp_license_file</replaceable> + meta-<replaceable>bsp_name</replaceable>/README + meta-<replaceable>bsp_name</replaceable>/README.sources + meta-<replaceable>bsp_name</replaceable>/binary/<replaceable>bootable_images</replaceable> + meta-<replaceable>bsp_name</replaceable>/conf/layer.conf + meta-<replaceable>bsp_name</replaceable>/conf/machine/*.conf + meta-<replaceable>bsp_name</replaceable>/recipes-bsp/* + meta-<replaceable>bsp_name</replaceable>/recipes-core/* + meta-<replaceable>bsp_name</replaceable>/recipes-graphics/* + meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux/linux-yocto_<replaceable>kernel_rev</replaceable>.bbappend </literallayout> </para> @@ -200,28 +201,19 @@ meta-crownbay/conf/ meta-crownbay/conf/layer.conf meta-crownbay/conf/machine/ - meta-crownbay/conf/machine/crownbay.conf meta-crownbay/conf/machine/crownbay-noemgd.conf meta-crownbay/recipes-bsp/ meta-crownbay/recipes-bsp/formfactor/ meta-crownbay/recipes-bsp/formfactor/formfactor_0.0.bbappend meta-crownbay/recipes-bsp/formfactor/formfactor/ - meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay/ - meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay/machconfig meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay-noemgd/ meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay-noemgd/machconfig - meta-crownbay/recipes-graphics/ - meta-crownbay/recipes-graphics/xorg-xserver/ - meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend - meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/ - meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay/ - meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay/xorg.conf meta-crownbay/recipes-kernel/ + meta-crownbay/recipes-kernel/kmod + meta-crownbay/recipes-kernel/kmod/kmod_git.bbappend meta-crownbay/recipes-kernel/linux/ - meta-crownbay/recipes-kernel/linux/linux-yocto-dev.bbappend meta-crownbay/recipes-kernel/linux/linux-yocto-rt_3.10.bbappend meta-crownbay/recipes-kernel/linux/linux-yocto_3.10.bbappend - meta-crownbay/recipes-kernel/linux/linux-yocto_3.14.bbappend </literallayout> </para> @@ -235,7 +227,7 @@ <para> You can find these files in the BSP Layer at: <literallayout class='monospaced'> - meta-<bsp_name>/<bsp_license_file> + meta-<replaceable>bsp_name</replaceable>/<replaceable>bsp_license_file</replaceable> </literallayout> </para> @@ -257,7 +249,7 @@ <para> You can find this file in the BSP Layer at: <literallayout class='monospaced'> - meta-<bsp_name>/README + meta-<replaceable>bsp_name</replaceable>/README </literallayout> </para> @@ -281,7 +273,7 @@ <para> You can find this file in the BSP Layer at: <literallayout class='monospaced'> - meta-<bsp_name>/README.sources + meta-<replaceable>bsp_name</replaceable>/README.sources </literallayout> </para> @@ -300,7 +292,7 @@ <para> You can find these files in the BSP Layer at: <literallayout class='monospaced'> - meta-<bsp_name>/binary/<bootable_images> + meta-<replaceable>bsp_name</replaceable>/binary/<replaceable>bootable_images</replaceable> </literallayout> </para> @@ -316,7 +308,7 @@ <para> The exact types of binaries present are highly hardware-dependent. - However, a README file should be present in the BSP Layer that explains how to use + However, a <filename>README</filename> file should be present in the BSP Layer that explains how to use the kernels and images with the target hardware. If pre-built binaries are present, source code to meet licensing requirements must also exist in some form. @@ -328,7 +320,7 @@ <para> You can find this file in the BSP Layer at: <literallayout class='monospaced'> - meta-<bsp_name>/conf/layer.conf + meta-<replaceable>bsp_name</replaceable>/conf/layer.conf </literallayout> </para> @@ -338,9 +330,9 @@ contents of the layer, and contains information about how the build system should use it. Generally, a standard boilerplate file such as the following works. - In the following example, you would replace "<filename>bsp</filename>" and - "<filename>_bsp</filename>" with the actual name - of the BSP (i.e. <filename><bsp_name></filename> from the example template). + In the following example, you would replace "<replaceable>bsp</replaceable>" and + "<replaceable>_bsp</replaceable>" with the actual name + of the BSP (i.e. <replaceable>bsp_name</replaceable> from the example template). </para> <para> @@ -352,9 +344,11 @@ BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ ${LAYERDIR}/recipes-*/*/*.bbappend" - BBFILE_COLLECTIONS += "bsp" - BBFILE_PATTERN_bsp = "^${LAYERDIR}/" - BBFILE_PRIORITY_bsp = "6" + BBFILE_COLLECTIONS += "<replaceable>bsp</replaceable>" + BBFILE_PATTERN_<replaceable>bsp</replaceable> = "^${LAYERDIR}/" + BBFILE_PRIORITY_<replaceable>bsp</replaceable> = "6" + + LAYERDEPENDS_<replaceable>bsp</replaceable> = "intel" </literallayout> </para> @@ -362,9 +356,18 @@ To illustrate the string substitutions, here are the corresponding statements from the Crown Bay <filename>conf/layer.conf</filename> file: <literallayout class='monospaced'> + # We have a conf and classes directory, add to BBPATH + BBPATH .= ":${LAYERDIR}" + + # We have a recipes directory, add to BBFILES + BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ + ${LAYERDIR}/recipes-*/*/*.bbappend" + BBFILE_COLLECTIONS += "crownbay" - BBFILE_PATTERN_crownbay = "^${LAYERDIR}/" + BBFILE_PATTERN_crownbay := "^${LAYERDIR}/" BBFILE_PRIORITY_crownbay = "6" + + LAYERDEPENDS_crownbay = "intel" </literallayout> </para> @@ -381,7 +384,7 @@ <para> You can find these files in the BSP Layer at: <literallayout class='monospaced'> - meta-<bsp_name>/conf/machine/*.conf + meta-<replaceable>bsp_name</replaceable>/conf/machine/*.conf </literallayout> </para> @@ -426,12 +429,12 @@ <para> To use an include file, you simply include them in the machine configuration file. - For example, the Crown Bay BSP <filename>crownbay.conf</filename> contains the + For example, the Crown Bay BSP <filename>crownbay-noemgd.conf</filename> contains the following statements: <literallayout class='monospaced'> - require conf/machine/include/intel-core2-32-common.inc require conf/machine/include/meta-intel.inc - require conf/machine/include/meta-intel-emgd.inc + require conf/machine/include/intel-core2-32-common.inc + require conf/machine/include/intel-common-pkgarch.inc </literallayout> </para> </section> @@ -441,7 +444,7 @@ <para> You can find these files in the BSP Layer at: <literallayout class='monospaced'> - meta-<bsp_name>/recipes-bsp/* + meta-<replaceable>bsp_name</replaceable>/recipes-bsp/* </literallayout> </para> @@ -453,11 +456,10 @@ append file used to augment the recipe that starts the build. Furthermore, there are machine-specific settings used during the build that are defined by the <filename>machconfig</filename> file. - In the Crown Bay example, two <filename>machconfig</filename> files - exist: one that supports the Intel® Embedded Media and Graphics - Driver (Intel® EMGD) and one that does not: + In the Crown Bay example, the <filename>machconfig</filename> file + supports the Video Electronics Standards Association (VESA) graphics + driver: <literallayout class='monospaced'> - meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay/machconfig meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay-noemgd/machconfig meta-crownbay/recipes-bsp/formfactor/formfactor_0.0.bbappend </literallayout> @@ -478,7 +480,7 @@ <para> You can find these files in the BSP Layer at: <literallayout class='monospaced'> - meta-<bsp_name>/recipes-graphics/* + meta-<replaceable>bsp_name</replaceable>/recipes-graphics/* </literallayout> </para> @@ -486,13 +488,17 @@ This optional directory contains recipes for the BSP if it has special requirements for graphics support. All files that are needed for the BSP to support a display are kept here. - For example, the Crown Bay BSP's <filename>xorg.conf</filename> file - detects the graphics support needed (i.e. the Intel® Embedded Media - Graphics Driver (EMGD) or the Video Electronics Standards Association - (VESA) graphics): + For example, the <filename>meta-emenlow</filename> layer, which supports + the eMenlow platform consisting of the + <trademark class='registered'>Intel</trademark> + <trademark class='trade'>Atom</trademark> + Z5xx processor with the + <trademark class='registered'>Intel</trademark> + System Controller Hub US15W uses these files for supporting the Video + Electronics Standards Association (VESA) graphics: <literallayout class='monospaced'> - meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend - meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay/xorg.conf + meta-emenlow/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend + meta-emenlow/recipes-graphics/xorg-xserver/xserver-xf86-config/emenlow-noemgd/xorg.conf </literallayout> </para> </section> @@ -502,7 +508,7 @@ <para> You can find these files in the BSP Layer at: <literallayout class='monospaced'> - meta-<bsp_name>/recipes-kernel/linux/linux-yocto_*.bbappend + meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux/linux-yocto*.bbappend </literallayout> </para> @@ -515,13 +521,13 @@ at <filename>meta/recipes-kernel/linux</filename>. You can append your specific changes to the kernel recipe by using a similarly named append file, which is located in the BSP Layer (e.g. - the <filename>meta-<bsp_name>/recipes-kernel/linux</filename> directory). + the <filename>meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux</filename> directory). </para> <para> Suppose you are using the <filename>linux-yocto_3.10.bb</filename> recipe to build the kernel. In other words, you have selected the kernel in your - <filename><bsp_name>.conf</filename> file by adding these types + <replaceable>bsp_name</replaceable><filename>.conf</filename> file by adding these types of statements: <literallayout class='monospaced'> PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" @@ -530,7 +536,7 @@ <note> When the preferred provider is assumed by default, the <filename>PREFERRED_PROVIDER</filename> statement does not appear in the - <filename><bsp_name>.conf</filename> file. + <replaceable>bsp_name</replaceable><filename>.conf</filename> file. </note> You would use the <filename>linux-yocto_3.10.bbappend</filename> file to append specific BSP settings to the kernel, thus configuring the kernel for your particular BSP. @@ -549,26 +555,14 @@ FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" - COMPATIBLE_MACHINE_crownbay = "crownbay" - KMACHINE_crownbay = "crownbay" - KBRANCH_crownbay = "standard/crownbay" - KERNEL_FEATURES_append_crownbay = " features/drm-emgd/drm-emgd-1.18 cfg/vesafb" - COMPATIBLE_MACHINE_crownbay-noemgd = "crownbay-noemgd" KMACHINE_crownbay-noemgd = "crownbay" KBRANCH_crownbay-noemgd = "standard/crownbay" KERNEL_FEATURES_append_crownbay-noemgd = " cfg/vesafb" - LINUX_VERSION_crownbay = "3.10.35" - SRCREV_meta_crownbay = "b6e58b33dd427fe471f8827c83e311acdf4558a4" - SRCREV_machine_crownbay = "cee957655fe67826b2e827e2db41f156fa8f0cc4" - SRCREV_emgd_crownbay = "42d5e4548e8e79e094fa8697949eed4cf6af00a3" - - LINUX_VERSION_crownbay-noemgd = "3.10.35" - SRCREV_meta_crownbay-noemgd = "b6e58b33dd427fe471f8827c83e311acdf4558a4" - SRCREV_machine_crownbay-noemgd = "cee957655fe67826b2e827e2db41f156fa8f0cc4" - - SRC_URI_crownbay = "git://git.yoctoproject.org/linux-yocto-3.10.git;protocol=git;nocheckout=1;branch=${KBRANCH},${KMETA},emgd-1.18;name=machine,meta,emgd" + LINUX_VERSION_crownbay-noemgd = "3.10.55" + SRCREV_meta_crownbay-noemgd = "f79a00265eefbe2fffc2cdb03f67235497a9a87e" + SRCREV_machine_crownbay-noemgd = "3677ea7f9476458aa6dec440243de3a6fb1343a9" </literallayout> This append file contains statements used to support the Crown Bay BSP. The file defines machines using the @@ -584,14 +578,11 @@ The <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink> variable enables features specific to the kernel - (e.g. graphics support in this case). + (e.g. VESA graphics support in this case). The append file points to specific commits in the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> Git repository and the <filename>meta</filename> Git repository branches to identify the exact kernel needed to build the Crown Bay BSP. - Finally, the file includes the - <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> - statement to locate the source files. </para> <para> @@ -752,7 +743,7 @@ </para></listitem> <listitem><para><emphasis>License File:</emphasis> You must include a license file in the - <filename>meta-<bsp_name></filename> directory. + <filename>meta-<replaceable>bsp_name</replaceable></filename> directory. This license covers the BSP Metadata as a whole. You must specify which license to use since there is no default license if one is not specified. @@ -762,7 +753,7 @@ as an example.</para></listitem> <listitem><para><emphasis>README File:</emphasis> You must include a <filename>README</filename> file in the - <filename>meta-<bsp_name></filename> directory. + <filename>meta-<replaceable>bsp_name</replaceable></filename> directory. See the <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-intel/tree/meta-fri2/README'><filename>README</filename></ulink> file for the Fish River Island 2 BSP in the <filename>meta-fri2</filename> BSP layer @@ -804,7 +795,7 @@ </itemizedlist></para></listitem> <listitem><para><emphasis>README.sources File:</emphasis> You must include a <filename>README.sources</filename> in the - <filename>meta-<bsp_name></filename> directory. + <filename>meta-<replaceable>bsp_name</replaceable></filename> directory. This file specifies exactly where you can find the sources used to generate the binary images contained in the <filename>binary</filename> directory, if present. @@ -814,12 +805,13 @@ as an example.</para></listitem> <listitem><para><emphasis>Layer Configuration File:</emphasis> You must include a <filename>conf/layer.conf</filename> in the - <filename>meta-<bsp_name></filename> directory. - This file identifies the <filename>meta-<bsp_name></filename> + <filename>meta-<replaceable>bsp_name</replaceable></filename> directory. + This file identifies the <filename>meta-<replaceable>bsp_name</replaceable></filename> BSP layer as a layer to the build system.</para></listitem> <listitem><para><emphasis>Machine Configuration File:</emphasis> - You must include one or more <filename>conf/machine/<bsp_name>.conf</filename> - files in the <filename>meta-<bsp_name></filename> directory. + You must include one or more + <filename>conf/machine/<replaceable>bsp_name</replaceable>.conf</filename> + files in the <filename>meta-<replaceable>bsp_name</replaceable></filename> directory. These configuration files define machine targets that can be built using the BSP layer. Multiple machine configuration files define variations of machine @@ -866,7 +858,7 @@ filesystems meant to allow users to boot the BSP for evaluation purposes, you should put the images and artifacts within a <filename>binary/</filename> subdirectory located in the - <filename>meta-<bsp_name></filename> directory. + <filename>meta-<replaceable>bsp_name</replaceable></filename> directory. <note>If you do include a bootable image as part of the BSP and the image was built by software covered by the GPL or other open source licenses, it is your responsibility to understand @@ -910,8 +902,15 @@ <filename>recipes-bsp</filename>, <filename>recipes-graphics</filename>, <filename>recipes-core</filename>, and so forth). </para></listitem> - <listitem><para>Place the BSP-specific files in the directory named for - your machine inside the BSP layer. + <listitem><para>Place the BSP-specific files in the proper directory + inside the BSP layer. + How expansive the layer is affects where you must place these files. + For example, if your layer supports several different machine types, + you need to be sure your layer's directory structure includes hierarchy + that separates the files out according to machine. + If your layer does not support multiple machines, the layer would not + have that additional hierarchy and the files would obviously not be + able to reside in a machine-specific directory. </para></listitem> </itemizedlist> </para> @@ -920,7 +919,8 @@ Following is a specific example to help you better understand the process. Consider an example that customizes a recipe by adding a BSP-specific configuration file named <filename>interfaces</filename> to the - <filename>init-ifupdown_1.0.bb</filename> recipe for machine "xyz". + <filename>init-ifupdown_1.0.bb</filename> recipe for machine "xyz" where the + BSP layer also supports several other machines. Do the following: <orderedlist> <listitem><para>Edit the <filename>init-ifupdown_1.0.bbappend</filename> file so that it @@ -934,8 +934,17 @@ <listitem><para>Create and place the new <filename>interfaces</filename> configuration file in the BSP's layer here: <literallayout class='monospaced'> - meta-xyz/recipes-core/init-ifupdown/files/xyz/interfaces + meta-xyz/recipes-core/init-ifupdown/files/xyz-machine-one/interfaces </literallayout> + <note> + If the <filename>meta-xyz</filename> layer did not support + multiple machines, you would place the + <filename>interfaces</filename> configuration file in the + layer here: + <literallayout class='monospaced'> + meta-xyz/recipes-core/init-ifupdown/files/interfaces + </literallayout> + </note> The <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> variable in the append files extends the search path @@ -1100,7 +1109,7 @@ Consequently, to use the scripts, you must <filename>source</filename> the environment just as you would when invoking a build: <literallayout class='monospaced'> - $ source oe-init-build-env [build_dir] + $ source oe-init-build-env <replaceable>build_dir</replaceable> </literallayout> </para> @@ -1242,12 +1251,13 @@ <literallayout class='monospaced'> $ yocto-bsp list karch Architectures available: - powerpc - i386 - x86_64 - arm qemu + arm mips + x86_64 + i386 + powerpc + mips64 </literallayout> </para> @@ -1288,26 +1298,25 @@ 3) ARM (32-bit) 4) PowerPC (32-bit) 5) MIPS (32-bit) + 6) MIPS64 (64-bit) 3 - Would you like to use the default (3.10) kernel? (y/n) [default: y] y + Would you like to use the default (3.17) kernel? (y/n) [default: y] y Do you need a new machine branch for this BSP (the alternative is to re-use an existing branch)? [y/n] [default: y] - Getting branches from remote repo git://git.yoctoproject.org/linux-yocto-3.10.git... + Getting branches from remote repo git://git.yoctoproject.org/linux-yocto-3.17.git... Please choose a machine branch to base your new BSP branch on: [default: standard/base] 1) standard/arm-versatile-926ejs 2) standard/base 3) standard/beagleboard 4) standard/beaglebone 5) standard/ck - 6) standard/crownbay - 7) standard/edgerouter - 8) standard/emenlow - 9) standard/fri2 - 10) standard/fsl-mpc8315e-rdb - 11) standard/mti-malta32 - 12) standard/mti-malta64 + 6) standard/common-pc + 7) standard/crownbay + 8) standard/edgerouter + 9) standard/fsl-mpc8315e-rdb + 10) standard/mti-malta32 + 11) standard/mti-malta64 + 12) standard/qemuarm64 13) standard/qemuppc - 14) standard/routerstationpro - 15) standard/sys940x 1 Would you like SMP support? (y/n) [default: y] Does your BSP have a touchscreen? (y/n) [default: n] @@ -1322,7 +1331,7 @@ In the example, we use the ARM architecture. </para></listitem> <listitem><para>The script then prompts you for the kernel. - The default 3.14 kernel is acceptable. + The default 3.17 kernel is acceptable. So, the example accepts the default. If you enter 'n', the script prompts you to further enter the kernel you do want to use.</para></listitem> @@ -1351,7 +1360,7 @@ <listitem><para>By default, the script creates the new BSP Layer in the current working directory of the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>, - which is <filename>poky</filename> in this case. + (i.e. <filename>poky/build</filename>). </para></listitem> </orderedlist> </para> diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index 1e4f25d918..0085cefa81 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -71,6 +71,7 @@ you will see several layers: <filename>meta</filename>, <filename>meta-skeleton</filename>, + <filename>meta-selftest</filename>, <filename>meta-yocto</filename>, and <filename>meta-yocto-bsp</filename>. Each of these folders represents a distinct layer. @@ -151,7 +152,7 @@ BBFILE_COLLECTIONS += "yoctobsp" BBFILE_PATTERN_yoctobsp = "^${LAYERDIR}/" BBFILE_PRIORITY_yoctobsp = "5" - LAYERVERSION_yoctobsp = "2" + LAYERVERSION_yoctobsp = "3" </literallayout></para> <para>Here is an explanation of the example: <itemizedlist> @@ -193,7 +194,7 @@ <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'>BBFILE_PRIORITY</ulink></filename> variable then assigns a priority to the layer. Applying priorities is useful in situations - where the same package might appear in multiple + where the same recipe might appear in multiple layers and allows you to choose the layer that takes precedence.</para></listitem> <listitem><para>The @@ -347,6 +348,12 @@ DEPENDS_append_one = " foo" DEPENDS_prepend_one = "foo " </literallayout> + As an actual example, here's a line from the recipe for + the OProfile profiler, which lists an extra build-time + dependency when building specifically for 64-bit PowerPC: + <literallayout class='monospaced'> + DEPENDS_append_powerpc64 = " libpfm4" + </literallayout> <note> Avoiding "+=" and "=+" and using machine-specific @@ -414,7 +421,7 @@ <itemizedlist> <listitem><para>Store custom layers in a Git repository that uses the - <filename>meta-<layer_name></filename> format. + <filename>meta-<replaceable>layer_name</replaceable></filename> format. </para></listitem> <listitem><para>Clone the repository alongside other <filename>meta</filename> directories in the @@ -534,7 +541,7 @@ LICENSE = "MIT" LIC_FILES_CHKSUM = "file://${COREBASE}/LICENSE;md5=4d92cd373abda3937c2bc47fbc49d690 \ file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420" - PR = "r44" + PR = "r45" SRC_URI = "file://config file://machconfig" S = "${WORKDIR}" @@ -543,7 +550,7 @@ INHIBIT_DEFAULT_DEPS = "1" do_install() { - # Only install file if it has a contents + # Install file only if it has contents install -d ${D}${sysconfdir}/formfactor/ install -m 0644 ${S}/config ${D}${sysconfdir}/formfactor/ if [ -s "${S}/machconfig" ]; then @@ -671,7 +678,7 @@ <para> Use the following form when running the layer management tool. <literallayout class='monospaced'> - $ bitbake-layers <command> [arguments] + $ bitbake-layers <replaceable>command</replaceable> [<replaceable>arguments</replaceable>] </literallayout> The following list describes the available commands: <itemizedlist> @@ -738,13 +745,13 @@ ... DESCRIPTION = "A useful utility" ... - EXTRA_OECONF = "--enable-something" + EXTRA_OECONF = "‐‐enable-something" ... #### bbappended from meta-anotherlayer #### DESCRIPTION = "Customized utility" - EXTRA_OECONF += "--enable-somethingelse" + EXTRA_OECONF += "‐‐enable-somethingelse" </literallayout> Ideally, you would tidy up these utilities as follows: @@ -752,7 +759,7 @@ ... DESCRIPTION = "Customized utility" ... - EXTRA_OECONF = "--enable-something --enable-somethingelse" + EXTRA_OECONF = "‐‐enable-something ‐‐enable-somethingelse" ... </literallayout></para></listitem> </itemizedlist></para></listitem> @@ -775,7 +782,7 @@ The default mode of the script's operation is to prompt you for information needed to generate the layer: <itemizedlist> - <listitem><para>The layer priority + <listitem><para>The layer priority. </para></listitem> <listitem><para>Whether or not to create a sample recipe. </para></listitem> @@ -816,7 +823,7 @@ This directory contains the layer's configuration file. The root name for the file is the same as the root name your provided for the layer (e.g. - <filename><layer>.conf</filename>). + <filename><replaceable>layer</replaceable>.conf</filename>). </para></listitem> <listitem><para><emphasis>The <filename>COPYING.MIT</filename> file:</emphasis> @@ -832,7 +839,7 @@ <para> If you choose to generate a sample recipe file, the script prompts you for the name for the recipe and then creates it - in <filename><layer>/recipes-example/example/</filename>. + in <filename><replaceable>layer</replaceable>/recipes-example/example/</filename>. The script creates a <filename>.bb</filename> file and a directory, which contains a sample <filename>helloworld.c</filename> source file, along with @@ -844,7 +851,7 @@ <para> If you choose to generate a sample append file, the script prompts you for the name for the file and then creates it - in <filename><layer>/recipes-example-bbappend/example-bbappend/</filename>. + in <filename><replaceable>layer</replaceable>/recipes-example-bbappend/example-bbappend/</filename>. The script creates a <filename>.bbappend</filename> file and a directory, which contains a sample patch file. If you do not provide a recipe name, the script uses @@ -1221,7 +1228,7 @@ S = "${WORKDIR}/${PN}-${PV}" - inherit <stuff> + inherit <replaceable>stuff</replaceable> </literallayout> Modifying this recipe is the recommended method for creating a new recipe. @@ -1267,7 +1274,7 @@ When you name your recipe, you need to follow this naming convention: <literallayout class='monospaced'> - <basename>_<version>.bb + <replaceable>basename</replaceable>_<replaceable>version</replaceable>.bb </literallayout> Use lower-cased characters and do not include the reserved suffixes <filename>-native</filename>, @@ -1313,7 +1320,7 @@ <listitem><para><emphasis>Functions:</emphasis> Functions provide a series of actions to be performed. You usually use functions to override the default - implementation of a task function or to compliment + implementation of a task function or to complement a default function (i.e. append or prepend to an existing function). Standard functions use <filename>sh</filename> shell @@ -1325,12 +1332,13 @@ do_install () { autotools_do_install install -d ${D}${base_bindir} - mv ${D}${bindir}/sed ${D}${base_bindir}/sed.${PN} + mv ${D}${bindir}/sed ${D}${base_bindir}/sed + rmdir ${D}${bindir}/ } </literallayout> It is also possible to implement new functions that are called between existing tasks as long as the - new functions are not replacing or complimenting the + new functions are not replacing or complementing the default functions. You can implement functions in Python instead of shell. @@ -1386,13 +1394,13 @@ </note> </para></listitem> <listitem><para><emphasis>Using Variables: <filename>${...}</filename></emphasis> - - Use the <filename>${<varname>}</filename> syntax to + Use the <filename>${<replaceable>varname</replaceable>}</filename> syntax to access the contents of a variable: <literallayout class='monospaced'> SRC_URI = "${SOURCEFORGE_MIRROR}/libpng/zlib-${PV}.tar.gz" </literallayout> </para></listitem> - <listitem><para><emphasis>Quote All Assignments: <filename>"<value>"</filename></emphasis> - + <listitem><para><emphasis>Quote All Assignments: <filename>"<replaceable>value</replaceable>"</filename></emphasis> - Use double quotes around the value in all variable assignments. <literallayout class='monospaced'> @@ -1481,7 +1489,6 @@ Use the <filename>_prepend</filename> operator to prepend values to existing variables. This operator does not add any additional space. - This operator does not add any additional space. Also, the operator is applied after all the <filename>+=</filename>, and <filename>=+</filename> operators have been applied and @@ -1499,12 +1506,12 @@ only being performed for the specified target or machine: <literallayout class='monospaced'> - CFLAGS_prepend_sh4 = " file://fix-makefile.patch" + CFLAGS_prepend_sh4 = "-I${S}/myincludes " </literallayout> </para></listitem> <listitem><para><emphasis>Overrides:</emphasis> - You can use overrides to set a value conditionally, - typically on how the recipe is being built. + typically based on how the recipe is being built. For example, to set the <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink> variable's value to "standard/base" for any target @@ -1521,7 +1528,7 @@ For example, when setting variables such as <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink> and - <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>, + <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink> that are specific to individual packages produced by a recipe, you should always use an override that specifies the name of the package. @@ -1534,12 +1541,12 @@ Realize that some layers have a policy to use spaces for all indentation. </para></listitem> - <listitem><para><emphasis>Using Python for Complex Operations: <filename>${@<python_code>}</filename></emphasis> - + <listitem><para><emphasis>Using Python for Complex Operations: <filename>${@<replaceable>python_code</replaceable>}</filename></emphasis> - For more advanced processing, it is possible to use Python code during variable assignments (e.g. search and replacement on a variable).</para> <para>You indicate Python code using the - <filename>${@<python_code>}</filename> + <filename>${@<replaceable>python_code</replaceable>}</filename> syntax for the variable assignment: <literallayout class='monospaced'> SRC_URI = "ftp://ftp.info-zip.org/pub/infozip/src/zip${@d.getVar('PV',1).replace('.', '')}.tgz @@ -1570,7 +1577,7 @@ Creating a new recipe is usually an iterative process that requires using BitBake to process the recipe multiple times in order to progressively discover and add information to the - recipe. + recipe file. </para> <para> @@ -1582,34 +1589,35 @@ <link linkend='build-directory'>Build Directory</link>, use BitBake to process your recipe. All you need to provide is the - <filename><basename></filename> of the recipe as described + <filename><replaceable>basename</replaceable></filename> of the recipe as described in the previous section: <literallayout class='monospaced'> - $ bitbake <basename> + $ bitbake <replaceable>basename</replaceable> </literallayout> </para> <para> During the build, the OpenEmbedded build system creates a - temporary work directory for the recipe + temporary work directory for each recipe (<filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename>) where it keeps extracted source files, log files, intermediate compilation and packaging files, and so forth. </para> <para> - The temporary work directory is constructed as follows and + The per-recipe temporary work directory is constructed as follows and depends on several factors: <literallayout class='monospaced'> - ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR} + BASE_WORKDIR ?= "${TMPDIR}/work" + WORKDIR = "${BASE_WORKDIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}" </literallayout> As an example, assume a Source Directory top-level folder named <filename>poky</filename>, a default Build Directory at <filename>poky/build</filename>, and a <filename>qemux86-poky-linux</filename> machine target system. Furthermore, suppose your recipe is named - <filename>foo_1.3.0-r0.bb</filename>. + <filename>foo_1.3.0.bb</filename>. In this case, the work directory the build system uses to build the package would be as follows: <literallayout class='monospaced'> @@ -1624,7 +1632,7 @@ You can find log files for each task in the recipe's <filename>temp</filename> directory (e.g. <filename>poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0/temp</filename>). - Log files are named <filename>log.<taskname></filename> + Log files are named <filename>log.<replaceable>taskname</replaceable></filename> (e.g. <filename>log.do_configure</filename>, <filename>log.do_fetch</filename>, and <filename>log.do_compile</filename>). @@ -1680,7 +1688,7 @@ The <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>do_fetch</filename></ulink> task uses the prefix of each entry in the - <filename>SRC_URI</filename> variable value to determine what + <filename>SRC_URI</filename> variable value to determine which fetcher to use to get your source files. It is the <filename>SRC_URI</filename> variable that triggers the fetcher. @@ -1710,7 +1718,7 @@ <para> Here is a simple example from the - <filename>meta/recipes-devtools/cdrtools/cdrtools-native_3.01a17.bb</filename> + <filename>meta/recipes-devtools/cdrtools/cdrtools-native_3.01a20.bb</filename> recipe where the source comes from a single tarball. Notice the use of the <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> @@ -1789,18 +1797,36 @@ </para> <para> - To find these checksums, you can comment the statements out - and then attempt to build the software. - The build will produce an error for each missing checksum - and as part of the error message provide the correct checksum - string. - Once you have the correct checksums, simply copy them into your - recipe for a subsequent build. + Proper values for <filename>md5</filename> and + <filename>sha256</filename> checksums might be available + with other signatures on the download page for the upstream + source (e.g. <filename>md5</filename>, + <filename>sha1</filename>, <filename>sha256</filename>, + <filename>GPG</filename>, and so forth). + Because the OpenEmbedded build system only deals with + <filename>sha256sum</filename> and <filename>md5sum</filename>, + you should verify all the signatures you find by hand. + </para> + + <para> + If no <filename>SRC_URI</filename> checksums are specified + when you attempt to build the recipe, the build will produce + an error for each missing checksum. + As part of the error message, the build system provides + the checksum string corresponding to the fetched file. + Once you have the correct checksums, you can copy and paste + them into your recipe and then run the build again to continue. + <note> + As mentioned, if the upstream source provides signatures + for verifying the downloaded source code, you should + verify those manually before setting the checksum values + in the recipe and continuing with the build. + </note> </para> <para> This final example is a bit more complicated and is from the - <filename>meta/recipes-sato/rxvt-unicode/rxvt-unicode_9.19.bb</filename> + <filename>meta/recipes-sato/rxvt-unicode/rxvt-unicode_9.20.bb</filename> recipe. The example's <filename>SRC_URI</filename> statement identifies multiple files as the source files for the recipe: a tarball, a @@ -1820,8 +1846,8 @@ The path is relative to the <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink> variable and searches specific directories in a certain order: - <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BPN'><filename>BPN</filename></ulink><filename>}</filename>, <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BP'><filename>BP</filename></ulink><filename>}</filename>, + <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BPN'><filename>BPN</filename></ulink><filename>}</filename>, and <filename>files</filename>. The directories are assumed to be subdirectories of the directory in which the recipe or append file resides. @@ -1967,6 +1993,12 @@ incorrect md5 strings, attempt to build the software, and then note the resulting error messages that will report the correct md5 strings. + See the + "<link linkend='new-recipe-fetching-code'>Fetching Code</link>" + section for additional information. + </para> + + <para> Here is an example that assumes the software has a <filename>COPYING</filename> file: <literallayout class='monospaced'> @@ -2061,7 +2093,7 @@ <filename>configure.ac</filename> file, then your software is built using Autotools. If this is the case, you just need to worry about - tweaking the configuration.</para> + modifying the configuration.</para> <para>When using Autotools, your recipe needs to inherit the <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-autotools'><filename>autotools</filename></ulink> @@ -2078,7 +2110,7 @@ <filename>CMakeLists.txt</filename> file, then your software is built using CMake. If this is the case, you just need to worry about - tweaking the configuration.</para> + modifying the configuration.</para> <para>When you use CMake, your recipe needs to inherit the <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-cmake'><filename>cmake</filename></ulink> @@ -2110,7 +2142,7 @@ configure script with the appropriate options.</para> <para>For the case involving a custom configure script, you would run - <filename>./configure --help</filename> and look for + <filename>./configure ‐‐help</filename> and look for the options you need to set.</para></listitem> </itemizedlist> </para> @@ -2126,14 +2158,14 @@ that it did not find something that it needed for some desired optional functionality, then you would need to add those to <filename>DEPENDS</filename>. - Looking at the log might also reveal items being checked for - and/or enabled that you do not want, or items not being found + Looking at the log might also reveal items being checked for, + enabled, or both that you do not want, or items not being found that are in <filename>DEPENDS</filename>, in which case you would need to look at passing extra options to the configure script as needed. For reference information on configure options specific to the software you are building, you can consult the output of the - <filename>./configure --help</filename> command within + <filename>./configure ‐‐help</filename> command within <filename>${S}</filename> or consult the software's upstream documentation. </para> @@ -2171,7 +2203,12 @@ to an empty string: <literallayout class='monospaced'> PARALLEL_MAKE = "" - </literallayout></para></listitem> + </literallayout></para> + <para> + For information on parallel Makefile issues, see the + "<link linkend='debugging-parallel-make-races'>Debugging Parallel Make Races</link>" + section. + </para></listitem> <listitem><para><emphasis>Improper host path usage:</emphasis> This failure applies to recipes building for the target or <filename>nativesdk</filename> only. @@ -2261,7 +2298,7 @@ <filename>make install</filename>, you should do this using a <filename>do_install_append</filename> function using the install command as described in - <emphasis>Manual</emphasis> later in this list. + the "Manual" bulleted item later in this list. </para></listitem> <listitem><para><emphasis>Other (using <filename>make install</filename>):</emphasis> @@ -2310,39 +2347,47 @@ files have been installed correctly. </para> - <note> - During the installation process, you might need to modify - some of the installed files to suit the target layout. - For example, you might need to replace hard-coded paths in an - initscript with values of variables provided by the build - system, such as replacing <filename>/usr/bin/</filename> with - <filename>${bindir}</filename>. - If you do perform such modifications during - <filename>do_install</filename>, be sure to modify the - destination file after copying rather than before copying. - Modifying after copying ensures that the build system can - re-execute <filename>do_install</filename> if needed. - </note> - - <note> - <filename>oe_runmake install</filename>, which can be run - directly or can be run indirectly by the - <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-autotools'><filename>autotools</filename></ulink> - and - <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-cmake'><filename>cmake</filename></ulink> - classes, runs <filename>make install</filename> in parallel. - Sometimes, a Makefile can have missing dependencies between - targets that can result in race conditions. - If you experience intermittent failures during - <filename>do_install</filename>, you might be able to work - around them by disabling parallel Makefile installs - by adding the following to the recipe: - <literallayout class='monospaced'> + <note><title>Notes</title> + <itemizedlist> + <listitem><para> + During the installation process, you might need to + modify some of the installed files to suit the target + layout. + For example, you might need to replace hard-coded paths + in an initscript with values of variables provided by + the build system, such as replacing + <filename>/usr/bin/</filename> with + <filename>${bindir}</filename>. + If you do perform such modifications during + <filename>do_install</filename>, be sure to modify the + destination file after copying rather than before + copying. + Modifying after copying ensures that the build system + can re-execute <filename>do_install</filename> if + needed. + </para></listitem> + <listitem><para> + <filename>oe_runmake install</filename>, which can be + run directly or can be run indirectly by the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-autotools'><filename>autotools</filename></ulink> + and + <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-cmake'><filename>cmake</filename></ulink> + classes, runs <filename>make install</filename> in + parallel. + Sometimes, a Makefile can have missing dependencies + between targets that can result in race conditions. + If you experience intermittent failures during + <filename>do_install</filename>, you might be able to + work around them by disabling parallel Makefile + installs by adding the following to the recipe: + <literallayout class='monospaced'> PARALLEL_MAKEINST = "" - </literallayout> - See - <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKEINST'><filename>PARALLEL_MAKEINST</filename></ulink> - for additional information. + </literallayout> + See + <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKEINST'><filename>PARALLEL_MAKEINST</filename></ulink> + for additional information. + </para></listitem> + </itemizedlist> </note> </section> @@ -2410,7 +2455,7 @@ needs to inherit the <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-systemd'><filename>systemd</filename></ulink> class. - See the <filename>systemd.class</filename> file + See the <filename>systemd.bbclass</filename> file located in your <link linkend='source-directory'>Source Directory</link>. section for more information. @@ -2438,7 +2483,9 @@ that files are split up and packaged correctly. </para></listitem> <listitem><para><emphasis>Running QA Checks</emphasis>: - The <filename>insane</filename> class adds a step to + The + <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-insane'><filename>insane</filename></ulink> + class adds a step to the package generation process so that output quality assurance checks are generated by the OpenEmbedded build system. @@ -2502,7 +2549,7 @@ machine or architecture at all (e.g. recipes that simply package script files or configuration files), you should use the - <ulink url='&YOCTO_DOCS_REF_URL;#allarch'><filename>allarch</filename></ulink> + <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-allarch'><filename>allarch</filename></ulink> class to do this for you by adding this to your recipe: <literallayout class='monospaced'> @@ -2511,7 +2558,7 @@ Ensuring that the package architecture is correct is not critical while you are doing the first few builds of your recipe. - However, it is important in order to + However, it is important in order to ensure that your recipe rebuilds (or does not rebuild) appropriately in response to changes in configuration, and to ensure that you get the @@ -2549,7 +2596,7 @@ recommended convention is to set <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> within the recipe to - "<previous version>+<current version>". + "<replaceable>previous_version</replaceable>+<replaceable>current_version</replaceable>". You can use an additional variable so that you can use the current version elsewhere. Here is an example: @@ -2565,7 +2612,7 @@ <para> Post-installation scripts run immediately after installing - a package on the target, or during image creation when a + a package on the target or during image creation when a package is included in an image. To add a post-installation script to a package, add a <filename>pkg_postinst_PACKAGENAME()</filename> function to @@ -2582,7 +2629,7 @@ <para> A post-installation function has the following structure: <literallayout class='monospaced'> - pkg_postinst_PACKAGENAME () { + pkg_postinst_PACKAGENAME() { #!/bin/sh -e # Commands to carry out } @@ -2605,7 +2652,7 @@ To delay script execution until boot time, use the following structure in the post-installation script: <literallayout class='monospaced'> - pkg_postinst_PACKAGENAME () { + pkg_postinst_PACKAGENAME() { #!/bin/sh -e if [ x"$D" = "x" ]; then # Actions to carry out on the device go here @@ -2668,6 +2715,7 @@ <listitem><para>Using an Autotooled package</para></listitem> <listitem><para>Using a Makefile-based package</para></listitem> <listitem><para>Splitting an application into multiple packages</para></listitem> + <listitem><para>Adding binaries to an image</para></listitem> </itemizedlist> </para> @@ -2676,7 +2724,7 @@ <para> Building an application from a single file that is stored - locally (e.g. under <filename>files/</filename>) requires + locally (e.g. under <filename>files</filename>) requires a recipe that has the file listed in the <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename> variable. @@ -2767,7 +2815,7 @@ If you need additional <filename>make</filename> options, you should store them in the <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OEMAKE'>EXTRA_OEMAKE</ulink></filename> variable. - BitBake passes these options into the <filename>make</filename> GNU invocation. + BitBake passes these options into the GNU <filename>make</filename> invocation. Note that a <filename>do_install</filename> task is still required. Otherwise, BitBake runs an empty <filename>do_install</filename> task by default. </para> @@ -2786,33 +2834,36 @@ <para> In the following example, <filename>mtd-utils</filename> is a makefile-based package: <literallayout class='monospaced'> - SUMMARY = "Tools for managing memory technology devices." + SUMMARY = "Tools for managing memory technology devices" SECTION = "base" DEPENDS = "zlib lzo e2fsprogs util-linux" HOMEPAGE = "http://www.linux-mtd.infradead.org/" LICENSE = "GPLv2+" LIC_FILES_CHKSUM = "file://COPYING;md5=0636e73ff0215e8d672dc4c32c317bb3 \ - file://include/common.h;beginline=1;endline=17;md5=ba05b07912a44ea2bf81ce409380049c" + file://include/common.h;beginline=1;endline=17;md5=ba05b07912a44ea2bf81ce409380049c" - SRC_URI = "git://git.infradead.org/mtd-utils.git;protocol=git;tag=995cfe51b0a3cf32f381c140bf72b21bf91cef1b \ - file://add-exclusion-to-mkfs-jffs2-git-2.patch" + # Use the latest version at 26 Oct, 2013 + SRCREV = "9f107132a6a073cce37434ca9cda6917dd8d866b" + SRC_URI = "git://git.infradead.org/mtd-utils.git \ + file://add-exclusion-to-mkfs-jffs2-git-2.patch \ + " - S = "${WORKDIR}/git/" + PV = "1.5.1+git${SRCPV}" - PR = "r1" + S = "${WORKDIR}/git/" - EXTRA_OEMAKE = "'CC=${CC}' 'RANLIB=${RANLIB}' 'AR=${AR}' \ - 'CFLAGS=${CFLAGS} -I${S}/include -DWITHOUT_XATTR' 'BUILDDIR=${S}'" + EXTRA_OEMAKE = "'CC=${CC}' 'RANLIB=${RANLIB}' 'AR=${AR}' 'CFLAGS=${CFLAGS} -I${S}/include -DWITHOUT_XATTR' 'BUILDDIR=${S}'" do_install () { - oe_runmake install DESTDIR=${D} SBINDIR=${sbindir} MANDIR=${mandir} \ - INCLUDEDIR=${includedir} - install -d ${D}${includedir}/mtd/ - for f in ${S}/include/mtd/*.h; do - install -m 0644 $f ${D}${includedir}/mtd/ - done + oe_runmake install DESTDIR=${D} SBINDIR=${sbindir} MANDIR=${mandir} INCLUDEDIR=${includedir} } + PACKAGES =+ "mtd-utils-jffs2 mtd-utils-ubifs mtd-utils-misc" + + FILES_mtd-utils-jffs2 = "${sbindir}/mkfs.jffs2 ${sbindir}/jffs2dump ${sbindir}/jffs2reader ${sbindir}/sumtool" + FILES_mtd-utils-ubifs = "${sbindir}/mkfs.ubifs ${sbindir}/ubi*" + FILES_mtd-utils-misc = "${sbindir}/nftl* ${sbindir}/ftl* ${sbindir}/rfd* ${sbindir}/doc* ${sbindir}/serve_image ${sbindir}/recv_image" + PARALLEL_MAKE = "" BBCLASSEXTEND = "native" @@ -2868,6 +2919,100 @@ does not include the above listed files. </para> </section> + + <section id='packaging-externally-produced-binaries'> + <title>Packaging Externally Produced Binaries</title> + + <para> + Sometimes, you need to add pre-compiled binaries to an + image. + For example, suppose that binaries for proprietary code + exist, which are created by a particular division of a + company. + Your part of the company needs to use those binaries as + part of an image that you are building using the + OpenEmbedded build system. + Since you only have the binaries and not the source code, + you cannot use a typical recipe that expects to fetch the + source specified in + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + and then compile it. + </para> + + <para> + One method is to package the binaries and then install them + as part of the image. + Generally, it is not a good idea to package binaries + since, among other things, it can hinder the ability to + reproduce builds and could lead to compatibility problems + with ABI in the future. + However, sometimes you have no choice. + </para> + + <para> + The easiest solution is to create a recipe that uses + the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-bin-package'><filename>bin_package</filename></ulink> + class and to be sure that you are using default locations + for build artifacts. + In most cases, the <filename>bin_package</filename> class + handles "skipping" the configure and compile steps as well + as sets things up to grab packages from the appropriate + area. + In particular, this class sets <filename>noexec</filename> + on both the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-configure'><filename>do_configure</filename></ulink> + and + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile</filename></ulink> + tasks, sets + <filename>FILES_${PN}</filename> to "/" so that it picks + up all files, and sets up a + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink> + task, which effectively copies all files from + <filename>${S}</filename> to <filename>${D}</filename>. + The <filename>bin_package</filename> class works well when + the files extracted into <filename>${S}</filename> are + already laid out in the way they should be laid out + on the target. + For more information on these variables, see the + <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink>, + <ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>, + <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>, + and + <ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink> + variables in the Yocto Project Reference Manual's variable + glossary. + </para> + + <para> + If you can't use the <filename>bin_package</filename> + class, you need to be sure you are doing the following: + <itemizedlist> + <listitem><para>Create a recipe where the + <filename>do_configure</filename> and + <filename>do_compile</filename> tasks do nothing: + <literallayout class='monospaced'> + do_configure[noexec] = "1" + do_compile[noexec] = "1" + </literallayout> + Alternatively, you can make these tasks an empty + function. + </para></listitem> + <listitem><para>Make sure your + <filename>do_install</filename> task installs the + binaries appropriately. + </para></listitem> + <listitem><para>Ensure that you set up + <filename>FILES</filename> (usually + <filename>FILES_${PN}</filename>) to point to the + files you have installed, which of course depends + on where you have installed them and whether + those files are in different locations than the + defaults. + </para></listitem> + </itemizedlist> + </para> + </section> </section> </section> @@ -2875,7 +3020,7 @@ <title>Adding a New Machine</title> <para> - Adding a new machine to the Yocto Project is a straight forward + Adding a new machine to the Yocto Project is a straightforward process. This section describes how to add machines that are similar to those that the Yocto Project already supports. @@ -2915,12 +3060,13 @@ <para> The most important variables you must set in your machine - configuration file are as follows: + configuration file or include from a lower-level configuration + file are as follows: <itemizedlist> <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_ARCH'>TARGET_ARCH</ulink></filename> (e.g. "arm")</para></listitem> <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'>PREFERRED_PROVIDER</ulink>_virtual/kernel</filename> - (see below)</para></listitem> + </para></listitem> <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_FEATURES'>MACHINE_FEATURES</ulink></filename> (e.g. "apm screen wifi")</para></listitem> </itemizedlist> @@ -3073,41 +3219,47 @@ variables in the <filename>meta/conf/bitbake.conf</filename> configuration file define how files installed by the <filename>do_install</filename> task are packaged. - By default, the <filename>PACKAGES</filename> variable contains - <filename>${PN}-staticdev</filename>, which includes all static library files. + By default, the <filename>PACKAGES</filename> variable includes + <filename>${PN}-staticdev</filename>, which represents all static library files. <note> Some previously released versions of the Yocto Project defined the static library files through <filename>${PN}-dev</filename>. </note> - Following, is part of the BitBake configuration file. - You can see where the static library files are defined: + Following is part of the BitBake configuration file, where + you can see how the static library files are defined: <literallayout class='monospaced'> - PACKAGES = "${PN}-dbg ${PN} ${PN}-doc ${PN}-dev ${PN}-staticdev ${PN}-locale" - PACKAGES_DYNAMIC = "${PN}-locale-*" + PACKAGE_BEFORE_PN ?= "" + PACKAGES = "${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}" + PACKAGES_DYNAMIC = "^${PN}-locale-.*" FILES = "" FILES_${PN} = "${bindir}/* ${sbindir}/* ${libexecdir}/* ${libdir}/lib*${SOLIBS} \ ${sysconfdir} ${sharedstatedir} ${localstatedir} \ ${base_bindir}/* ${base_sbindir}/* \ ${base_libdir}/*${SOLIBS} \ + ${base_prefix}/lib/udev/rules.d ${prefix}/lib/udev/rules.d \ ${datadir}/${BPN} ${libdir}/${BPN}/* \ ${datadir}/pixmaps ${datadir}/applications \ ${datadir}/idl ${datadir}/omf ${datadir}/sounds \ ${libdir}/bonobo/servers" + FILES_${PN}-bin = "${bindir}/* ${sbindir}/*" + FILES_${PN}-doc = "${docdir} ${mandir} ${infodir} ${datadir}/gtk-doc \ ${datadir}/gnome/help" SECTION_${PN}-doc = "doc" - FILES_${PN}-dev = "${includedir} ${libdir}/lib*${SOLIBSDEV} ${libdir}/*.la \ + FILES_SOLIBSDEV ?= "${base_libdir}/lib*${SOLIBSDEV} ${libdir}/lib*${SOLIBSDEV}" + FILES_${PN}-dev = "${includedir} ${FILES_SOLIBSDEV} ${libdir}/*.la \ ${libdir}/*.o ${libdir}/pkgconfig ${datadir}/pkgconfig \ - ${datadir}/aclocal ${base_libdir}/*.o" + ${datadir}/aclocal ${base_libdir}/*.o \ + ${libdir}/${BPN}/*.la ${base_libdir}/*.la" SECTION_${PN}-dev = "devel" ALLOW_EMPTY_${PN}-dev = "1" RDEPENDS_${PN}-dev = "${PN} (= ${EXTENDPKGV})" - FILES_${PN}-staticdev = "${libdir}/*.a ${base_libdir}/*.a" + FILES_${PN}-staticdev = "${libdir}/*.a ${base_libdir}/*.a ${libdir}/${BPN}/*.a" SECTION_${PN}-staticdev = "devel" RDEPENDS_${PN}-staticdev = "${PN}-dev (= ${EXTENDPKGV})" </literallayout> @@ -3137,7 +3289,7 @@ While the Multilib feature is most commonly used for 32 and 64-bit differences, the approach the build system uses facilitates different target optimizations. You could compile some binaries to use one set of libraries and other binaries - to use other different sets of libraries. + to use a different set of libraries. The libraries could differ in architecture, compiler options, or other optimizations. </para> @@ -3196,8 +3348,9 @@ <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>, <ulink url='&YOCTO_DOCS_REF_URL;#var-RPROVIDES'><filename>RPROVIDES</filename></ulink>, <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>, - <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>, - and <filename>PACKAGES_DYNAMIC</filename> are automatically extended by the system. + <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>, and + <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES_DYNAMIC'><filename>PACKAGES_DYNAMIC</filename></ulink> + are automatically extended by the system. If you are extending any manual code in the recipe, you can use the <filename>${MLPREFIX}</filename> variable to ensure those names are extended correctly. @@ -3241,7 +3394,7 @@ </literallayout> You can also build Multilib packages specifically with a command like this: <literallayout class='monospaced'> - $ bitbake lib32-connman + $ bitbake lib32-connman </literallayout> </para> </section> @@ -3315,7 +3468,7 @@ </para> <para> - The process is straight forward as long as the libraries use + The process is straightforward as long as the libraries use proper versioning. With properly versioned libraries, all you need to do to individually specify the libraries is create separate, @@ -3348,6 +3501,944 @@ </section> </section> + <section id='creating-partitioned-images'> + <title>Creating Partitioned Images</title> + + <para> + Creating an image for a particular hardware target using the + OpenEmbedded build system does not necessarily mean you can boot + that image as is on your device. + Physical devices accept and boot images in various ways depending + on the specifics of the device. + Usually, information about the hardware can tell you what image + format the device requires. + Should your device require multiple partitions on an SD card, flash, + or an HDD, you can use the OpenEmbedded Image Creator, + <filename>wic</filename>, to create the properly partitioned image. + </para> + + <para> + The <filename>wic</filename> command generates partitioned images + from existing OpenEmbedded build artifacts. + Image generation is driven by partitioning commands contained + in an Openembedded kickstart file (<filename>.wks</filename>) + specified either directly on the command line or as one of a + selection of canned <filename>.wks</filename> files as shown + with the <filename>wic list images</filename> command in the + "<link linkend='using-a-provided-kickstart_file'>Using an Existing Kickstart File</link>" + section. + When applied to a given set of build artifacts, the result is an + image or set of images that can be directly written onto media and + used on a particular system. + </para> + + <para> + The <filename>wic</filename> command and the infrastructure + it is based on is by definition incomplete. + Its purpose is to allow the generation of customized images, + and as such was designed to be completely extensible through a + plugin interface. + See the + "<link linkend='openembedded-kickstart-plugins'>Plugins</link>" + section for information on these plugins. + </para> + + <para> + This section provides some background information on + <filename>wic</filename>, describes what you need to have in + place to run the tool, provides instruction on how to use + <filename>wic</filename>, and provides several examples. + </para> + + <section id='wic-background'> + <title>Background</title> + + <para> + This section provides some background on the + <filename>wic</filename> utility. + While none of this information is required to use + <filename>wic</filename>, you might find it interesting. + <itemizedlist> + <listitem><para> + The name "wic" is derived from OpenEmbedded + Image Creator (oeic). + The "oe" diphthong in "oeic" was promoted to the + letter "w", because "oeic" is both difficult to remember and + pronounce.</para></listitem> + <listitem><para> + <filename>wic</filename> is loosely based on the + Meego Image Creator (<filename>mic</filename>) + framework. + The <filename>wic</filename> implementation has been + heavily modified to make direct use of OpenEmbedded + build artifacts instead of package installation and + configuration, which are already incorporated within + the OpenEmbedded artifacts.</para></listitem> + <listitem><para> + <filename>wic</filename> is a completely independent + standalone utility that initially provides + easier-to-use and more flexible replacements for a + couple bits of existing functionality in OE Core's + <filename>boot-directdisk.bbclass</filename> and + <filename>mkefidisk.sh</filename> scripts. + The difference between + <filename>wic</filename> and those examples is + that with <filename>wic</filename> the + functionality of those scripts is implemented + by a general-purpose partitioning language, which is + based on Redhat kickstart syntax.</para></listitem> + </itemizedlist> + </para> + </section> + + <section id='wic-requirements'> + <title>Requirements</title> + + <para> + In order to use the <filename>wic</filename> utility + with the OpenEmbedded Build system, your system needs + to meet the following requirements: + <itemizedlist> + <listitem><para>The Linux distribution on your + development host must support the Yocto Project. + See the + "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>" + section in the Yocto Project Reference Manual for this + list of distributions.</para></listitem> + <listitem><para> + The standard system utilities, such as + <filename>cp</filename>, must be installed on your + development host system. + </para></listitem> + <listitem><para> + The + <ulink url='http://www.gnu.org/software/parted/'>GNU Parted</ulink> + package must be installed on your development host + system. + </para></listitem> + <listitem><para> + You need to have the build artifacts already + available, which typically means that you must + have already created an image using the + Openembedded build system (e.g. + <filename>core-image-minimal</filename>). + While it might seem redundant to generate an image in + order to create an image using + <filename>wic</filename>, the current version of + <filename>wic</filename> requires the artifacts + in the form generated by the build system. + </para></listitem> + <listitem><para> + You must have sourced one of the build environment + setup scripts (i.e. + <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> + or + <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>) + found in the + <link linkend='build-directory'>Build Directory</link>. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='wic-getting-help'> + <title>Getting Help</title> + + <para> + You can get general help for the <filename>wic</filename> + by entering the <filename>wic</filename> command by itself + or by entering the command with a help argument as follows: + <literallayout class='monospaced'> + $ wic -h + $ wic ‐‐help + </literallayout> + </para> + + <para> + Currently, <filename>wic</filename> supports two commands: + <filename>create</filename> and <filename>list</filename>. + You can get help for these commands as follows: + <literallayout class='monospaced'> + $ wic help <replaceable>command</replaceable> + </literallayout> + </para> + + <para> + You can also get detailed help on a number of topics + from the help system. + The output of <filename>wic ‐‐help</filename> + displays a list of available help + topics under a "Help topics" heading. + You can have the help system display the help text for + a given topic by prefacing the topic with + <filename>wic help</filename>: + <literallayout class='monospaced'> + $ wic help <replaceable>help_topic</replaceable> + </literallayout> + </para> + + <para> + You can find out more about the images + <filename>wic</filename> creates using the existing + kickstart files with the following form of the command: + <literallayout class='monospaced'> + $ wic list <replaceable>image</replaceable> help + </literallayout> + where <filename><replaceable>image</replaceable></filename> is either + <filename>directdisk</filename> or + <filename>mkefidisk</filename>. + </para> + </section> + + <section id='operational-modes'> + <title>Operational Modes</title> + + <para> + You can use <filename>wic</filename> in two different + modes, depending on how much control you need for + specifying the Openembedded build artifacts that are + used for creating the image: Raw and Cooked: + <itemizedlist> + <listitem><para><emphasis>Raw Mode:</emphasis> + You explicitly specify build artifacts through + command-line arguments.</para></listitem> + <listitem><para><emphasis>Cooked Mode:</emphasis> + The current + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> + setting and image name are used to automatically locate + and provide the build artifacts.</para></listitem> + </itemizedlist> + </para> + + <para> + Regardless of the mode you use, you need to have the build + artifacts ready and available. + Additionally, the environment must be set up using the + <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> + or + <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink> + script found in the + <link linkend='build-directory'>Build Directory</link>. + </para> + + <section id='raw-mode'> + <title>Raw Mode</title> + + <para> + The general form of the 'wic' command in raw mode is: + <literallayout class='monospaced'> + $ wic create <replaceable>image_name</replaceable>.wks [<replaceable>options</replaceable>] [...] + + Where: + + <replaceable>image_name</replaceable>.wks + An OpenEmbedded kickstart file. You can provide + your own custom file or use a file from a set of + existing files as described by further options. + + -o <replaceable>OUTDIR</replaceable>, ‐‐outdir=<replaceable>OUTDIR</replaceable> + The name of a directory in which to create image. + + -i <replaceable>PROPERTIES_FILE</replaceable>, ‐‐infile=<replaceable>PROPERTIES_FILE</replaceable> + The name of a file containing the values for image + properties as a JSON file. + + -e <replaceable>IMAGE_NAME</replaceable>, ‐‐image-name=<replaceable>IMAGE_NAME</replaceable> + The name of the image from which to use the artifacts + (e.g. <filename>core-image-sato</filename>). + + -r <replaceable>ROOTFS_DIR</replaceable>, ‐‐rootfs-dir=<replaceable>ROOTFS_DIR</replaceable> + The path to the <filename>/rootfs</filename> directory to use as the + <filename>.wks</filename> rootfs source. + + -b <replaceable>BOOTIMG_DIR</replaceable>, ‐‐bootimg-dir=<replaceable>BOOTIMG_DIR</replaceable> + The path to the directory containing the boot artifacts + (e.g. <filename>/EFI</filename> or <filename>/syslinux</filename>) to use as the <filename>.wks</filename> bootimg + source. + + -k <replaceable>KERNEL_DIR</replaceable>, ‐‐kernel-dir=<replaceable>KERNEL_DIR</replaceable> + The path to the directory containing the kernel to use + in the <filename>.wks</filename> boot image. + + -n <replaceable>NATIVE_SYSROOT</replaceable>, ‐‐native-sysroot=<replaceable>NATIVE_SYSROOT</replaceable> + The path to the native sysroot containing the tools to use + to build the image. + + -s, ‐‐skip-build-check + Skips the build check. + + -D, ‐‐debug + Output debug information. + </literallayout> + <note> + You do not need root privileges to run + <filename>wic</filename>. + In fact, you should not run as root when using the + utility. + </note> + </para> + </section> + + <section id='cooked-mode'> + <title>Cooked Mode</title> + + <para> + The general form of the <filename>wic</filename> command + using Cooked Mode is: + <literallayout class='monospaced'> + $ wic create <replaceable>kickstart_file</replaceable> -e <replaceable>image_name</replaceable> + + Where: + + <replaceable>kickstart_file</replaceable> + An OpenEmbedded kickstart file. You can provide your own + custom file or supplied file. + + <replaceable>image_name</replaceable> + Specifies the image built using the OpenEmbedded build + system. + </literallayout> + This form is the simplest and most user-friendly, as it + does not require specifying all individual parameters. + All you need to provide is your own + <filename>.wks</filename> file or one provided with the + release. + </para> + </section> + </section> + + <section id='using-a-provided-kickstart_file'> + <title>Using an Existing Kickstart File</title> + + <para> + If you do not want to create your own + <filename>.wks</filename> file, you can use an existing + file provided by the <filename>wic</filename> installation. + Use the following command to list the available files: + <literallayout class='monospaced'> + $ wic list images + directdisk Create a 'pcbios' direct disk image + mkefidisk Create an EFI disk image + </literallayout> + When you use an existing file, you do not have to use the + <filename>.wks</filename> extension. + Here is an example in Raw Mode that uses the + <filename>directdisk</filename> file: + <literallayout class='monospaced'> + $ wic create directdisk -r <replaceable>rootfs_dir</replaceable> -b <replaceable>bootimg_dir</replaceable> \ + -k <replaceable>kernel_dir</replaceable> -n <replaceable>native_sysroot</replaceable> + </literallayout> + </para> + + <para> + Here are the actual partition language commands + used in the <filename>mkefidisk.wks</filename> file to generate + an image: + <literallayout class='monospaced'> + # short-description: Create an EFI disk image + # long-description: Creates a partitioned EFI disk image that the user + # can directly dd to boot media. + + part /boot --source bootimg-efi --ondisk sda --label msdos --active --align 1024 + + part / --source rootfs --ondisk sda --fstype=ext3 --label platform --align 1024 + + part swap --ondisk sda --size 44 --label swap1 --fstype=swap + + bootloader --timeout=10 --append="rootwait rootfstype=ext3 console=ttyPCH0,115200 console=tty0 vmalloc=256MB snd-hda-intel.enable_msi=0" + </literallayout> + </para> + </section> + + <section id='wic-usage-examples'> + <title>Examples</title> + + <para> + This section provides several examples that show how to use + the <filename>wic</filename> utility. + All the examples assume the list of requirements in the + "<link linkend='wic-requirements'>Requirements</link>" section + have been met. + The examples assume the previously generated image is + <filename>core-image-minimal</filename>. + </para> + + <section id='generate-an-image-using-a-provided-kickstart-file'> + <title>Generate an Image using an Existing Kickstart File</title> + + <para> + This example runs in Cooked Mode and uses the + <filename>mkefidisk</filename> kickstart file: + <literallayout class='monospaced'> + $ wic create mkefidisk -e core-image-minimal + Checking basic build environment... + Done. + + Creating image(s)... + + Info: The new image(s) can be found here: + /var/tmp/wic/build/mkefidisk-201310230946-sda.direct + + The following build artifacts were used to create the image(s): + ROOTFS_DIR: /home/trz/yocto/yocto-image/build/tmp/work/minnow-poky-linux/core-image-minimal/1.0-r0/rootfs + BOOTIMG_DIR: /home/trz/yocto/yocto-image/build/tmp/work/minnow-poky-linux/core-image-minimal/1.0-r0/core-image-minimal-1.0/hddimg + KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/minnow/usr/src/kernel + NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/x86_64-linux + + + The image(s) were created using OE kickstart file: + /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/mkefidisk.wks + </literallayout> + This example shows the easiest way to create an image + by running in Cooked Mode and using the + <filename>-e</filename> option with an existing kickstart + file. + All that is necessary is to specify the image used to + generate the artifacts. + Your <filename>local.conf</filename> needs to have the + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> + variable set to the machine you are using, which is + "minnow" in this example. + </para> + + <para> + The output specifies the exact created as well as where + it was created. + The output also names the artifacts used and the exact + <filename>.wks</filename> script that was used to generate + the image. + <note> + You should always verify the details provided in the + output to make sure that the image was indeed created + exactly as expected. + </note> + </para> + + <para> + Continuing with the example, you can now directly + <filename>dd</filename> the image to a USB stick, or + whatever media for which you built your image, + and boot the resulting media: + <literallayout class='monospaced'> + $ sudo dd if=/var/tmp/wic/build/mkefidisk-201310230946-sda.direct of=/dev/sdb + [sudo] password for trz: + 182274+0 records in + 182274+0 records out + 93324288 bytes (93 MB) copied, 14.4777 s, 6.4 MB/s + [trz@empanada ~]$ sudo eject /dev/sdb + </literallayout> + </para> + </section> + + <section id='using-a-modified-kickstart-file'> + <title>Using a Modified Kickstart File</title> + + <para> + Because <filename>wic</filename> image creation is driven + by the kickstart file, it is easy to affect image creation + by changing the parameters in the file. + This next example demonstrates that through modification + of the <filename>directdisk</filename> kickstart file. + </para> + + <para> + As mentioned earlier, you can use the command + <filename>wic list images</filename> to show the list + of existing kickstart files. + The directory in which these files reside is + <filename>scripts/lib/image/canned-wks/</filename> + located in the + <link linkend='source-directory'>Source Directory</link>. + Because the available files reside in this directory, you + can create and add your own custom files to the directory. + Subsequent use of the <filename>wic list images</filename> + command would then include your kickstart files. + </para> + + <para> + In this example, the existing + <filename>directdisk</filename> file already does most + of what is needed. + However, for the hardware in this example, the image will + need to boot from <filename>sdb</filename> instead of + <filename>sda</filename>, which is what the + <filename>directdisk</filename> kickstart file uses. + </para> + + <para> + The example begins by making a copy of the + <filename>directdisk.wks</filename> file in the + <filename>scripts/lib/image/canned-wks</filename> + directory and then changing the lines that specify the + target disk from which to boot. + <literallayout class='monospaced'> + $ cp /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisk.wks \ + /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisksdb.wks + </literallayout> + Next, the example modifies the + <filename>directdisksdb.wks</filename> file and changes all + instances of "<filename>‐‐ondisk sda</filename>" + to "<filename>‐‐ondisk sdb</filename>". + The example changes the following two lines and leaves the + remaining lines untouched: + <literallayout class='monospaced'> + part /boot ‐‐source bootimg-pcbios ‐‐ondisk sdb ‐‐label boot ‐‐active ‐‐align 1024 + part / ‐‐source rootfs ‐‐ondisk sdb ‐‐fstype=ext3 ‐‐label platform ‐‐align 1024 + </literallayout> + Once the lines are changed, the example generates the + <filename>directdisksdb</filename> image. + The command points the process at the + <filename>core-image-minimal</filename> artifacts for the + Next Unit of Computing (nuc) + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> + the <filename>local.conf</filename>. + <literallayout class='monospaced'> + $ wic create directdisksdb -e core-image-minimal + Checking basic build environment... + Done. + + Creating image(s)... + + Info: The new image(s) can be found here: + /var/tmp/wic/build/directdisksdb-201310231131-sdb.direct + + The following build artifacts were used to create the image(s): + ROOTFS_DIR: /home/trz/yocto/yocto-image/build/tmp/work/nuc-poky-linux/core-image-minimal/1.0-r0/rootfs + BOOTIMG_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/nuc/usr/share + KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/nuc/usr/src/kernel + NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/x86_64-linux + + + The image(s) were created using OE kickstart file: + /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisksdb.wks + </literallayout> + Continuing with the example, you can now directly + <filename>dd</filename> the image to a USB stick, or + whatever media for which you built your image, + and boot the resulting media: + <literallayout class='monospaced'> + $ sudo dd if=/var/tmp/wic/build/directdisksdb-201310231131-sdb.direct of=/dev/sdb + 86018+0 records in + 86018+0 records out + 44041216 bytes (44 MB) copied, 13.0734 s, 3.4 MB/s + [trz@empanada tmp]$ sudo eject /dev/sdb + </literallayout> + </para> + </section> + + <section id='creating-an-image-based-on-core-image-minimal-and-crownbay-noemgd'> + <title>Creating an Image Based on <filename>core-image-minimal</filename> and <filename>crownbay-noemgd</filename></title> + + <para> + This example creates an image based on + <filename>core-image-minimal</filename> and a + <filename>crownbay-noemgd</filename> + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> + that works right out of the box. + <literallayout class='monospaced'> + $ wic create directdisk -e core-image-minimal + + Checking basic build environment... + Done. + + Creating image(s)... + + Info: The new image(s) can be found here: + /var/tmp/wic/build/directdisk-201309252350-sda.direct + + The following build artifacts were used to create the image(s): + + ROOTFS_DIR: /home/trz/yocto/yocto-image/build/tmp/work/crownbay_noemgd-poky-linux/core-image-minimal/1.0-r0/rootfs + BOOTIMG_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/share + KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel + NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel + + The image(s) were created using OE kickstart file: + /home/trz/yocto/yocto-image/scripts/lib/image/canned-wks/directdisk.wks + </literallayout> + </para> + </section> + + <section id='using-a-modified-kickstart-file-and-running-in-raw-mode'> + <title>Using a Modified Kickstart File and Running in Raw Mode</title> + + <para> + This next example manually specifies each build artifact + (runs in Raw Mode) and uses a modified kickstart file. + The example also uses the <filename>-o</filename> option + to cause <filename>wic</filename> to create the output + somewhere other than the default + <filename>/var/tmp/wic</filename> directory: + <literallayout class='monospaced'> + $ wic create ~/test.wks -o /home/trz/testwic ‐‐rootfs-dir \ + /home/trz/yocto/yocto-image/build/tmp/work/crownbay_noemgd-poky-linux/core-image-minimal/1.0-r0/rootfs \ + ‐‐bootimg-dir /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/share \ + ‐‐kernel-dir /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel \ + ‐‐native-sysroot /home/trz/yocto/yocto-image/build/tmp/sysroots/x86_64-linux + + Creating image(s)... + + Info: The new image(s) can be found here: + /home/trz/testwic/build/test-201309260032-sda.direct + + The following build artifacts were used to create the image(s): + + ROOTFS_DIR: /home/trz/yocto/yocto-image/build/tmp/work/crownbay_noemgd-poky-linux/core-image-minimal/1.0-r0/rootfs + BOOTIMG_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/share + KERNEL_DIR: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel + NATIVE_SYSROOT: /home/trz/yocto/yocto-image/build/tmp/sysroots/crownbay-noemgd/usr/src/kernel + + The image(s) were created using OE kickstart file: + /home/trz/test.wks + </literallayout> + For this example, + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> + did not have to be specified in the + <filename>local.conf</filename> file since the artifact is + manually specified. + </para> + </section> + </section> + + <section id='openembedded-kickstart-plugins'> + <title>Plugins</title> + + <para> + Plugins allow <filename>wic</filename> functionality to + be extended and specialized by users. + This section documents the plugin interface, which is + currently restricted to source plugins. + </para> + + <para> + Source plugins provide a mechanism to customize + various aspects of the image generation process in + <filename>wic</filename>, mainly the contents of + partitions. + The plugins provide a mechanism for mapping values + specified in <filename>.wks</filename> files using the + <filename>‐‐source</filename> keyword to a + particular plugin implementation that populates a + corresponding partition. + </para> + + <para> + A source plugin is created as a subclass of + <filename>SourcePlugin</filename>. + The plugin file containing it is added to + <filename>scripts/lib/mic/plugins/source/</filename> to + make the plugin implementation available to the + <filename>wic</filename> implementation. + For more information, see + <filename>scripts/lib/mic/pluginbase.py</filename>. + </para> + + <para> + Source plugins can also be implemented and added by + external layers. + As such, any plugins found in a + <filename>scripts/lib/mic/plugins/source/</filename> + directory in an external layer are also made + available. + </para> + + <para> + When the <filename>wic</filename> implementation needs + to invoke a partition-specific implementation, it looks + for the plugin that has the same name as the + <filename>‐‐source</filename> parameter given to + that partition. + For example, if the partition is set up as follows: + <literallayout class='monospaced'> + part /boot ‐‐source bootimg-pcbios ... + </literallayout> + The methods defined as class members of the plugin + having the matching <filename>bootimg-pcbios.name</filename> + class member are used. + </para> + + <para> + To be more concrete, here is the plugin definition that + matches a + <filename>‐‐source bootimg-pcbios</filename> usage, + along with an example + method called by the <filename>wic</filename> implementation + when it needs to invoke an implementation-specific + partition-preparation function: + <literallayout class='monospaced'> + class BootimgPcbiosPlugin(SourcePlugin): + name = 'bootimg-pcbios' + + @classmethod + def do_prepare_partition(self, part, ...) + </literallayout> + If the subclass itself does not implement a function, a + default version in a superclass is located and + used, which is why all plugins must be derived from + <filename>SourcePlugin</filename>. + </para> + + <para> + The <filename>SourcePlugin</filename> class defines the + following methods, which is the current set of methods + that can be implemented or overridden by + <filename>‐‐source</filename> plugins. + Any methods not implemented by a + <filename>SourcePlugin</filename> subclass inherit the + implementations present in the + <filename>SourcePlugin</filename> class. + For more information, see the + <filename>SourcePlugin</filename> source for details: + </para> + + <para> + <itemizedlist> + <listitem><para><emphasis><filename>do_prepare_partition()</filename>:</emphasis> + Called to do the actual content population for a + partition. + In other words, the method prepares the final + partition image that is incorporated into the + disk image. + </para></listitem> + <listitem><para><emphasis><filename>do_configure_partition()</filename>:</emphasis> + Called before + <filename>do_prepare_partition()</filename>. + This method is typically used to create custom + configuration files for a partition (e.g. syslinux or + grub configuration files). + </para></listitem> + <listitem><para><emphasis><filename>do_install_disk()</filename>:</emphasis> + Called after all partitions have been prepared and + assembled into a disk image. + This method provides a hook to allow finalization of a + disk image, (e.g. writing an MBR). + </para></listitem> + <listitem><para><emphasis><filename>do_stage_partition()</filename>:</emphasis> + Special content-staging hook called before + <filename>do_prepare_partition()</filename>. + This method is normally empty.</para> + <para>Typically, a partition just uses the passed-in + parameters (e.g. the unmodified value of + <filename>bootimg_dir</filename>). + However, in some cases things might need to be + more tailored. + As an example, certain files might additionally + need to be taken from + <filename>bootimg_dir + /boot</filename>. + This hook allows those files to be staged in a + customized fashion. + <note> + <filename>get_bitbake_var()</filename> + allows you to access non-standard variables + that you might want to use for this. + </note> + </para></listitem> + </itemizedlist> + </para> + + <para> + This scheme is extensible. + Adding more hooks is a simple matter of adding more + plugin methods to <filename>SourcePlugin</filename> and + derived classes. + The code that then needs to call the plugin methods uses + <filename>plugin.get_source_plugin_methods()</filename> + to find the method or methods needed by the call. + Retrieval of those methods is accomplished + by filling up a dict with keys + containing the method names of interest. + On success, these will be filled in with the actual + methods. + Please see the <filename>wic</filename> + implementation for examples and details. + </para> + </section> + + <section id='openembedded-kickstart-wks-reference'> + <title>OpenEmbedded Kickstart (.wks) Reference</title> + + <para> + The current <filename>wic</filename> implementation supports + only the basic kickstart partitioning commands: + <filename>partition</filename> (or <filename>part</filename> + for short) and <filename>bootloader</filename>. + <note> + Future updates will implement more commands and options. + If you use anything that is not specifically + supported, results can be unpredictable. + </note> + </para> + + <para> + The following is a list of the commands, their syntax, + and meanings. + The commands are based on the Fedora + kickstart versions but with modifications to + reflect <filename>wic</filename> capabilities. + You can see the original documentation for those commands + at the following links: + <itemizedlist> + <listitem><para> + <ulink url='http://fedoraproject.org/wiki/Anaconda/Kickstart#part_or_partition'>http://fedoraproject.org/wiki/Anaconda/Kickstart#part_or_partition</ulink> + </para></listitem> + <listitem><para> + <ulink url='http://fedoraproject.org/wiki/Anaconda/Kickstart#bootloader'>http://fedoraproject.org/wiki/Anaconda/Kickstart#bootloader</ulink> + </para></listitem> + </itemizedlist> + </para> + + <section id='command-part-or-partition'> + <title>Command: part or partition</title> + + <para> + This command creates a partition on the system and uses the + following syntax: + <literallayout class='monospaced'> + part <replaceable>mntpoint</replaceable> + </literallayout> + The <filename><replaceable>mntpoint</replaceable></filename> + is where the + partition will be mounted and must be of one of the + following forms: + <itemizedlist> + <listitem><para><filename>/<replaceable>path</replaceable></filename>: + For example, <filename>/</filename>, + <filename>/usr</filename>, and + <filename>/home</filename></para></listitem> + <listitem><para><filename>swap</filename>: + The partition will be used as swap space. + </para></listitem> + </itemizedlist> + </para> + + <para> + Following are the supported options: + <itemizedlist> + <listitem><para><emphasis><filename>‐‐size</filename>:</emphasis> + The minimum partition size in MBytes. + Specify an integer value such as 500. + Do not append the number with "MB". + You do not need this option if you use + <filename>‐‐source</filename>.</para></listitem> + <listitem><para><emphasis><filename>‐‐source</filename>:</emphasis> + This option is a + <filename>wic</filename>-specific option that + names the source of the data that populates + the partition. + The most common value for this option is + "rootfs", but you can use any value that maps to + a valid source plugin. + For information on the source plugins, see the + "<link linkend='openembedded-kickstart-plugins'>Plugins</link>" + section.</para> + <para>If you use + <filename>‐‐source rootfs</filename>, + <filename>wic</filename> creates a partition as + large as needed and to fill it with the contents of + the root filesystem pointed to by the + <filename>-r</filename> command-line option + or the equivalent rootfs derived from the + <filename>-e</filename> command-line + option. + The filesystem type used to create the + partition is driven by the value of the + <filename>‐‐fstype</filename> option + specified for the partition. + See the entry on + <filename>‐‐fstype</filename> that + follows for more information. + </para> + <para>If you use + <filename>‐‐source <replaceable>plugin-name</replaceable></filename>, + <filename>wic</filename> creates a partition as + large as needed and fills it with the contents of + the partition that is generated by the + specified plugin name using the data pointed + to by the <filename>-r</filename> command-line + option or the equivalent rootfs derived from the + <filename>-e</filename> command-line + option. + Exactly what those contents and + filesystem type end up being are dependent + on the given plugin implementation. + </para></listitem> + <listitem><para><emphasis><filename>‐‐ondisk</filename> or <filename>‐‐ondrive</filename>:</emphasis> + Forces the partition to be created on a particular + disk.</para></listitem> + <listitem><para><emphasis><filename>‐‐fstype</filename>:</emphasis> + Sets the file system type for the partition. + Valid values are: + <itemizedlist> + <listitem><para><filename>ext4</filename> + </para></listitem> + <listitem><para><filename>ext3</filename> + </para></listitem> + <listitem><para><filename>ext2</filename> + </para></listitem> + <listitem><para><filename>btrfs</filename> + </para></listitem> + <listitem><para><filename>squashfs</filename> + </para></listitem> + <listitem><para><filename>swap</filename> + </para></listitem> + </itemizedlist></para></listitem> + <listitem><para><emphasis><filename>‐‐fsoptions</filename>:</emphasis> + Specifies a free-form string of options to be + used when mounting the filesystem. + This string will be copied into the + <filename>/etc/fstab</filename> file of the + installed system and should be enclosed in + quotes. + If not specified, the default string + is "defaults". + </para></listitem> + <listitem><para><emphasis><filename>‐‐label label</filename>:</emphasis> + Specifies the label to give to the filesystem to + be made on the partition. + If the given label is already in use by another + filesystem, a new label is created for the + partition.</para></listitem> + <listitem><para><emphasis><filename>‐‐active</filename>:</emphasis> + Marks the partition as active.</para></listitem> + <listitem><para><emphasis><filename>‐‐align (in KBytes)</filename>:</emphasis> + This option is a <filename>wic</filename>-specific + option that says to start a partition on an + x KBytes boundary.</para></listitem> + </itemizedlist> + </para> + </section> + + <section id='command-bootloader'> + <title>Command: bootloader</title> + + <para> + This command specifies how the boot loader should be + configured and supports the following options: + <note> + Bootloader functionality and boot partitions are + implemented by the various + <filename>‐‐source</filename> + plugins that implement bootloader functionality. + The bootloader command essentially provides a means of + modifying bootloader configuration. + </note> + <itemizedlist> + <listitem><para><emphasis><filename>‐‐timeout</filename>:</emphasis> + Specifies the number of seconds before the + bootloader times out and boots the default option. + </para></listitem> + <listitem><para><emphasis><filename>‐‐append</filename>:</emphasis> + Specifies kernel parameters. + These parameters will be added to the syslinux + <filename>APPEND</filename> or + <filename>grub</filename> kernel command line. + </para></listitem> + </itemizedlist> + </para> + </section> + </section> + </section> + <section id='configuring-the-kernel'> <title>Configuring the Kernel</title> @@ -3357,7 +4448,7 @@ You can use the <filename>menuconfig</filename> tool and configuration fragments to make sure your <filename>.config</filename> file is just how you need it. This section describes how to use <filename>menuconfig</filename>, create and use - configuration fragments, and how to interactively tweak your <filename>.config</filename> + configuration fragments, and how to interactively modify your <filename>.config</filename> file to create the leanest kernel configuration file possible. </para> @@ -4040,7 +5131,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> security problems. </para></listitem> <listitem><para> - Pay particular attention to to the security for + Pay particular attention to the security for any web-based administration interface. </para> <para>Web interfaces typically need to perform @@ -4118,7 +5209,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> Use the following line in your <filename>local.conf</filename> file or in your custom distribution configuration file to enable the security - compiler and linker flags to your build: + compiler and linker flags for your build: <literallayout class='monospaced'> require conf/distro/include/security_flags.inc </literallayout> @@ -4133,15 +5224,19 @@ Gateways via their Web Interfaces</ulink>"</emphasis> OpenEmbedded build system to make your images more secure: <itemizedlist> <listitem><para> - Ensure "debug-tweaks" is not listed with + Ensure "debug-tweaks" is not one of your selected <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>. - The default is to enable "debug-tweaks" by adding it - to - <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink> - in <filename>local.conf</filename>. - However, you should comment out the variable or be - sure that it does not have "debug-tweaks" before - producing your final image. + When creating a new project, the default is to provide you + with an initial <filename>local.conf</filename> file that + enables this feature using the + <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink> variable with the line: + <literallayout class='monospaced'> + EXTRA_IMAGE_FEATURES = "debug-tweaks" + </literallayout> + To disable that feature, simply comment out that line in your + <filename>local.conf</filename> file, or + make sure <filename>IMAGE_FEATURES</filename> does not contain + "debug-tweaks" before producing your final image. Among other things, leaving this in place sets the root password as blank, which makes logging in for debugging or inspection easy during @@ -4157,8 +5252,8 @@ Gateways via their Web Interfaces</ulink>"</emphasis> </para> <para> To set up passwords, use the - <filename>extrausers</filename> class, which is the - preferred method. + <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-extrausers'><filename>extrausers</filename></ulink> + class, which is the preferred method. For an example on how to set up both root and user passwords, see the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-extrausers'><filename>extrausers.bbclass</filename></ulink>" @@ -4179,8 +5274,11 @@ Gateways via their Web Interfaces</ulink>"</emphasis> </para></listitem> <listitem><para> Consider enabling a Mandatory Access Control (MAC) - framework (such as SMACK or SELinux) and tuning it + framework such as SMACK or SELinux and tuning it appropriately for your device's usage. + You can find more information in the + <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/meta-selinux/'><filename>meta-selinux</filename></ulink> + layer. </para></listitem> </itemizedlist> </para> @@ -4609,7 +5707,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> section of the Yocto Project Linux Kernel Development Manual and the "<link linkend='creating-config-fragments'>Creating Configuration Fragments</link>" section, which is in this manual.</para></listitem> - <listitem><para><filename>bitbake -u depexp -g <bitbake_target></filename>: + <listitem><para><filename>bitbake -u depexp -g <replaceable>bitbake_target</replaceable></filename>: Using the BitBake command with these options brings up a Dependency Explorer from which you can view file dependencies. @@ -4628,7 +5726,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> libraries, and applications. To change things, you can configure how the packaging happens, which changes the way you build them. - You can also tweak the filesystem itself or select a different + You can also modify the filesystem itself or select a different filesystem. </para> @@ -4636,7 +5734,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> First, find out what is hogging your root filesystem by running the <filename>dirsize.py</filename> script from your root directory: <literallayout class='monospaced'> - $ cd <root-directory-of-image> + $ cd <replaceable>root-directory-of-image</replaceable> $ dirsize.py 100000 > dirsize-100k.log $ cat dirsize-100k.log </literallayout> @@ -4656,8 +5754,8 @@ Gateways via their Web Interfaces</ulink>"</emphasis> One way to see how packages relate to each other is by using the Dependency Explorer UI with the BitBake command: <literallayout class='monospaced'> - $ cd <image-directory> - $ bitbake -u depexp -g <image> + $ cd <replaceable>image-directory</replaceable> + $ bitbake -u depexp -g <replaceable>image</replaceable> </literallayout> Use the interface to select potential packages you wish to eliminate and see their dependency relationships. @@ -4724,7 +5822,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> Linux build directory to get an idea of what is making up the kernel: <literallayout class='monospaced'> - $ cd <top-level-linux-build-directory> + $ cd <replaceable>top-level-linux-build-directory</replaceable> $ ksize.py > ksize.log $ cat ksize.log </literallayout> @@ -4875,6 +5973,192 @@ Gateways via their Web Interfaces</ulink>"</emphasis> </section> </section> + <section id='building-images-for-more-than-one-machine'> + <title>Building Images for More than One Machine</title> + + <para> + A common scenario developers face is creating images for several + different machines that use the same software environment. + In this situation, it is tempting to set the + tunings and optimization flags for each build specifically for + the targeted hardware (i.e. "maxing out" the tunings). + Doing so can considerably add to build times and package feed + maintenance collectively for the machines. + For example, selecting tunes that are extremely specific to a + CPU core used in a system might enable some micro optimizations + in GCC for that particular system but would otherwise not gain + you much of a performance difference across the other systems + as compared to using a more general tuning across all the builds + (e.g. setting + <ulink url='var-DEFAULTTUNE'><filename>DEFAULTTUNE</filename></ulink> + specifically for each machine's build). + Rather than "max out" each build's tunings, you can take steps that + cause the OpenEmbedded build system to reuse software across the + various machines where it makes sense. + </para> + <para> + If build speed and package feed maintenance are considerations, + you should consider the points in this section that can help you + optimize your tunings to best consider build times and package + feed maintenance. + <itemizedlist> + <listitem><para><emphasis>Share the Build Directory:</emphasis> + If at all possible, share the + <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink> + across builds. + The Yocto Project supports switching between different + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> + values in the same <filename>TMPDIR</filename>. + This practice is well supported and regularly used by + developers when building for multiple machines. + When you use the same <filename>TMPDIR</filename> for + multiple machine builds, the OpenEmbedded build system can + reuse the existing native and often cross-recipes for + multiple machines. + Thus, build time decreases. + <note> + If + <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink> + settings change or fundamental configuration settings + such as the filesystem layout, you need to work with + a clean <filename>TMPDIR</filename>. + Sharing <filename>TMPDIR</filename> under these + circumstances might work but since it is not + guaranteed, you should use a clean + <filename>TMPDIR</filename>. + </note> + </para></listitem> + <listitem><para><emphasis>Enable the Appropriate Package Architecture:</emphasis> + By default, the OpenEmbedded build system enables three + levels of package architectures: "all", "tune" or "package", + and "machine". + Any given recipe usually selects one of these package + architectures (types) for its output. + Depending for what a given recipe creates packages, making + sure you enable the appropriate package architecture can + directly impact the build time.</para> + <para>A recipe that just generates scripts can enable + "all" architecture because there are no binaries to build. + To specifically enable "all" architecture, be sure your + recipe inherits the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-allarch'><filename>allarch</filename></ulink> + class. + This class is useful for "all" architectures because it + configures many variables so packages can be used across + multiple architectures.</para> + <para>If your recipe needs to generate packages that are + machine-specific or when one of the build or runtime + dependencies is already machine-architecture dependent, + which makes your recipe also machine-architecture dependent, + make sure your recipe enables the "machine" package + architecture through the + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ARCH'><filename>MACHINE_ARCH</filename></ulink> + variable: + <literallayout class='monospaced'> + PACKAGE_ARCH = "${MACHINE_ARCH}" + </literallayout> + When you do not specifically enable a package + architecture through the + <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink>, + The OpenEmbedded build system defaults to the + <ulink url='&YOCTO_DOCS_REF_URL;#var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></ulink> + setting: + <literallayout class='monospaced'> + PACKAGE_ARCH = "${TUNE_PKGARCH}" + </literallayout> + </para></listitem> + <listitem><para><emphasis>Choose a Generic Tuning File if Possible:</emphasis> + Some tunes are more generic and can run on multiple targets + (e.g. an <filename>armv5</filename> set of packages could + run on <filename>armv6</filename> and + <filename>armv7</filename> processors in most cases). + Similarly, <filename>i486</filename> binaries could work + on <filename>i586</filename> and higher processors. + You should realize, however, that advances on newer + processor versions would not be used.</para> + <para>If you select the same tune for several different + machines, the OpenEmbedded build system reuses software + previously built, thus speeding up the overall build time. + Realize that even though a new sysroot for each machine is + generated, the software is not recompiled and only one + package feed exists. + </para></listitem> + <listitem><para><emphasis>Manage Granular Level Packaging:</emphasis> + Sometimes cases exist where injecting another level + of package architecture beyond the three higher levels + noted earlier can be useful. + For example, consider the <filename>emgd</filename> + graphics stack in the + <filename>meta-intel</filename> layer. + In this layer, a subset of software exists that is + compiled against something different from the rest of the + generic packages. + You can examine the key code in the + <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi'>Source Repositories</ulink> + "daisy" branch in + <filename>classes/emgd-gl.bbclass</filename>. + For a specific set of packages, the code redefines + <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink>. + <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_EXTRA_ARCHS'><filename>PACKAGE_EXTRA_ARCHS</filename></ulink> + is then appended with this extra tune name in + <filename>meta-intel-emgd.inc</filename>. + The result is that when searching for packages, the + build system uses a four-level search and the packages + in this new level are preferred as compared to the standard + tune. + The overall result is that the build system reuses most + software from the common tune except for specific cases + as needed. + </para></listitem> + <listitem><para><emphasis>Use Tools to Debug Issues:</emphasis> + Sometimes you can run into situations where software is + being rebuilt when you think it should not be. + For example, the OpenEmbedded build system might not be + using shared state between machines when you think it + should be. + These types of situations are usually due to references + to machine-specific variables such as + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>, + <ulink url='&YOCTO_DOCS_REF_URL;#var-SERIAL_CONSOLE'><filename>SERIAL_CONSOLE</filename></ulink>, + <ulink url='&YOCTO_DOCS_REF_URL;#var-XSERVER'><filename>XSERVER</filename></ulink>, + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></ulink>, + and so forth in code that is supposed to only be + tune-specific or when the recipe depends + (<ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>, + <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>, + <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>, + <ulink url='&YOCTO_DOCS_REF_URL;#var-RSUGGESTS'><filename>RSUGGESTS</filename></ulink>, + and so forth) on some other recipe that already has + <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink> + defined as "${MACHINE_ARCH}". + <note> + Patches to fix any issues identified are most welcome + as these issues occasionally do occur. + </note></para> + <para>For such cases, you can use some tools to help you + sort out the situation: + <itemizedlist> + <listitem><para><emphasis><filename>sstate-diff-machines.sh</filename>:</emphasis> + You can find this tool in the + <filename>scripts</filename> directory of the + Source Repositories. + See the comments in the script for information on + how to use the tool. + </para></listitem> + <listitem><para><emphasis>BitBake's "-S printdiff" Option:</emphasis> + Using this option causes BitBake to try to + establish the closest signature match it can + (e.g. in the shared state cache) and then run + <filename>bitbake-diffsigs</filename> over the + matches to determine the stamps and delta where + these two stamp trees diverge. + </para></listitem> + </itemizedlist> + </para></listitem> + </itemizedlist> + </para> + </section> + <section id='working-with-packages'> <title>Working with Packages</title> @@ -5075,7 +6359,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> For this scenario, you need to start the PR Service using the <filename>bitbake-prserv</filename> command: <literallayout class='monospaced'> - bitbake-prserv ‐‐host <ip> ‐‐port <port> ‐‐start + bitbake-prserv ‐‐host <replaceable>ip</replaceable> ‐‐port <replaceable>port</replaceable> ‐‐start </literallayout> In addition to hand-starting the service, you need to update the <filename>local.conf</filename> file of each @@ -5594,7 +6878,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> Realize that it is not sufficient to simply do the following: <literallayout class='monospaced'> - $ bitbake <some-package> package-index + $ bitbake <replaceable>some-package</replaceable> package-index </literallayout> This is because BitBake does not properly schedule the <filename>package-index</filename> target fully after any @@ -5614,7 +6898,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> <para> When your build is complete, your packages reside in the - <filename>${TMPDIR}/deploy/<package-format></filename> + <filename>${TMPDIR}/deploy/<replaceable>package-format</replaceable></filename> directory. For example, if <filename>${TMPDIR}</filename> is <filename>tmp</filename> and your selected package type @@ -5712,7 +6996,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> <para> If you are using lighttpd, all you need to do is to provide a link from your - <filename>${TMPDIR}/deploy/<package-format></filename> + <filename>${TMPDIR}/deploy/<replaceable>package-format</replaceable></filename> directory to lighttpd's document-root. You can determine the specifics of your lighttpd installation by looking through its configuration file, @@ -5774,9 +7058,9 @@ Gateways via their Web Interfaces</ulink>"</emphasis> Given this example, issue the following commands on the target: <literallayout class='monospaced'> - # smart channel --add all type=rpm-md baseurl=http://server.name/rpm/all - # smart channel --add i585 type=rpm-md baseurl=http://server.name/rpm/i586 - # smart channel --add qemux86 type=rpm-md baseurl=http://server.name/rpm/qemux86 + # smart channel ‐‐add all type=rpm-md baseurl=http://server.name/rpm/all + # smart channel ‐‐add i585 type=rpm-md baseurl=http://server.name/rpm/i586 + # smart channel ‐‐add qemux86 type=rpm-md baseurl=http://server.name/rpm/qemux86 </literallayout> Also from the target machine, fetch the repository information using this command: @@ -5863,7 +7147,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> a shell script (<filename>run-ptest</filename>) that starts the test. The shell script that starts the test must not contain - the actual test, the script only starts it. + the actual test - the script only starts the test. On the other hand, the test can be anything from a simple shell script that runs a binary and checks the output to an elaborate system of test binaries and data files. @@ -5873,18 +7157,24 @@ Gateways via their Web Interfaces</ulink>"</emphasis> The test generates output in the format used by Automake: <literallayout class='monospaced'> - <result>: <testname> + <replaceable>result</replaceable>: <replaceable>testname</replaceable> </literallayout> where the result can be <filename>PASS</filename>, <filename>FAIL</filename>, or <filename>SKIP</filename>, and the testname can be any identifying string. </para> - <note> - A recipe is "ptest-enabled" if it inherits the - <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-ptest'><filename>ptest</filename></ulink> - class. - </note> + <para> + For a list of Yocto Project recipes that are already + enabled with ptest, see the + <ulink url='https://wiki.yoctoproject.org/wiki/Ptest'>Ptest</ulink> + wiki page. + <note> + A recipe is "ptest-enabled" if it inherits the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-ptest'><filename>ptest</filename></ulink> + class. + </note> + </para> <section id='adding-ptest-to-your-build'> <title>Adding ptest to Your Build</title> @@ -5900,21 +7190,12 @@ Gateways via their Web Interfaces</ulink>"</emphasis> DISTRO_FEATURES_append = " ptest" EXTRA_IMAGE_FEATURES += "ptest-pkgs" </literallayout> - <note> - The OpenEmbedded build system uses the - <ulink url='&YOCTO_DOCS_REF_URL;#var-PTEST_ENABLED'><filename>PTEST_ENABLED</filename></ulink> - variable to see if it should enable ptests during - a build. - This variable is enabled or disabled through your use - of the <filename>DISTRO_FEATURES</filename> variable. - You do not set <filename>PTEST_ENABLED</filename> - directly. - </note> Once your build is complete, the ptest files are installed - into the <filename>/usr/lib/<package>/ptest</filename> + into the + <filename>/usr/lib/<replaceable>package</replaceable>/ptest</filename> directory within the image, where - <filename><package></filename> is the name of the - package. + <filename><replaceable>package</replaceable></filename> + is the name of the package. </para> </section> @@ -5999,7 +7280,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> Consequently, packages that use the unaltered, patched version of <filename>make check</filename> automatically cross-compiles.</para> - <para>However, you still must add a + <para>Regardless, you still must add a <filename>do_compile_ptest</filename> function to build the test suite. Add a function similar to the following to your @@ -6122,7 +7403,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> Use the following BitBake command form to fetch all the necessary sources without starting the build: <literallayout class='monospaced'> - $ bitbake -c fetchall <target> + $ bitbake -c fetchall <replaceable>target</replaceable> </literallayout> This variation of the BitBake command guarantees that you have all the sources for that BitBake target should you @@ -6137,8 +7418,8 @@ Gateways via their Web Interfaces</ulink>"</emphasis> <para> By default, the OpenEmbedded build system uses the - <link linkend='build-directory'>Build Directory</link> to - build source code. + <link linkend='build-directory'>Build Directory</link> when + building source code. The build process involves fetching the source files, unpacking them, and then patching them if necessary before the build takes place. @@ -6172,11 +7453,27 @@ Gateways via their Web Interfaces</ulink>"</emphasis> <filename>local.conf</filename> file: <literallayout class='monospaced'> INHERIT += "externalsrc" - EXTERNALSRC_pn-myrecipe = "/some/path/to/your/source/tree" + EXTERNALSRC_pn-<replaceable>myrecipe</replaceable> = "<replaceable>path-to-your-source-tree</replaceable>" </literallayout> </para> <para> + This next example shows how to accomplish the same thing by setting + <filename>EXTERNALSRC</filename> in the recipe itself or in the + recipe's append file: + <literallayout class='monospaced'> + EXTERNALSRC = "<replaceable>path</replaceable>" + EXTERNALSRC_BUILD = "<replaceable>path</replaceable>" + </literallayout> + <note> + In order for these settings to take effect, you must globally + or locally inherit the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-externalsrc'><filename>externalsrc</filename></ulink> + class. + </note> + </para> + + <para> By default, <filename>externalsrc.bbclass</filename> builds the source code in a directory separate from the external source directory as specified by @@ -6186,7 +7483,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC_BUILD'><filename>EXTERNALSRC_BUILD</filename></ulink> to point to that directory: <literallayout class='monospaced'> - EXTERNALSRC_BUILD_pn-myrecipe = "/path/to/my/source/tree" + EXTERNALSRC_BUILD_pn-<replaceable>myrecipe</replaceable> = "<replaceable>path-to-your-source-tree</replaceable>" </literallayout> </para> </section> @@ -6247,7 +7544,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> <title>Using systemd for the Main Image and Using SysVinit for the Rescue Image</title> <para> - Set the these variables in your distribution configuration + Set these variables in your distribution configuration file as follows: <literallayout class='monospaced'> DISTRO_FEATURES_append = " systemd" @@ -6291,7 +7588,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> Then, you can add the following to your <filename>local.conf</filename>: <literallayout class='monospaced'> - SRCREV_pn-<PN> = "${AUTOREV}" + SRCREV_pn-<replaceable>PN</replaceable> = "${AUTOREV}" </literallayout> <ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink> is the name of the recipe for which you want to enable automatic source @@ -6496,8 +7793,8 @@ Gateways via their Web Interfaces</ulink>"</emphasis> <title>Enabling Tests</title> <para> - Depending on whether you are planning on running tests using - QEMU or on running them on the hardware, you have to take + Depending on whether you are planning to run tests using + QEMU or on the hardware, you have to take different steps to enable the tests. See the following subsections for information on how to enable both types of tests. @@ -6517,7 +7814,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> <listitem><para>Add <filename>NOPASSWD</filename> for your user in <filename>/etc/sudoers</filename> either for - ALL commands or just for + all commands or just for <filename>runqemu-ifup</filename>. You must provide the full path as that can change if you are using multiple clones of the @@ -6559,7 +7856,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> <para> Once you start running the tests, the following happens: - <itemizedlist> + <orderedlist> <listitem><para>A copy of the root filesystem is written to <filename>${WORKDIR}/testimage</filename>. </para></listitem> @@ -6589,7 +7886,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> <filename>unittest</filename> in the task log at <filename>${WORKDIR}/temp/log.do_testimage</filename>. </para></listitem> - </itemizedlist> + </orderedlist> </para> </section> @@ -6637,8 +7934,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> <filename>TEST_TARGET</filename> to an appropriate value. For QEMU, you do not have to change anything, the default value is "QemuTarget". - For running tests on hardware, two options exist: - "SimpleRemoteTarget" and "GummibootTarget". + For running tests on hardware, the following options exist: <itemizedlist> <listitem><para><emphasis>"SimpleRemoteTarget":</emphasis> Choose "SimpleRemoteTarget" if you are going to @@ -6665,6 +7961,45 @@ Gateways via their Web Interfaces</ulink>"</emphasis> "<link linkend='selecting-gummiboottarget'>Selecting GummibootTarget</link>" section, which follows, for more information. </para></listitem> + <listitem><para><emphasis>"BeagleBoneTarget":</emphasis> + Choose "BeagleBoneTarget" if you are deploying + images and running tests on the BeagleBone + "Black" or original "White" hardware. + For information on how to use these tests, see the + comments at the top of the BeagleBoneTarget + <filename>meta-yocto-bsp/lib/oeqa/controllers/beaglebonetarget.py</filename> + file. + </para></listitem> + <listitem><para><emphasis>"EdgeRouterTarget":</emphasis> + Choose "EdgeRouterTarget" is you are deploying + images and running tests on the Ubiquiti Networks + EdgeRouter Lite. + For information on how to use these tests, see the + comments at the top of the EdgeRouterTarget + <filename>meta-yocto-bsp/lib/oeqa/controllers/edgeroutertarget.py</filename> + file. + </para></listitem> + <listitem><para><emphasis>"GrubTarget":</emphasis> + Choose the "supports deploying images and running + tests on any generic PC that boots using GRUB. + For information on how to use these tests, see the + comments at the top of the GrubTarget + <filename>meta-yocto-bsp/lib/oeqa/controllers/grubtarget.py</filename> + file. + </para></listitem> + <listitem><para><emphasis>"<replaceable>your-target</replaceable>":</emphasis> + Create your own custom target if you want to run + tests when you are deploying images and running + tests on a custom machine within your BSP layer. + To do this, you need to add a Python unit that + defines the target class under + <filename>lib/oeqa/controllers/</filename> within + your layer. + You must also provide an empty + <filename>__init__.py</filename>. + For examples, see files in + <filename>meta-yocto-bsp/lib/oeqa/controllers/</filename>. + </para></listitem> </itemizedlist> </para> </section> @@ -6716,7 +8051,8 @@ Gateways via their Web Interfaces</ulink>"</emphasis> <filename>kmod</filename>). </para></listitem> <listitem><para>Uses a custom - initramfs image with a custom installer. + Initial RAM Disk (initramfs) image with a + custom installer. A normal image that you can install usually creates a single rootfs partition. This image uses another installer that @@ -6774,10 +8110,14 @@ Gateways via their Web Interfaces</ulink>"</emphasis> </para></listitem> </orderedlist> </para> + </section> + + <section id='power-control'> + <title>Power Control</title> <para> - Here is some additional information regarding running - "GummibootTarget" as your test target: + For most hardware targets other than SimpleRemoteTarget, + you can control power: <itemizedlist> <listitem><para> You can use @@ -6796,7 +8136,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> In this example, the expect script does the following: <literallayout class='monospaced'> - ssh test@10.11.12.1 "pyctl nuc1 <arg>" + ssh test@10.11.12.1 "pyctl nuc1 <replaceable>arg</replaceable>" </literallayout> It then runs a Python script that controls power for a label called <filename>nuc1</filename>. @@ -6822,6 +8162,63 @@ Gateways via their Web Interfaces</ulink>"</emphasis> some manual interaction is okay from time to time. </para></listitem> </itemizedlist> + If you have no hardware to automatically perform power + control but still wish to experiment with automated + hardware testing, you can use the dialog-power-control + script that shows a dialog prompting you to perform the + required power action. + This script requires either KDialog or Zenity to be + installed. + To use this script, set the + <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_POWERCONTROL_CMD'><filename>TEST_POWERCONTROL_CMD</filename></ulink> + variable as follows: + <literallayout class='monospaced'> + TEST_POWERCONTROL_CMD = "${COREBASE}/scripts/contrib/dialog-power-control" + </literallayout> + </para> + </section> + + <section id='serial-console-connection'> + <title>Serial Console Connection</title> + + <para> + For test target classes requiring a serial console + to interact with the bootloader (e.g. BeagleBoneTarget, + EdgeRouterTarget, and GrubTarget), you need to + specify a command to use to connect to the serial console + of the target machine by using the + <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_POWERCONTROL_CMD'><filename>TEST_POWERCONTROL_CMD</filename></ulink> + variable and optionally the + <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_SERIALCONTROL_EXTRA_ARGS'><filename>TEST_SERIALCONTROL_EXTRA_ARGS</filename></ulink> + variable. + </para> + + <para> + These cases could be a serial terminal program if the + machine is connected to a local serial port, or a + <filename>telnet</filename> or + <filename>ssh</filename> command connecting to a remote + console server. + Regardless of the case, the command simply needs to + connect to the serial console and forward that connection + to standard input and output as any normal terminal + program does. + For example, to use the picocom terminal program on + serial device <filename>/dev/ttyUSB0</filename> + at 115200bps, you would set the variable as follows: + <literallayout class='monospaced'> + TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200" + </literallayout> + For local devices where the serial port device disappears + when the device reboots, an additional "serdevtry" wrapper + script is provided. + To use this wrapper, simply prefix the terminal command + with + <filename>${COREBASE}/scripts/contrib/serdevtry</filename>: + <literallayout class='monospaced'> + TEST_SERIALCONTROL_CMD = "${COREBASE}/scripts/contrib/serdevtry picocom -b +115200 /dev/ttyUSB0" + </literallayout> </para> </section> </section> @@ -6859,7 +8256,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> </literallayout> Next, use BitBake to run the tests: <literallayout class='monospaced'> - bitbake -c testimage <image> + bitbake -c testimage <replaceable>image</replaceable> </literallayout></para></listitem> </itemizedlist> </para> @@ -6881,7 +8278,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> <ulink url='&YOCTO_DOCS_REF_URL;#var-BBPATH'><filename>BBPATH</filename></ulink> in the <filename>local.conf</filename> file as normal. Be sure that tests reside in - <filename><layer>/lib/oeqa/runtime</filename>. + <filename><replaceable>layer</replaceable>/lib/oeqa/runtime</filename>. <note> Be sure that module names do not collide with module names used in the default set of test modules in @@ -6927,7 +8324,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> <listitem><para>The default tests for the image are defined as: <literallayout class='monospaced'> - DEFAULT_TEST_SUITES_pn-<image> = "ping ssh df connman syslog xorg scp vnc date rpm smart dmesg" + DEFAULT_TEST_SUITES_pn-<replaceable>image</replaceable> = "ping ssh df connman syslog xorg scp vnc date rpm smart dmesg" </literallayout></para></listitem> <listitem><para>Add your own test to the list of the by using the following: @@ -6958,7 +8355,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> </para> <para> - If you image is already built, make sure the following are set + If your image is already built, make sure the following are set in your <filename>local.conf</filename> file. Be sure to provide the IP address you need: <literallayout class='monospaced'> @@ -6979,22 +8376,6 @@ Gateways via their Web Interfaces</ulink>"</emphasis> </para> <para> - The exported data (i.e. <filename>testdata.json</filename>) - contains paths to the Build Directory. - Thus, the contents of the directory can be moved - to another machine as long as you update some paths in the - JSON. - Usually you only care about the - ${DEPLOY_DIR}/rpm directory (assuming the RPM and Smart tests - are enabled). - Consequently, running the tests on other machine - means that you have to move the contents and call - <filename>runexported</filename> with "--deploy-dir PATH: - ./runexported.py --deploy-dir /new/path/on/this/machine testdata.json - runexported.py accepts other arguments as well, see --help. - </para> - - <para> You can now run the tests outside of the build environment: <literallayout class='monospaced'> $ cd tmp/testimage/core-image-sato @@ -7008,6 +8389,27 @@ Gateways via their Web Interfaces</ulink>"</emphasis> <filename>runexported.py</filename> </note> </para> + + <para> + The exported data (i.e. <filename>testdata.json</filename>) + contains paths to the Build Directory. + Thus, the contents of the directory can be moved + to another machine as long as you update some paths in the + JSON. + Usually, you only care about the + <filename>${DEPLOY_DIR}/rpm</filename> directory + (assuming the RPM and Smart tests are enabled). + Consequently, running the tests on other machine + means that you have to move the contents and call + <filename>runexported.py</filename> with + "‐‐deploy-dir <replaceable>path</replaceable>" as + follows: + <literallayout class='monospaced'> + ./runexported.py ‐‐deploy-dir /new/path/on/this/machine testdata.json + </literallayout> + <filename>runexported.py</filename> accepts other arguments + as well as described using <filename>‐‐help</filename>. + </para> </section> <section id="qemu-image-writing-new-tests"> @@ -7018,8 +8420,8 @@ Gateways via their Web Interfaces</ulink>"</emphasis> proper place for the build system to find them. New tests for additional functionality outside of the core should be added to the layer that adds the functionality, in - <filename><layer>/lib/oeqa/runtime</filename> (as - long as + <filename><replaceable>layer</replaceable>/lib/oeqa/runtime</filename> + (as long as <ulink url='&YOCTO_DOCS_REF_URL;#var-BBPATH'><filename>BBPATH</filename></ulink> is extended in the layer's <filename>layer.conf</filename> file as normal). @@ -7129,11 +8531,11 @@ Gateways via their Web Interfaces</ulink>"</emphasis> The command returns a tuple: (status, output), which are what their names imply - the return code - of 'cmd' and whatever output + of "cmd" and whatever output it produces. The optional timeout argument represents the number of seconds the - test should wait for 'cmd' to + test should wait for "cmd" to return. If the argument is "None", the test uses the default instance's @@ -7187,7 +8589,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> </para> <tip> - For best results, install DBG (<filename>-dbg</filename>) packages + For best results, install debug (<filename>-dbg</filename>) packages for the applications you are going to debug. Doing so makes extra debug symbols available that give you more meaningful output. @@ -7217,12 +8619,21 @@ Gateways via their Web Interfaces</ulink>"</emphasis> as all the heavy debugging is done by the host GDB. Offloading these processes gives the Gdbserver running on the target a chance to remain small and fast. + <note> + By default, source files are part of the + <filename>*-dbg</filename> packages in order to enable GDB + to show source lines in its output. + You can save further space on the target by setting the + <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_DEBUG_SPLIT_STYLE'><filename>PACKAGE_DEBUG_SPLIT_STYLE</filename></ulink> + variable to "debug-without-src" so that these packages do not + include the source files. + </note> </para> <para> Because the host GDB is responsible for loading the debugging information and - for doing the necessary processing to make actual debugging happen, the - user has to make sure the host can access the unstripped binaries complete + for doing the necessary processing to make actual debugging happen, + you have to make sure the host can access the unstripped binaries complete with their debugging information and also be sure the target is compiled with no optimizations. The host GDB must also have local access to all the libraries used by the debugged program. @@ -7270,7 +8681,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> </para> <para> - Here is an example that when entered from the host + Here is an example, that when entered from the host, connects to the target and launches Gdbserver in order to "debug" a binary named <filename>helloworld</filename>: <literallayout class='monospaced'> @@ -7321,7 +8732,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> </literallayout> Once the binary is built, you can find it here: <literallayout class='monospaced'> - tmp/sysroots/<host-arch>/usr/bin/<target-platform>/<target-abi>-gdb + tmp/sysroots/<replaceable>host-arch</replaceable>/usr/bin/<replaceable>target-platform</replaceable>/<replaceable>target-abi</replaceable>-gdb </literallayout> </para> </section> @@ -7344,12 +8755,12 @@ Gateways via their Web Interfaces</ulink>"</emphasis> <para> You need to add a statement in the - <filename>.gdbinit</filename> file that points to your + <filename>~/.gdbinit</filename> file that points to your root filesystem. Here is an example that points to the root filesystem for an ARM-based target device: <literallayout class='monospaced'> - set sysroot /home/jzhang/sysroot_arm + set sysroot ~/sysroot_arm </literallayout> </para> </section> @@ -7457,7 +8868,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> | DEBUG: SITE files ['endian-little', 'bit-32', 'ix86-common', 'common-linux', 'common-glibc', 'i586-linux', 'common'] | DEBUG: Executing shell function do_compile | NOTE: make -j 16 - | make --no-print-directory all-am + | make ‐‐no-print-directory all-am | /bin/mkdir -p include/near | /bin/mkdir -p include/near | /bin/mkdir -p include/near @@ -7498,7 +8909,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> | ln -s /home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/work/i586-poky-linux/neard/ 0.14-r0/neard-0.14/include/dbus.h include/near/dbus.h | ./src/genbuiltin nfctype1 nfctype2 nfctype3 nfctype4 p2p > src/builtin.h - | i586-poky-linux-gcc -m32 -march=i586 --sysroot=/home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/ + | i586-poky-linux-gcc -m32 -march=i586 ‐‐sysroot=/home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/ build/build/tmp/sysroots/qemux86 -DHAVE_CONFIG_H -I. -I./include -I./src -I./gdbus -I/home/pokybuild/ yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/sysroots/qemux86/usr/include/glib-2.0 -I/home/pokybuild/yocto-autobuilder/yocto-slave/nightly-x86/build/build/tmp/sysroots/qemux86/usr/ @@ -7573,7 +8984,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> Here is some abbreviated, sample output with the missing dependency clearly visible at the end: <literallayout class='monospaced'> - i586-poky-linux-gcc -m32 -march=i586 --sysroot=/home/scott-lenovo/...... + i586-poky-linux-gcc -m32 -march=i586 ‐‐sysroot=/home/scott-lenovo/...... . . . @@ -7637,7 +9048,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> </literallayout> The final thing you need to do to implement the fix in the build is to update the "neard" recipe (i.e. - <filename>neard-0.14.bb</filename> so that the + <filename>neard-0.14.bb</filename>) so that the <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> statement includes the patch file. The recipe file is in the folder above the patch. @@ -7850,19 +9261,20 @@ Gateways via their Web Interfaces</ulink>"</emphasis> </para> <note><title>Notes</title> - <para> - For information on how to delete information from the Toaster - database, see the - <ulink url='https://wiki.yoctoproject.org/wiki/Toaster#Deleting_a_Build_from_the_Toaster_Database'>Deleting a Build from the Toaster Database</ulink> - wiki page. - </para> - - <para> - For information on how to set up an instance of Toaster on - a remote host, see the - <ulink url='https://wiki.yoctoproject.org/wiki/Toaster#Setting_up_a_Toaster_Instance_on_a_Remote_Host'>Setting Up a Toaster Instance on a Remote Host</ulink> - wiki page. - </para> + <itemizedlist> + <listitem><para> + For information on how to delete information from the + Toaster database, see the + <ulink url='https://wiki.yoctoproject.org/wiki/Toaster#Deleting_a_Build_from_the_Toaster_Database'>Deleting a Build from the Toaster Database</ulink> + wiki page. + </para></listitem> + <listitem><para> + For information on how to set up an instance of Toaster + on a remote host, see the + <ulink url='https://wiki.yoctoproject.org/wiki/Toaster#Setting_up_a_Toaster_Instance_on_a_Remote_Host'>Setting Up a Toaster Instance on a Remote Host</ulink> + wiki page. + </para></listitem> + </itemizedlist> </note> </section> @@ -7932,7 +9344,8 @@ Gateways via their Web Interfaces</ulink>"</emphasis> takes place. You can gain access to the symbols by using "dbg-pkgs" in the <filename>IMAGE_FEATURES</filename> variable or by - installing the appropriate DBG (<filename>-dbg</filename>) packages. + installing the appropriate debug (<filename>-dbg</filename>) + packages. </para> <para> @@ -7966,14 +9379,14 @@ Gateways via their Web Interfaces</ulink>"</emphasis> <para> <literallayout class='monospaced'> - # opcontrol --reset - # opcontrol --start --separate=lib --no-vmlinux -c 5 + # opcontrol ‐‐reset + # opcontrol ‐‐start ‐‐separate=lib ‐‐no-vmlinux -c 5 . . [do whatever is being profiled] . . - # opcontrol --stop + # opcontrol ‐‐stop $ opreport -cl </literallayout> </para> @@ -7986,7 +9399,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> five levels deep. <note> To profile the kernel, you would specify the - <filename>--vmlinux=/path/to/vmlinux</filename> option. + <filename>‐‐vmlinux=/path/to/vmlinux</filename> option. The <filename>vmlinux</filename> file is usually in the source directory in the <filename>/boot/</filename> directory and must match the running kernel. </note> @@ -8049,7 +9462,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> With this connection, you just need to run "oprofile-server" on the device. By default, OProfile listens on port 4224. <note> - You can change the port using the <filename>--port</filename> command-line + You can change the port using the <filename>‐‐port</filename> command-line option. </note> </para> @@ -8106,8 +9519,8 @@ Gateways via their Web Interfaces</ulink>"</emphasis> If you wish to perform kernel profiling, you need to be sure a <filename>vmlinux</filename> file that matches the running kernel is available. In the source directory, that file is usually located in - <filename>/boot/vmlinux-KERNELVERSION</filename>, where - <filename>KERNEL-version</filename> is the version of the kernel. + <filename>/boot/vmlinux-<replaceable>kernelversion</replaceable></filename>, where + <filename><replaceable>kernelversion</replaceable></filename> is the version of the kernel. The OpenEmbedded build system generates separate <filename>vmlinux</filename> packages for each kernel it builds. Thus, it should just be a question of making sure a matching package is @@ -8139,14 +9552,14 @@ Gateways via their Web Interfaces</ulink>"</emphasis> If network access to the target is unavailable, you can generate an archive for processing in <filename>oprofile-viewer</filename> as follows: <literallayout class='monospaced'> - # opcontrol --reset - # opcontrol --start --separate=lib --no-vmlinux -c 5 + # opcontrol ‐‐reset + # opcontrol ‐‐start ‐‐separate=lib ‐‐no-vmlinux -c 5 . . [do whatever is being profiled] . . - # opcontrol --stop + # opcontrol ‐‐stop # oparchive -o my_archive </literallayout> </para> @@ -8209,7 +9622,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> <note> The Yocto Project generates a license manifest during image creation that is located - in <filename>${DEPLOY_DIR}/licenses/<image_name-datestamp></filename> + in <filename>${DEPLOY_DIR}/licenses/<replaceable>image_name-datestamp</replaceable></filename> to assist with any audits. </note> </para> diff --git a/documentation/dev-manual/dev-manual-customization.xsl b/documentation/dev-manual/dev-manual-customization.xsl index 470f8bdb48..5dd425c810 100644 --- a/documentation/dev-manual/dev-manual-customization.xsl +++ b/documentation/dev-manual/dev-manual-customization.xsl @@ -1,7 +1,7 @@ <?xml version='1.0'?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0"> - <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl" /> + <xsl:import href="http://docbook.sourceforge.net/release/xsl/1.76.1/xhtml/docbook.xsl" /> <xsl:include href="../template/permalinks.xsl"/> <xsl:include href="../template/section.title.xsl"/> diff --git a/documentation/dev-manual/dev-manual-intro.xml b/documentation/dev-manual/dev-manual-intro.xml index f3cf489f5b..21fba29670 100644 --- a/documentation/dev-manual/dev-manual-intro.xml +++ b/documentation/dev-manual/dev-manual-intro.xml @@ -39,8 +39,11 @@ <link linkend='metadata'>Metadata</link>. A good example is Angstrom, which has had a distribution based on the Yocto Project since its inception. - Other examples include commercial distributions like - Wind River Linux, Mentor Embedded Linux, and ENEA Linux. + Other examples include commercial distributions like + <ulink url='https://www.yoctoproject.org/organization/wind-river-systems'>Wind River Linux</ulink>, + <ulink url='https://www.yoctoproject.org/organization/mentor-graphics'>Mentor Embedded Linux</ulink>, + <ulink url='https://www.yoctoproject.org/organization/enea-ab'>ENEA Linux</ulink> + and <ulink url='https://www.yoctoproject.org/ecosystem/member-organizations'>others</ulink>. See the "<link linkend='creating-your-own-distribution'>Creating Your Own Distribution</link>" section for more information. </note> @@ -64,6 +67,11 @@ generally used during image development for embedded devices. </para></listitem> + <listitem><para>Information on using the Yocto Project + integration of the QuickEMUlator (QEMU), which lets you + simulate running on hardware an image you have built using + the OpenEmbedded build system. + </para></listitem> <listitem><para>Many references to other sources of related information.</para></listitem> </itemizedlist> @@ -104,12 +112,16 @@ <itemizedlist> <listitem><para><emphasis><ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>: </emphasis> The home page for the Yocto Project provides lots of information on the project - as well as links to software and documentation.</para></listitem> + as well as links to software and documentation. + </para></listitem> <listitem><para><emphasis> - <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>:</emphasis> This short document lets you get started - with the Yocto Project and quickly begin building an image.</para></listitem> + <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>:</emphasis> + This short document lets you get started + with the Yocto Project and quickly begin building an image. + </para></listitem> <listitem><para><emphasis> - <ulink url='&YOCTO_DOCS_REF_URL;'>Yocto Project Reference Manual</ulink>:</emphasis> This manual is a reference + <ulink url='&YOCTO_DOCS_REF_URL;'>Yocto Project Reference Manual</ulink>:</emphasis> + This manual is a reference guide to the OpenEmbedded build system, which is based on BitBake. The build system is sometimes referred to as "Poky". </para></listitem> @@ -117,11 +129,13 @@ <ulink url='&YOCTO_DOCS_ADT_URL;'>Yocto Project Application Developer's Guide</ulink>:</emphasis> This guide provides information that lets you get going with the Application Development Toolkit (ADT) and stand-alone cross-development toolchains to - develop projects using the Yocto Project.</para></listitem> + develop projects using the Yocto Project. + </para></listitem> <listitem><para><emphasis> <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>:</emphasis> This guide defines the structure for BSP components. - Having a commonly understood structure encourages standardization.</para></listitem> + Having a commonly understood structure encourages standardization. + </para></listitem> <listitem><para><emphasis> <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>:</emphasis> This manual describes how to work with Linux Yocto kernels as well as provides a bit @@ -134,23 +148,34 @@ </para></listitem> <listitem><para><emphasis> <ulink url='http://www.youtube.com/watch?v=3ZlOu-gLsh0'> - Eclipse IDE Yocto Plug-in</ulink>:</emphasis> A step-by-step instructional video that + Eclipse IDE Yocto Plug-in</ulink>:</emphasis> + A step-by-step instructional video that demonstrates how an application developer uses Yocto Plug-in features within - the Eclipse IDE.</para></listitem> + the Eclipse IDE. + </para></listitem> <listitem><para><emphasis> <ulink url='&YOCTO_WIKI_URL;/wiki/FAQ'>FAQ</ulink>:</emphasis> - A list of commonly asked questions and their answers.</para></listitem> + A list of commonly asked questions and their answers. + </para></listitem> <listitem><para><emphasis> <ulink url='&YOCTO_RELEASE_NOTES;'>Release Notes</ulink>:</emphasis> Features, updates and known issues for the current - release of the Yocto Project.</para></listitem> + release of the Yocto Project. + </para></listitem> <listitem><para><emphasis> - <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'> - Hob</ulink>:</emphasis> A graphical user interface for BitBake. - Hob's primary goal is to enable a user to perform common tasks more easily.</para></listitem> + <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink>:</emphasis> + A graphical user interface for BitBake. + Hob's primary goal is to enable a user to perform common tasks more easily. + </para></listitem> <listitem><para><emphasis> - <ulink url='&YOCTO_HOME_URL;/download/build-appliance-0'> - Build Appliance</ulink>:</emphasis> A virtual machine that + <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/toaster'>Toaster</ulink>:</emphasis> + An Application Programming Interface (API) and web-based + interface to the OpenEmbedded build system, which uses + BitBake, that reports build information. + </para></listitem> + <listitem><para><emphasis> + <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/build-appliance'>Build Appliance</ulink>:</emphasis> + A virtual machine that enables you to build and boot a custom embedded Linux image with the Yocto Project using a non-Linux development system. </para></listitem> @@ -158,46 +183,54 @@ <ulink url='&YOCTO_BUGZILLA_URL;'>Bugzilla</ulink>:</emphasis> The bug tracking application the Yocto Project uses. If you find problems with the Yocto Project, you should report them using this - application.</para></listitem> - <listitem><para><emphasis> - Yocto Project Mailing Lists:</emphasis> To subscribe to the Yocto Project mailing + application. + </para></listitem> + <listitem><para><emphasis>Yocto Project Mailing Lists:</emphasis> + To subscribe to the Yocto Project mailing lists, click on the following URLs and follow the instructions: <itemizedlist> - <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'></ulink> for a - Yocto Project Discussions mailing list.</para></listitem> - <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/poky'></ulink> for a - Yocto Project Discussions mailing list about the + <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'></ulink> + for a Yocto Project Discussions mailing list. + </para></listitem> + <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/poky'></ulink> + for a Yocto Project Discussions mailing list about the OpenEmbedded build system (Poky). </para></listitem> <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/yocto-announce'></ulink> for a mailing list to receive official Yocto Project announcements - as well as Yocto Project milestones.</para></listitem> - <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo'></ulink> for a - listing of all public mailing lists on <filename>lists.yoctoproject.org</filename>. + as well as Yocto Project milestones. + </para></listitem> + <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo'></ulink> + for a listing of all public mailing lists on + <filename>lists.yoctoproject.org</filename>. </para></listitem> </itemizedlist></para></listitem> <listitem><para><emphasis>Internet Relay Chat (IRC):</emphasis> Two IRC channels on freenode are available for Yocto Project and Poky discussions: <filename>#yocto</filename> and - <filename>#poky</filename>, respectively.</para></listitem> + <filename>#poky</filename>, respectively. + </para></listitem> <listitem><para><emphasis> <ulink url='&OE_HOME_URL;'>OpenEmbedded</ulink>:</emphasis> The build system used by the Yocto Project. This project is the upstream, generic, embedded distribution from which the Yocto Project derives its build system (Poky) - and to which it contributes.</para></listitem> + and to which it contributes. + </para></listitem> <listitem><para><emphasis> - <ulink url='http://developer.berlios.de/projects/bitbake/'> - BitBake</ulink>:</emphasis> The tool used by the OpenEmbedded build system - to process project metadata.</para></listitem> + <ulink url='http://www.openembedded.org/wiki/BitBake'>BitBake</ulink>:</emphasis> + The tool used by the OpenEmbedded build system + to process project metadata. + </para></listitem> <listitem><para><emphasis> <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual:</ulink></emphasis> A comprehensive guide to the BitBake tool. If you want information on BitBake, see this manual. </para></listitem> <listitem><para><emphasis> - <ulink url='http://wiki.qemu.org/Index.html'>Quick EMUlator (QEMU)</ulink>: - </emphasis> An open-source machine emulator and virtualizer.</para></listitem> + <ulink url='http://wiki.qemu.org/Index.html'>Quick EMUlator (QEMU)</ulink>:</emphasis> + An open-source machine emulator and virtualizer. + </para></listitem> </itemizedlist> </para> </section> diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml index a05a5559f1..43c31b8405 100644 --- a/documentation/dev-manual/dev-manual-model.xml +++ b/documentation/dev-manual/dev-manual-model.xml @@ -70,7 +70,7 @@ <title>Developing a Board Support Package (BSP)</title> <para> - A BSP is a package of recipes that, when applied during a build, results in + A BSP is a collection of recipes that, when applied during a build, results in an image that you can run on a particular board. Thus, the package when compiled into the new image, supports the operation of the board. </para> @@ -156,15 +156,21 @@ Yocto Project Board Support Package (BSP) Developer's Guide.</para> <note>Five BSPs exist that are part of the Yocto Project release: <filename>genericx86</filename>, <filename>genericx86-64</filename>, - <filename>beaglebone</filename>, - <filename>mpc8315e</filename>, and <filename>edgerouter</filename>. + <filename>beaglebone</filename> (ARM), + <filename>mpc8315e</filename> (PowerPC), + and <filename>edgerouter</filename> (MIPS). The recipes and configurations for these five BSPs are located and dispersed within the <link linkend='source-directory'>Source Directory</link>. - On the other hand, BSP layers for Crown Bay, + On the other hand, the <filename>meta-intel</filename> layer + contains BSP layers for many supported BSPs (e.g. Crystal Forest, Emenlow, Fish River Island 2, Haswell, - Jasper Forest, NUC DC3217IYE, - Romley, Sugar Bay, and tlk exist in their own separate layers - within the larger <filename>meta-intel</filename> layer.</note> + Jasper Forest, and so forth). + Aside from the BSPs in the <filename>meta-intel</filename> + layer, the + <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink> + contain additional BSP layers such as + <filename>meta-minnow</filename> and + <filename>meta-raspberrypi</filename>.</note> <para>When you set up a layer for a new BSP, you should follow a standard layout. This layout is described in the "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout'>Example Filesystem Layout</ulink>" @@ -273,20 +279,35 @@ Within this group, you will find several kernels supported by the Yocto Project: <itemizedlist> - <listitem><para><emphasis><filename>linux-yocto-3.4</filename></emphasis> - The - stable Yocto Project kernel to use with the Yocto Project Release 1.3. This kernel - is based on the Linux 3.4 released kernel.</para></listitem> - <listitem><para><emphasis><filename>linux-yocto-3.8</filename></emphasis> - The - stable Yocto Project kernel to use with the Yocto Project Release 1.4. This kernel - is based on the Linux 3.8 released kernel.</para></listitem> - <listitem><para><emphasis><filename>linux-yocto-3.10</filename></emphasis> - The - stable Yocto Project kernel to use with the Yocto Project Release 1.5. This kernel - is based on the Linux 3.10 released kernel.</para></listitem> - <listitem><para><emphasis><filename>linux-yocto-3.14</filename></emphasis> - The - stable Yocto Project kernel to use with the Yocto Project Release 1.6. This kernel - is based on the Linux 3.14 released kernel.</para></listitem> - <listitem><para><emphasis><filename>linux-yocto-dev</filename></emphasis> - A development - kernel based on the latest upstream release candidate available.</para></listitem> + <listitem><para><emphasis> + <filename>linux-yocto-3.8</filename></emphasis> - The + stable Yocto Project kernel to use with the Yocto + Project Release 1.4. This kernel is based on the + Linux 3.8 released kernel. + </para></listitem> + <listitem><para><emphasis> + <filename>linux-yocto-3.10</filename></emphasis> - The + stable Yocto Project kernel to use with the Yocto + Project Release 1.5. + This kernel is based on the Linux 3.10 released kernel. + </para></listitem> + <listitem><para><emphasis> + <filename>linux-yocto-3.14</filename></emphasis> - The + stable Yocto Project kernel to use with the Yocto + Project Releases 1.6 and 1.7. + This kernel is based on the Linux 3.14 released kernel. + </para></listitem> + <listitem><para><emphasis> + <filename>linux-yocto-3.17</filename></emphasis> - An + additional Yocto Project kernel used with the Yocto + Project Release 1.7. + This kernel is based on the Linux 3.17 released kernel. + </para></listitem> + <listitem><para><emphasis> + <filename>linux-yocto-dev</filename></emphasis> - A + development kernel based on the latest upstream release + candidate available. + </para></listitem> </itemizedlist> </para> @@ -310,7 +331,7 @@ kernel. Thus, everything further to the right in the structure is based on the <filename>linux-yocto-3.4</filename> kernel. - Branch points to right in the figure represent where the + Branch points to the right in the figure represent where the <filename>linux-yocto-3.4</filename> kernel is modified for specific hardware or types of kernels, such as real-time kernels. Each leaf thus represents the end-point for a kernel designed to run on a specific @@ -602,7 +623,11 @@ QEMU through the project's preferences. If you are not using the Eclipse IDE, then you need to deploy the application to the hardware using other methods. - Or, if you are using QEMU, you need to use that tool and load your image in for testing. + Or, if you are using QEMU, you need to use that tool and + load your image in for testing. + See the + "<link linkend='dev-manual-qemu'>Using the Quick EMUlator (QEMU)</link>" + chapter for information on using QEMU. </para></listitem> <listitem><para><emphasis>Test and debug the application</emphasis>: Once your application is deployed, you need to test it. @@ -1075,7 +1100,7 @@ <filename>Build system derived toolchain</filename>, the target kernel you built will be located in the Build Directory in - <filename>tmp/deploy/images/<machine></filename> + <filename>tmp/deploy/images/<replaceable>machine</replaceable></filename> directory. If you selected <filename>Standalone pre-built toolchain</filename>, @@ -1243,6 +1268,11 @@ <para> To start the QEMU emulator from within Eclipse, follow these steps: + <note> + See the + "<link linkend='dev-manual-qemu'>Using the Quick EMUlator (QEMU)</link>" + chapter for more information on using QEMU. + </note> <orderedlist> <listitem><para>Expose and select "External Tools" from the "Run" menu. @@ -1483,7 +1513,7 @@ Project Location. The Yocto project's Metadata files will be put under the directory - <filename><project_location>/<project_name></filename>. + <filename><replaceable>project_location</replaceable>/<replaceable>project_name</replaceable></filename>. If that directory does not exist, you need to check the "Clone from Yocto Git Repository" box, which would execute a <filename>git clone</filename> @@ -1626,7 +1656,11 @@ If you need to separately install and use the QEMU emulator, you can go to <ulink url='http://wiki.qemu.org/Main_Page'>QEMU Home Page</ulink> - to download and learn about the emulator.</para></listitem> + to download and learn about the emulator. + You can see the + "<link linkend='dev-manual-qemu'>Using the Quick EMUlator (QEMU)</link>" + chapter for information on using QEMU within the Yocto + Project.</para></listitem> </orderedlist> </para> </section> @@ -1713,7 +1747,7 @@ <filename>qemux86-poky-linux</filename> machine target system. Furthermore, suppose your recipe is named - <filename>foo_1.3.0-r0.bb</filename>. + <filename>foo_1.3.0.bb</filename>. In this case, the work directory the build system uses to build the package would be as follows: <literallayout class='monospaced'> @@ -1777,7 +1811,7 @@ <filename>do_compile</filename> task as shown in the following example: <literallayout class='monospaced'> - $ bitbake -c compile -f <name_of_package> + $ bitbake -c compile -f <replaceable>name_of_package</replaceable> </literallayout> The <filename>-f</filename> or <filename>--force</filename> option forces the specified task to execute. @@ -1789,9 +1823,9 @@ or <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleanall'><filename>do_cleanall</filename></ulink> tasks using BitBake (i.e. - <filename>bitbake -c clean <name_of_package></filename> + <filename>bitbake -c clean <replaceable>name_of_package</replaceable></filename> and - <filename>bitbake -c cleanall <name_of_package></filename>). + <filename>bitbake -c cleanall <replaceable>name_of_package</replaceable></filename>). Modifications will also disappear if you use the <filename>rm_work</filename> feature as described in the "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" @@ -1882,7 +1916,7 @@ <filename>do_compile</filename> task as shown in the following example: <literallayout class='monospaced'> - $ bitbake -c compile -f <name_of_package> + $ bitbake -c compile -f <replaceable>name_of_package</replaceable> </literallayout> The <filename>-f</filename> or <filename>--force</filename> option forces the specified task to execute. @@ -1916,11 +1950,11 @@ Once you have committed the files, you can use the <filename>git log</filename> command to see your changes: <literallayout class='monospaced'> - $ git commit -m "<commit-summary-message>" + $ git commit -m "<replaceable>commit-summary-message</replaceable>" $ git log </literallayout> <note>The name of the patch file created in the next step is based on your - <filename>commit-summary-message</filename>.</note></para></listitem> + <replaceable>commit-summary-message</replaceable>.</note></para></listitem> <listitem><para><emphasis>Generate the Patch:</emphasis> Once the changes are committed, use the <filename>git format-patch</filename> command to generate a patch file: @@ -1947,7 +1981,7 @@ of the recipe. Here is an example: <literallayout class='monospaced'> - SRC_URI += "file://0001-<commit-summary-message>.patch" + SRC_URI += "file://0001-<replaceable>commit-summary-message</replaceable>.patch" </literallayout></para></listitem> <listitem><para><emphasis>Increment the Recipe Revision Number:</emphasis> Finally, don't forget to 'bump' the diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml index 434a7d15a5..3208bf8d99 100644 --- a/documentation/dev-manual/dev-manual-newbie.xml +++ b/documentation/dev-manual/dev-manual-newbie.xml @@ -41,7 +41,7 @@ </para> <para> - A benchmark example of an open source project is the Linux Kernel, which was initially conceived + A benchmark example of an open source project is the Linux kernel, which was initially conceived and created by Finnish computer science student Linus Torvalds in 1991. Conversely, a good example of a non-open source project is the <trademark class='registered'>Windows</trademark> family of operating @@ -443,7 +443,7 @@ </para></listitem> <listitem><para> Be sure to always work in matching branches for both - the <filename>meta-intel</filename> repository and the + the selected BSP repository and the <link linkend='source-directory'>Source Directory</link> (i.e. <filename>poky</filename>) repository. For example, if you have checked out the "master" branch @@ -508,9 +508,14 @@ The filenames can differ only in the file type suffix used (e.g. <filename>formfactor_0.0.bb</filename> and <filename>formfactor_0.0.bbappend</filename>). </para> - <para>Information in append files overrides the information in the similarly-named recipe file. + <para>Information in append files extends or overrides the + information in the similarly-named recipe file. For an example of an append file in use, see the "<link linkend='using-bbappend-files'>Using .bbappend Files</link>" section. + <note> + Append files can also use wildcard patterns in their version numbers + so they can be applied to more than one version of the underlying recipe file. + </note> </para></listitem> <listitem><para id='bitbake-term'><emphasis>BitBake:</emphasis> The task executor and scheduler used by the OpenEmbedded build @@ -656,8 +661,8 @@ Application Developer's Guide</ulink>. </para></listitem> <listitem><para><emphasis>Image:</emphasis> - An image is the result produced when BitBake processes a given - collection of recipes and related Metadata. + An image is an artifact of the BitBake build process given + a collection of recipes and related Metadata. Images are the binary output that run on specific hardware or QEMU and are used for specific use-cases. For a list of the supported image types that the Yocto Project provides, see the @@ -665,7 +670,7 @@ chapter in the Yocto Project Reference Manual.</para></listitem> <listitem><para id='layer'><emphasis>Layer:</emphasis> A collection of recipes representing the core, a BSP, or an application stack. - For a discussion on BSP Layers, see the + For a discussion specifically on BSP Layers, see the "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>" section in the Yocto Project Board Support Packages (BSP) Developer's Guide.</para></listitem> @@ -686,7 +691,7 @@ This Metadata is found in the <filename>meta</filename> directory of the <link linkend='source-directory'>Source Directory</link>.</para></listitem> <listitem><para><emphasis>Package:</emphasis> - In the context of the Yocto Project, this term refers a + In the context of the Yocto Project, this term refers to a recipe's packaged output produced by BitBake (i.e. a "baked recipe"). A package is generally the compiled binaries produced from the @@ -695,7 +700,7 @@ <para>It is worth noting that the term "package" can, in general, have subtle meanings. For example, the packages referred to in the "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" section are - compiled binaries that when installed add functionality to your Linux + compiled binaries that, when installed, add functionality to your Linux distribution.</para> <para>Another point worth noting is that historically within the Yocto Project, recipes were referred to as packages - thus, the existence of several BitBake @@ -729,12 +734,11 @@ the Yocto Project.</para></listitem> <listitem><para><emphasis>Recipe:</emphasis> A set of instructions for building packages. - A recipe describes where you get source code and which patches - to apply. - Recipes describe dependencies for libraries or for other - recipes, and they also contain configuration and compilation - options. - Recipes contain the logical unit of execution, the software + A recipe describes where you get source code, which patches + to apply, how to configure the source, how to compile it and so on. + Recipes also describe dependencies for libraries or for other + recipes. + Recipes represent the logical unit of execution, the software to build, the images to build, and use the <filename>.bb</filename> file extension. </para></listitem> @@ -774,7 +778,7 @@ folder is also named "poky".</para> <para>While it is not recommended that you use tarball expansion - to setup the Source Directory, if you do, the top-level + to set up the Source Directory, if you do, the top-level directory name of the Source Directory is derived from the Yocto Project release tarball. For example, downloading and unpacking @@ -840,7 +844,7 @@ license is distributed with that software. MIT is also compatible with the GNU General Public License (GPL). Patches to the Yocto Project follow the upstream licensing scheme. - You can find information on the MIT license at + You can find information on the MIT license <ulink url='http://www.opensource.org/licenses/mit-license.php'>here</ulink>. You can find information on the GNU GPL <ulink url='http://www.opensource.org/licenses/LGPL-3.0'> here</ulink>. @@ -972,7 +976,7 @@ Each of these branches represents a specific area of development. The <filename>master</filename> branch represents the current or most recent development. - All other branches represent off-shoots of the <filename>master</filename> + All other branches represent offshoots of the <filename>master</filename> branch. </para> @@ -1024,9 +1028,10 @@ </para> <para> - Some key tags are <filename>dylan-9.0.0</filename>, - <filename>dora-10.0.0</filename>, - and <filename>&DISTRO_NAME;-&POKYVERSION;</filename>. + Some key tags are <filename>dylan-9.0.4</filename>, + <filename>dora-10.0.4</filename>, <filename>daisy-11.0.2</filename>, + <filename>dizzy-12.0.0</filename>, and + <filename>&DISTRO_NAME;-&POKYVERSION;</filename>. These tags represent Yocto Project releases. </para> @@ -1070,7 +1075,9 @@ A good place to look for instruction on a minimal set of Git commands is <ulink url='http://git-scm.com/documentation'>here</ulink>. If you need to download Git, you can do so - <ulink url='http://git-scm.com/download'>here</ulink>. + <ulink url='http://git-scm.com/download'>here</ulink>, although + any reasonably current Linux distribution should already have an + installable package for Git. </para> <para> @@ -1171,10 +1178,10 @@ For the Yocto Project, a key individual called the "maintainer" is responsible for the "master" branch of a given Git repository. The "master" branch is the “upstream” repository where the final builds of the project occur. - The maintainer is responsible for allowing changes in from other developers and for + The maintainer is responsible for accepting changes from other developers and for organizing the underlying branch structure to reflect release strategies and so forth. - <note>For information on finding out who is responsible (maintains) - for a particular area of code, see the + <note>For information on finding out who is responsible for (maintains) + a particular area of code, see the "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>" section. </note> @@ -1328,9 +1335,9 @@ a bug.</para></listitem> <listitem><para>When submitting a new bug, be sure to choose the appropriate Classification, Product, and Component for which the issue was found. - Defects for the Yocto Project fall into one of six classifications: Yocto Project - Components, Infrastructure, Build System & Metadata, Documentation, - QA/Testing, and Runtime. + Defects for the Yocto Project fall into one of seven classifications: + Yocto Project Components, Infrastructure, Build System & Metadata, + Documentation, QA/Testing, Runtime and Hardware. Each of these Classifications break down into multiple Products and, in some cases, multiple Components.</para></listitem> <listitem><para>Use the bug form to choose the correct Hardware and Architecture @@ -1397,7 +1404,7 @@ following command to bring up a short list of all commits against a specific file: <literallayout class='monospaced'> - git shortlog -- <filename> + git shortlog -- <replaceable>filename</replaceable> </literallayout> Just provide the name of the file for which you are interested. The information returned is not ordered by history but does @@ -1517,12 +1524,12 @@ bug references - any commit that addresses a specific bug should use the following form for the detailed description: <literallayout class='monospaced'> - Fixes [YOCTO #<bug-id>] + Fixes [YOCTO #<replaceable>bug-id</replaceable>] - <detailed description of change> + <replaceable>detailed description of change</replaceable> </literallayout></para></listitem> - Where <bug-id> is replaced with the specific bug ID from - the Yocto Project Bugzilla instance. + Where <replaceable>bug-id</replaceable> is replaced with the + specific bug ID from the Yocto Project Bugzilla instance. </itemizedlist> </para> diff --git a/documentation/dev-manual/dev-manual-qemu.xml b/documentation/dev-manual/dev-manual-qemu.xml new file mode 100644 index 0000000000..739fd7104b --- /dev/null +++ b/documentation/dev-manual/dev-manual-qemu.xml @@ -0,0 +1,419 @@ +<!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='dev-manual-qemu'> + +<title>Using the Quick EMUlator (QEMU)</title> + +<para> + Quick EMUlator (QEMU) is an Open Source project the Yocto Project uses + as part of its development "tool set". + As such, the information in this chapter is limited to the + Yocto Project integration of QEMU and not QEMU in general. + For official information and documentation on QEMU, see the + following references: + <itemizedlist> + <listitem><para><emphasis><ulink url='http://wiki.qemu.org/Main_Page'>QEMU Website</ulink>:</emphasis> + The official website for the QEMU Open Source project. + </para></listitem> + <listitem><para><emphasis><ulink url='http://wiki.qemu.org/Manual'>Documentation</ulink>:</emphasis> + The QEMU user manual. + </para></listitem> + </itemizedlist> +</para> + +<para> + This chapter provides an overview of the Yocto Project's integration of + QEMU, a description of how you use QEMU and its various options, running + under a Network File System (NFS) server, and a few tips and tricks you + might find helpful when using QEMU. +</para> + +<section id='qemu-overview'> + <title>Overview</title> + + <para> + Within the context of the Yocto Project, QEMU is an + emulator and virtualization machine that allows you to run a complete + image you have built using the Yocto Project as just another task + on your build system. + QEMU is useful for running and testing images and applications on + supported Yocto Project architectures without having actual hardware. + Among other things, the Yocto Project uses QEMU to run automated + Quality Assurance (QA) tests on final images shipped with each + release. + </para> + + <para> + QEMU is made available with the Yocto Project a number of ways. + The easiest and recommended method for getting QEMU is to run the + ADT installer. For more information on how to make sure you have + QEMU available, see the + "<ulink url='&YOCTO_DOCS_ADT_URL;#the-qemu-emulator'>The QEMU Emulator</ulink>" + section in the Yocto Project Application Developer's Guide. + </para> +</section> + +<section id='qemu-running-qemu'> + <title>Running QEMU</title> + + <para> + Running QEMU involves having your build environment set up, having the + right artifacts available, and understanding how to use the many + options that are available to you when you start QEMU using the + <filename>runqemu</filename> command. + </para> + + <section id='qemu-setting-up-the-environment'> + <title>Setting Up the Environment</title> + + <para> + You run QEMU in the same environment from which you run BitBake. + This means you need to source a build environment script (i.e. + <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> + or + <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>). + </para> + </section> + + <section id='qemu-using-the-runqemu-command'> + <title>Using the <filename>runqemu</filename> Command</title> + + <para> + The basic <filename>runqemu</filename> command syntax is as + follows: + <literallayout class='monospaced'> + $ runqemu [<replaceable>option</replaceable> ] [...] + </literallayout> + Based on what you provide on the command line, + <filename>runqemu</filename> does a good job of figuring out what + you are trying to do. + For example, by default, QEMU looks for the most recently built + image according to the timestamp when it needs to look for an + image. + Minimally, through the use of options, you must provide either + a machine name, a virtual machine image + (<filename>*.vmdk</filename>), or a kernel image + (<filename>*.bin</filename>). + </para> + + <para> + Following is a description of <filename>runqemu</filename> + options you can provide on the command line: + <note><title>Tip</title> + If you do provide some "illegal" option combination or perhaps + you do not provide enough in the way of options, + <filename>runqemu</filename> provides appropriate error + messaging to help you correct the problem. + </note> + <itemizedlist> + <listitem><para><replaceable>QEMUARCH</replaceable>: + The QEMU machine architecture, which must be "qemux86", + "qemux86-64", "qemuarm", "qemumips", "qemumipsel", + “qemumips64", "qemush4", "qemuppc", "qemumicroblaze", + or "qemuzynq". + </para></listitem> + <listitem><para><filename><replaceable>VM</replaceable></filename>: + The virtual machine image, which must be a + <filename>.vmdk</filename> file. + Use this option when you want to boot a + <filename>.vmdk</filename> image. + The image filename you provide must contain one of the + following strings: "qemux86-64", "qemux86", "qemuarm", + "qemumips64", "qemumips", "qemuppc", or "qemush4". + </para></listitem> + <listitem><para><replaceable>ROOTFS</replaceable>: + A root filesystem that has one of the following + filetype extensions: "ext2", "ext3", "ext4", "jffs2", + "nfs", or "btrfs". + If the filename you provide for this option uses “nfs”, it + must provide an explicit root filesystem path. + </para></listitem> + <listitem><para><replaceable>KERNEL</replaceable>: + A kernel image, which is a <filename>.bin</filename> file. + When you provide a <filename>.bin</filename> file, + <filename>runqemu</filename> detects it and assumes the + file is a kernel image. + </para></listitem> + <listitem><para><replaceable>MACHINE</replaceable>: + The architecture of the QEMU machine, which must be one + of the following: "qemux86", + "qemux86-64", "qemuarm", "qemumips", "qemumipsel", + “qemumips64", "qemush4", "qemuppc", "qemumicroblaze", + or "qemuzynq". + The <replaceable>MACHINE</replaceable> and + <replaceable>QEMUARCH</replaceable> options are basically + identical. + If you do not provide a <replaceable>MACHINE</replaceable> + option, <filename>runqemu</filename> tries to determine + it based on other options. + </para></listitem> + <listitem><para><filename>ramfs</filename>: + Indicates you are booting an initial RAM disk (initramfs) + image, which means the <filename>FSTYPE</filename> is + <filename>cpio.gz</filename>. + </para></listitem> + <listitem><para><filename>iso</filename>: + Indicates you are booting an ISO image, which means the + <filename>FSTYPE</filename> is + <filename>.iso</filename>. + </para></listitem> + <listitem><para><filename>nographic</filename>: + Disables the video console, which sets the console to + "ttys0". + </para></listitem> + <listitem><para><filename>serial</filename>: + Enables a serial console on + <filename>/dev/ttyS0</filename>. + </para></listitem> + <listitem><para><filename>biosdir</filename>: + Establishes a custom directory for BIOS, VGA BIOS and + keymaps. + </para></listitem> + <listitem><para><filename>qemuparams=\"<replaceable>xyz</replaceable>\"</filename>: + Specifies custom QEMU parameters. + Use this option to pass options other than the simple + "kvm" and "serial" options. + </para></listitem> + <listitem><para><filename>bootparams=\"<replaceable>xyz</replaceable>\"</filename>: + Specifies custom boot parameters for the kernel. + </para></listitem> + <listitem><para><filename>audio</filename>: + Enables audio in QEMU. + The <replaceable>MACHINE</replaceable> option must be + either "qemux86" or "qemux86-64" in order for audio to be + enabled. + Additionally, the <filename>snd_intel8x0</filename> + or <filename>snd_ens1370</filename> driver must be + installed in linux guest. + </para></listitem> + <listitem><para><filename>slirp</filename>: + Enables "slirp" networking, which is a different way + of networking that does not need root access + but also is not as easy to use or comprehensive + as the default. + </para></listitem> + <listitem><para><filename>kvm</filename>: + Enables KVM when running "qemux86" or "qemux86-64" + QEMU architectures. + For KVM to work, all the following conditions must be met: + <itemizedlist> + <listitem><para> + Your <replaceable>MACHINE</replaceable> must be either + "qemux86" or "qemux86-64". + </para></listitem> + <listitem><para> + Your build host has to have the KVM modules + installed, which are + <filename>/dev/kvm</filename>. + </para></listitem> + <listitem><para> + Your build host has to have virtio net device, which + are <filename>/dev/vhost-net</filename>. + </para></listitem> + <listitem><para> + The build host <filename>/dev/kvm</filename> + directory has to be both writable and readable. + </para></listitem> + <listitem><para> + The build host <filename>/dev/vhost-net</filename> + directory has to be either readable or writable + and “slirp-enabled”. + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para><filename>publicvnc</filename>: + Enables a VNC server open to all hosts. + </para></listitem> + </itemizedlist> + </para> + + <para> + For further understanding regarding option use with + <filename>runqemu</filename>, consider some examples. + </para> + + <para> + This example starts QEMU with + <replaceable>MACHINE</replaceable> set to "qemux86". + Assuming a standard + <link linkend='build-directory'>Build Directory</link>, + <filename>runqemu</filename> automatically finds the + <filename>bzImage-qemux86.bin</filename> image file and + the + <filename>core-image-minimal-qemux86-20140707074611.rootfs.ext3</filename> + (assuming the current build created a + <filename>core-image-minimal</filename> image). + <note> + When more than one image with the same name exists, QEMU finds + and uses the most recently built image according to the + timestamp. + </note> + <literallayout class='monospaced'> + $ runqemu qemux86 + </literallayout> + This example produces the exact same results as the + previous example. + This command, however, specifically provides the image + and root filesystem type. + <literallayout class='monospaced'> + $ runqemu qemux86 core-image-minimal ext3 + </literallayout> + This example specifies to boot an initial RAM disk image + and to enable audio in QEMU. + For this case, <filename>runqemu</filename> set the + internal variable <filename>FSTYPE</filename> to + "cpio.gz". + Also, for audio to be enabled, an appropriate driver must + be installed (see the previous description for the + <filename>audio</filename> option for more information). + <literallayout class='monospaced'> + $ runqemu qemux86 ramfs audio + </literallayout> + This example does not provide enough information for + QEMU to launch. + While the command does provide a root filesystem type, it + must also minimally provide a + <replaceable>MACHINE</replaceable>, + <replaceable>KERNEL</replaceable>, or + <replaceable>VM</replaceable> option. + <literallayout class='monospaced'> + $ runqemu ext3 + </literallayout> + This example specifies to boot a virtual machine image + (<filename>.vmdk</filename> file). + From the <filename>.vmdk</filename>, + <filename>runqemu</filename> determines the QEMU + architecture (<replaceable>MACHINE</replaceable>) to be + "qemux86" and the root filesystem type to be "vmdk". + <literallayout class='monospaced'> + $ runqemu /home/scott-lenovo/vm/core-image-minimal-qemux86.vmdk + </literallayout> + </para> + </section> +</section> + +<section id='qemu-running-under-a-network-file-system-nfs-server'> + <title>Running Under a Network File System (NFS) Server</title> + + <para> + One method for running QEMU is to run it on an NFS server. + This is useful when you need to access the same file system from both + the build and the emulated system at the same time. + It is also worth noting that the system does not need root privileges + to run. + It uses a user space NFS server to avoid that. + This section describes how to set up for running QEMU using an NFS + server and then how you can start and stop the server. + </para> + + <section id='qemu-setting-up-to-use-nfs'> + <title>Setting Up to Use NFS</title> + + <para> + Once you are able to run QEMU in your environment, you can use the + <filename>runqemu-extract-sdk</filename> script, which is located + in the <filename>scripts</filename> directory along with + <filename>runqemu</filename> script. + The <filename>runqemu-extract-sdk</filename> takes a root + file system tarball and extracts it into a location that you + specify. + Then, when you run <filename>runqemu</filename>, you can specify + the location that has the file system to pass it to QEMU. + Here is an example that takes a file system and extracts it to + a directory named <filename>test-nfs</filename>: + <literallayout class='monospaced'> + runqemu-extract-sdk ./tmp/deploy/images/qemux86/core-image-sato-qemux86.tar.bz2 test-nfs + </literallayout> + Once you have extracted the file system, you can run + <filename>runqemu</filename> normally with the additional + location of the file system. + You can then also make changes to the files within + <filename>./test-nfs</filename> and see those changes appear in the + image in real time. + Here is an example using the <filename>qemux86</filename> image: + <literallayout class='monospaced'> + runqemu qemux86 ./test-nfs + </literallayout> + </para> + </section> + + <section id='qemu-starting-and-stopping-nfs'> + <title>Starting and Stopping NFS</title> + + <para> + You can manually start and stop the NFS share using these + commands: + <itemizedlist> + <listitem><para><emphasis><filename>start</filename>:</emphasis> + Starts the NFS share: + <literallayout class='monospaced'> + runqemu-export-rootfs start <replaceable>file-system-location</replaceable> + </literallayout> + </para></listitem> + <listitem><para><emphasis><filename>stop</filename>:</emphasis> + Stops the NFS share: + <literallayout class='monospaced'> + runqemu-export-rootfs stop <replaceable>file-system-location</replaceable> + </literallayout> + </para></listitem> + <listitem><para><emphasis><filename>restart</filename>:</emphasis> + Restarts the NFS share: + <literallayout class='monospaced'> + runqemu-export-rootfs restart <replaceable>file-system-location</replaceable> + </literallayout> + </para></listitem> + </itemizedlist> + </para> + </section> +</section> + +<section id='qemu-tips-and-tricks'> + <title>Tips and Tricks</title> + + <para> + The following list describes things you can do to make running QEMU + in the context of the Yocto Project a better experience: + <itemizedlist> + <listitem><para><emphasis>Switching Between Consoles:</emphasis> + When booting or running QEMU, you can switch between + supported consoles by using + Ctrl+Alt+<replaceable>number</replaceable>. + For example, Ctrl+Alt+3 switches you to the serial console as + long as that console is enabled. + Being able to switch consoles is helpful, for example, if the + main QEMU console breaks for some reason. + <note> + Usually, "2" gets you to the main console and "3" gets you + to the serial console. + </note> + </para></listitem> + <listitem><para><emphasis>Removing the Splash Screen:</emphasis> + You can remove the splash screen when QEMU is booting by + using Alt+left. + Removing the splash screen allows you to see what is happening + in the background. + </para></listitem> + <listitem><para><emphasis>Disabling the Cursor Grab:</emphasis> + The default QEMU integration captures the cursor within the + main window. + It does this since standard mouse devices only provide relative + input and not absolute coordinates. + You then have to break out of the grab using the "Ctrl+Alt" key + combination. + However, the Yocto Project's integration of QEMU enables the + wacom USB touch pad driver by default to allow input of absolute + coordinates. + This default means that the mouse can enter and leave the + main window without the grab taking effect leading to a better + user experience. + </para></listitem> + </itemizedlist> + </para> +</section> + +</chapter> +<!-- +vim: expandtab tw=80 ts=4 +--> diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml index 6ab93f79cf..df29302fdb 100644 --- a/documentation/dev-manual/dev-manual-start.xml +++ b/documentation/dev-manual/dev-manual-start.xml @@ -29,7 +29,7 @@ in the Yocto Project documentation. The Yocto Project provides various ancillary tools for the embedded developer and also features the Sato reference User Interface, which is optimized for - stylus driven, low-resolution screens. + stylus-driven, low-resolution screens. </para> <para> @@ -89,7 +89,9 @@ <link linkend='git'>Git</link> to clone a local copy of the upstream <filename>poky</filename> repository, or by downloading and unpacking a tarball of an official - Yocto Project release.</para> + Yocto Project release. + The preferred method is to create a clone of the repository. + </para> <para>Working from a copy of the upstream repository allows you to contribute back into the Yocto Project or simply work with the latest software on a development branch. @@ -188,42 +190,42 @@ Resolving deltas: 100% (260/260), done. </literallayout></para></listitem> <listitem><para id='supported-board-support-packages-(bsps)'><emphasis>Supported Board Support Packages (BSPs):</emphasis> - The Yocto Project provides a layer called - <filename>meta-intel</filename> and it is maintained in its own - separate Git repository. - The <filename>meta-intel</filename> layer contains many - supported - <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>. - </para> + The Yocto Project supports many BSPs, which are maintained in + their own layers or in layers designed to contain several + BSPs. + To get an idea of machine support through BSP layers, you can + look at the + <ulink url='&YOCTO_RELEASE_DL_URL;/machines'>index of machines</ulink> + for the release.</para> <para>The Yocto Project uses the following BSP layer naming scheme: <literallayout class='monospaced'> - meta-<BSP_name> + meta-<replaceable>bsp_name</replaceable> </literallayout> - where <filename><BSP_name></filename> is the recognized + where <replaceable>bsp_name</replaceable> is the recognized BSP name. Here are some examples: <literallayout class='monospaced'> meta-crownbay meta-emenlow - meta-n450 + meta-raspberrypi </literallayout> See the "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>" section in the Yocto Project Board Support Package (BSP) - Developer's Guide for more information on BSP Layers. - </para> + Developer's Guide for more information on BSP Layers.</para> - <para> + <para>A useful Git repository released with the Yocto + Project is <filename>meta-intel</filename>, which is a + parent layer that contains many supported + <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>. You can locate the <filename>meta-intel</filename> Git repository in the "Yocto Metadata Layers" area of the Yocto Project Source Repositories at - <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>. - </para> + <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.</para> - <para> - Using + <para>Using <link linkend='git'>Git</link> to create a local clone of the upstream repository can be helpful if you are working with BSPs. @@ -250,11 +252,9 @@ remote: Total 8844 (delta 4931), reused 8780 (delta 4867) Receiving objects: 100% (8844/8844), 2.48 MiB | 264 KiB/s, done. Resolving deltas: 100% (4931/4931), done. - </literallayout> - </para> + </literallayout></para> - <para> - The same + <para>The same <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_from_git_checkout_to_meta-intel_BSP'>wiki page</ulink> referenced earlier covers how to set up the <filename>meta-intel</filename> Git repository. @@ -350,6 +350,9 @@ You can find details on all these steps in the "<ulink url='&YOCTO_DOCS_QS_URL;#using-pre-built'>Using Pre-Built Binaries and QEMU</ulink>" section of the Yocto Project Quick Start. + You can learn more about using QEMU with the Yocto Project in the + "<link linkend='dev-manual-qemu'>Using the Quick EMUlator (QEMU)</link>" + section. </para> <para> diff --git a/documentation/dev-manual/dev-manual.xml b/documentation/dev-manual/dev-manual.xml index b89e2b357e..4a7840f5df 100644 --- a/documentation/dev-manual/dev-manual.xml +++ b/documentation/dev-manual/dev-manual.xml @@ -68,9 +68,14 @@ </revision> <revision> <revnumber>1.7</revnumber> - <date>Fall of 2014</date> + <date>October 2014</date> <revremark>Released with the Yocto Project 1.7 Release.</revremark> </revision> + <revision> + <revnumber>1.8</revnumber> + <date>Sometime in 2015</date> + <revremark>Released with the Yocto Project 1.8 Release.</revremark> + </revision> </revhistory> <copyright> @@ -106,6 +111,8 @@ <xi:include href="dev-manual-common-tasks.xml"/> + <xi:include href="dev-manual-qemu.xml"/> + </book> <!-- vim: expandtab tw=80 ts=4 diff --git a/documentation/dev-manual/figures/yp-download.png b/documentation/dev-manual/figures/yp-download.png Binary files differindex 7f1e5ca118..5770be6883 100644 --- a/documentation/dev-manual/figures/yp-download.png +++ b/documentation/dev-manual/figures/yp-download.png diff --git a/documentation/kernel-dev/kernel-dev-advanced.xml b/documentation/kernel-dev/kernel-dev-advanced.xml index 4a6aeb7391..283f483112 100644 --- a/documentation/kernel-dev/kernel-dev-advanced.xml +++ b/documentation/kernel-dev/kernel-dev-advanced.xml @@ -214,7 +214,7 @@ Here is an example that shows a trivial tree of kernel Metadata stored in recipe-space within a BSP layer: <literallayout class='monospaced'> - meta-my_bsp_layer/ + meta-<replaceable>my_bsp_layer</replaceable>/ `-- recipes-kernel `-- linux `-- linux-yocto @@ -370,7 +370,7 @@ of Metadata. The following Metadata file hierarchy is recommended: <literallayout class='monospaced'> - <base>/ + <replaceable>base</replaceable>/ bsp/ cfg/ features/ @@ -513,7 +513,7 @@ patch mypatch.patch patches/mypatch.patch: - <typical-patch> + <replaceable>typical-patch</replaceable> </literallayout> You can create the typical <filename>.patch</filename> file using <filename>diff -Nurp</filename> or @@ -968,37 +968,38 @@ hierarchical branching system similar to what the linux-yocto Linux kernel repositories use: <literallayout class='monospaced'> - <common>/<kernel_type>/<machine> + <replaceable>common</replaceable>/<replaceable>kernel_type</replaceable>/<replaceable>machine</replaceable> </literallayout> </para> <para> If you had two kernel types, "standard" and "small" for - instance, and three machines, the branches in your + instance, three machines, and <replaceable>common</replaceable> + as <filename>mydir</filename>, the branches in your Git repository might look like this: <literallayout class='monospaced'> - common/base - common/standard/base - common/standard/machine_a - common/standard/machine_b - common/standard/machine_c - common/small/base - common/small/machine_a + mydir/base + mydir/standard/base + mydir/standard/machine_a + mydir/standard/machine_b + mydir/standard/machine_c + mydir/small/base + mydir/small/machine_a </literallayout> </para> <para> This organization can help clarify the branch relationships. - In this case, <filename>common/standard/machine_a</filename> - includes everything in <filename>common/base</filename> and - <filename>common/standard/base</filename>. + In this case, <filename>mydir/standard/machine_a</filename> + includes everything in <filename>mydir/base</filename> and + <filename>mydir/standard/base</filename>. The "standard" and "small" branches add sources specific to those kernel types that for whatever reason are not appropriate for the other branches. <note>The "base" branches are an artifact of the way Git manages its data internally on the filesystem: Git will not allow you - to use <filename>common/standard</filename> and - <filename>common/standard/machine_a</filename> because it + to use <filename>mydir/standard</filename> and + <filename>mydir/standard/machine_a</filename> because it would have to create a file and a directory named "standard". </note> </para> diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml index 555c8d8903..58cc98ddff 100644 --- a/documentation/kernel-dev/kernel-dev-common.xml +++ b/documentation/kernel-dev/kernel-dev-common.xml @@ -85,10 +85,10 @@ you are using. For example, if you are modifying the <filename>meta/recipes-kernel/linux/linux-yocto_3.4.bb</filename> - recipe, the append file will typical be located as follows + recipe, the append file will typically be located as follows within your custom layer: <literallayout class='monospaced'> - <your-layer>/recipes-kernel/linux/linux-yocto_3.4.bbappend + <replaceable>your-layer</replaceable>/recipes-kernel/linux/linux-yocto_3.4.bbappend </literallayout> The append file should initially extend the <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink> @@ -107,7 +107,7 @@ described above, you must place the files in your layer in the following area: <literallayout class='monospaced'> - <your-layer>/recipes-kernel/linux/linux-yocto/ + <replaceable>your-layer</replaceable>/recipes-kernel/linux/linux-yocto/ </literallayout> <note>If you are working on a new machine Board Support Package (BSP), be sure to refer to the @@ -502,8 +502,9 @@ you can make them permanent by generating patches and applying them to the <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> - statement as described in section - "<link linkend='applying-patches'>Applying Patches</link>" section. + statement as described in the + "<link linkend='applying-patches'>Applying Patches</link>" + section. If you are not familiar with generating patches, refer to the "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-the-patch'>Creating the Patch</ulink>" section in the Yocto Project Development Manual. diff --git a/documentation/kernel-dev/kernel-dev-customization.xsl b/documentation/kernel-dev/kernel-dev-customization.xsl index bd81da5d8c..8676d66c3a 100644 --- a/documentation/kernel-dev/kernel-dev-customization.xsl +++ b/documentation/kernel-dev/kernel-dev-customization.xsl @@ -1,7 +1,7 @@ <?xml version='1.0'?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0"> - <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl" /> + <xsl:import href="http://docbook.sourceforge.net/release/xsl/1.76.1/xhtml/docbook.xsl" /> <xsl:include href="../template/permalinks.xsl"/> <xsl:include href="../template/section.title.xsl"/> diff --git a/documentation/kernel-dev/kernel-dev-intro.xml b/documentation/kernel-dev/kernel-dev-intro.xml index 297696c965..38ef36de5a 100644 --- a/documentation/kernel-dev/kernel-dev-intro.xml +++ b/documentation/kernel-dev/kernel-dev-intro.xml @@ -110,7 +110,7 @@ The sections that follow provide instructions for completing specific Linux kernel development tasks. These instructions assume you are comfortable working with - <ulink url='http://developer.berlios.de/projects/bitbake/'>BitBake</ulink> + <ulink url='http://openembedded.org/wiki/Bitbake'>BitBake</ulink> recipes and basic open-source development tools. Understanding these concepts will facilitate the process of working with the kernel recipes. diff --git a/documentation/kernel-dev/kernel-dev-maint-appx.xml b/documentation/kernel-dev/kernel-dev-maint-appx.xml index a7c144ff75..a72dcff01b 100644 --- a/documentation/kernel-dev/kernel-dev-maint-appx.xml +++ b/documentation/kernel-dev/kernel-dev-maint-appx.xml @@ -88,7 +88,7 @@ feature description in an <filename>.scc</filename> file whose name follows this format: <literallayout class='monospaced'> - <bsp_name>-<kernel_type>.scc + <replaceable>bsp_name</replaceable>-<replaceable>kernel_type</replaceable>.scc </literallayout> </para></listitem> <listitem><para>Once located, the feature description is either compiled into a simple script @@ -157,7 +157,7 @@ <listitem><para>A BSP build branch exists. This branch has the following form: <literallayout class='monospaced'> - <kernel_type>/<bsp_name> + <replaceable>kernel_type</replaceable>/<replaceable>bsp_name</replaceable> </literallayout></para></listitem> </itemizedlist> @@ -194,7 +194,7 @@ <filename>${MACHINE}</filename> is the metadata name of the machine (BSP) and "kernel_type" is one of the Yocto Project supported kernel types (e.g. "standard"): <literallayout class='monospaced'> - linux-${MACHINE}-<kernel_type>-build + linux-${MACHINE}-<replaceable>kernel_type</replaceable>-build </literallayout> </para> diff --git a/documentation/kernel-dev/kernel-dev.xml b/documentation/kernel-dev/kernel-dev.xml index dddc003ba0..c1b9d53e92 100644 --- a/documentation/kernel-dev/kernel-dev.xml +++ b/documentation/kernel-dev/kernel-dev.xml @@ -53,9 +53,14 @@ </revision> <revision> <revnumber>1.7</revnumber> - <date>Fall of 2014</date> + <date>October 2014</date> <revremark>Released with the Yocto Project 1.7 Release.</revremark> </revision> + <revision> + <revnumber>1.8</revnumber> + <date>Sometime in 2015</date> + <revremark>Released with the Yocto Project 1.8 Release.</revremark> + </revision> </revhistory> <copyright> diff --git a/documentation/mega-manual/figures/buildhistory.png b/documentation/mega-manual/figures/buildhistory.png Binary files differindex edf98d95cf..9a77bde68b 100644 --- a/documentation/mega-manual/figures/buildhistory.png +++ b/documentation/mega-manual/figures/buildhistory.png diff --git a/documentation/mega-manual/figures/yp-download.png b/documentation/mega-manual/figures/yp-download.png Binary files differindex 7f1e5ca118..5770be6883 100644 --- a/documentation/mega-manual/figures/yp-download.png +++ b/documentation/mega-manual/figures/yp-download.png diff --git a/documentation/mega-manual/mega-manual-customization.xsl b/documentation/mega-manual/mega-manual-customization.xsl index eb95240e64..a8b9bd6b5b 100644 --- a/documentation/mega-manual/mega-manual-customization.xsl +++ b/documentation/mega-manual/mega-manual-customization.xsl @@ -1,7 +1,7 @@ <?xml version='1.0'?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0"> - <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl" /> + <xsl:import href="http://docbook.sourceforge.net/release/xsl/1.76.1/xhtml/docbook.xsl" /> <xsl:param name="generate.toc"> appendix toc diff --git a/documentation/poky.ent b/documentation/poky.ent index 216015826f..c2bde9d3d6 100644 --- a/documentation/poky.ent +++ b/documentation/poky.ent @@ -1,11 +1,11 @@ -<!ENTITY DISTRO "1.7"> -<!ENTITY DISTRO_COMPRESSED "17"> +<!ENTITY DISTRO "1.8"> +<!ENTITY DISTRO_COMPRESSED "18"> <!ENTITY DISTRO_NAME "tbd"> -<!ENTITY YOCTO_DOC_VERSION "1.7"> -<!ENTITY POKYVERSION "12.0.0"> -<!ENTITY POKYVERSION_COMPRESSED "1100"> +<!ENTITY YOCTO_DOC_VERSION "1.8"> +<!ENTITY POKYVERSION "13.0.0"> +<!ENTITY POKYVERSION_COMPRESSED "1300"> <!ENTITY YOCTO_POKY "poky-&DISTRO_NAME;-&POKYVERSION;"> -<!ENTITY COPYRIGHT_YEAR "2010-2014"> +<!ENTITY COPYRIGHT_YEAR "2010-2015"> <!ENTITY YOCTO_DL_URL "http://downloads.yoctoproject.org"> <!ENTITY YOCTO_HOME_URL "http://www.yoctoproject.org"> <!ENTITY YOCTO_LISTS_URL "http://lists.yoctoproject.org"> @@ -56,11 +56,11 @@ <!ENTITY OE_INIT_PATH "&YOCTO_POKY;/oe-init-build-env"> <!ENTITY OE_INIT_FILE "oe-init-build-env"> <!ENTITY UBUNTU_HOST_PACKAGES_ESSENTIAL "gawk wget git-core diffstat unzip texinfo gcc-multilib \ - build-essential chrpath"> + build-essential chrpath socat"> <!ENTITY FEDORA_HOST_PACKAGES_ESSENTIAL "gawk make wget tar bzip2 gzip python unzip perl patch \ diffutils diffstat git cpp gcc gcc-c++ glibc-devel texinfo chrpath \ - ccache perl-Data-Dumper perl-Text-ParseWords perl-Thread-Queue"> + ccache perl-Data-Dumper perl-Text-ParseWords perl-Thread-Queue socat"> <!ENTITY OPENSUSE_HOST_PACKAGES_ESSENTIAL "python gcc gcc-c++ git chrpath make wget python-xml \ - diffstat texinfo python-curses patch"> + diffstat texinfo python-curses patch socat"> <!ENTITY CENTOS_HOST_PACKAGES_ESSENTIAL "gawk make wget tar bzip2 gzip python unzip perl patch \ - diffutils diffstat git cpp gcc gcc-c++ glibc-devel texinfo chrpath"> + diffutils diffstat git cpp gcc gcc-c++ glibc-devel texinfo chrpath socat"> diff --git a/documentation/profile-manual/profile-manual-customization.xsl b/documentation/profile-manual/profile-manual-customization.xsl index 7775e5bbcf..7284aec365 100644 --- a/documentation/profile-manual/profile-manual-customization.xsl +++ b/documentation/profile-manual/profile-manual-customization.xsl @@ -1,7 +1,7 @@ <?xml version='1.0'?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0"> - <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl" /> + <xsl:import href="http://docbook.sourceforge.net/release/xsl/1.76.1/xhtml/docbook.xsl" /> <xsl:include href="../template/permalinks.xsl"/> <xsl:include href="../template/section.title.xsl"/> diff --git a/documentation/profile-manual/profile-manual-usage.xml b/documentation/profile-manual/profile-manual-usage.xml index 5577b1b001..95ad73909c 100644 --- a/documentation/profile-manual/profile-manual-usage.xml +++ b/documentation/profile-manual/profile-manual-usage.xml @@ -842,7 +842,7 @@ idea. One of the first projects to do this was IBM's DProbes dpcc compiler, an ANSI C compiler which targeted a low-level assembly language running on an in-kernel interpreter on the - target system. This is exactly analagous to what Sun's DTrace + target system. This is exactly analogous to what Sun's DTrace did, except that DTrace invented its own language for the purpose. Systemtap, heavily inspired by DTrace, also created its own one-off language, but rather than running the product on an @@ -1275,7 +1275,7 @@ </para> <informalexample> - <emphasis>Tying it Together:</emphasis> The trace events subsystem accomodate static + <emphasis>Tying it Together:</emphasis> The trace events subsystem accommodate static and dynamic tracepoints in exactly the same way - there's no difference as far as the infrastructure is concerned. See the ftrace section for more details on the trace event subsystem. @@ -2169,7 +2169,7 @@ ### Shell environment set up for builds. ### - You can now run 'bitbake <target>' + You can now run 'bitbake <replaceable>target</replaceable>' Common targets are: core-image-minimal @@ -3257,15 +3257,25 @@ <title>Documentation</title> <para> - There doesn't seem to be any current documentation covering - LTTng 2.0, but maybe that's because the project is in transition. - The LTTng 2.0 website, however, is here: + You can find the primary LTTng Documentation on the + <ulink url='https://lttng.org/docs/'>LTTng Documentation</ulink> + site. + The documentation on this site is appropriate for intermediate to + advanced software developers who are working in a Linux environment + and are interested in efficient software tracing. + </para> + + <para> + For information on LTTng in general, visit the <ulink url='http://lttng.org/lttng2.0'>LTTng Project</ulink> + site. + You can find a "Getting Started" link on this site that takes + you to an LTTng Quick Start. </para> <para> - You can access extensive help information on how to use the - LTTng plug-in to search and analyze captured traces via the + Finally, you can access extensive help information on how to use + the LTTng plug-in to search and analyze captured traces via the Eclipse help system: <literallayout class='monospaced'> Help | Help Contents | LTTng Plug-in User Guide diff --git a/documentation/profile-manual/profile-manual.xml b/documentation/profile-manual/profile-manual.xml index e5b253b552..9842c46cab 100644 --- a/documentation/profile-manual/profile-manual.xml +++ b/documentation/profile-manual/profile-manual.xml @@ -53,9 +53,14 @@ </revision> <revision> <revnumber>1.7</revnumber> - <date>Fall of 2014</date> + <date>October 2014</date> <revremark>Released with the Yocto Project 1.7 Release.</revremark> </revision> + <revision> + <revnumber>1.8</revnumber> + <date>Sometime in 2015</date> + <revremark>Released with the Yocto Project 1.8 Release.</revremark> + </revision> </revhistory> <copyright> diff --git a/documentation/ref-manual/closer-look.xml b/documentation/ref-manual/closer-look.xml index f0ed967228..c0c0d619a4 100644 --- a/documentation/ref-manual/closer-look.xml +++ b/documentation/ref-manual/closer-look.xml @@ -255,7 +255,7 @@ <para> When you launch your build with the - <filename>bitbake <target></filename> command, BitBake + <filename>bitbake <replaceable>target</replaceable></filename> command, BitBake sorts out the configurations to ultimately define your build environment. </para> @@ -351,7 +351,7 @@ Best practices dictate that you isolate these types of configurations into their own layer. Settings you provide in - <filename>conf/distro/<distro>.conf</filename> override + <filename>conf/distro/<replaceable>distro</replaceable>.conf</filename> override similar settings that BitBake finds in your <filename>conf/local.conf</filename> file in the Build @@ -375,7 +375,7 @@ This area holds configuration files for the layer (<filename>conf/layer.conf</filename>), the distribution - (<filename>conf/distro/<distro>.conf</filename>), + (<filename>conf/distro/<replaceable>distro</replaceable>.conf</filename>), and any distribution-wide include files. </para></listitem> <listitem><para><emphasis>recipes-*:</emphasis> @@ -408,7 +408,7 @@ <para> The BSP Layer's configuration directory contains configuration files for the machine - (<filename>conf/machine/<machine>.conf</filename>) and, + (<filename>conf/machine/<replaceable>machine</replaceable>.conf</filename>) and, of course, the layer (<filename>conf/layer.conf</filename>). </para> @@ -1145,7 +1145,7 @@ <para> Images are written out to the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> - inside the <filename>tmp/deploy/images/<machine>/</filename> + inside the <filename>tmp/deploy/images/<replaceable>machine</replaceable>/</filename> folder as shown in the figure. This folder contains any files expected to be loaded on the target device. @@ -1157,43 +1157,43 @@ variable points to the appropriate directory containing images for the current configuration. <itemizedlist> - <listitem><para><filename><kernel-image></filename>: + <listitem><para><filename><replaceable>kernel-image</replaceable></filename>: A kernel binary file. The <link linkend='var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></link> variable setting determines the naming scheme for the kernel image file. Depending on that variable, the file could begin with a variety of naming strings. - The <filename>deploy/images/<machine></filename> + The <filename>deploy/images/<replaceable>machine</replaceable></filename> directory can contain multiple image files for the machine.</para></listitem> - <listitem><para><filename><root-filesystem-image></filename>: + <listitem><para><filename><replaceable>root-filesystem-image</replaceable></filename>: Root filesystems for the target device (e.g. <filename>*.ext3</filename> or <filename>*.bz2</filename> files). The <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link> variable setting determines the root filesystem image type. - The <filename>deploy/images/<machine></filename> + The <filename>deploy/images/<replaceable>machine</replaceable></filename> directory can contain multiple root filesystems for the machine.</para></listitem> - <listitem><para><filename><kernel-modules></filename>: + <listitem><para><filename><replaceable>kernel-modules</replaceable></filename>: Tarballs that contain all the modules built for the kernel. Kernel module tarballs exist for legacy purposes and can be suppressed by setting the <link linkend='var-MODULE_TARBALL_DEPLOY'><filename>MODULE_TARBALL_DEPLOY</filename></link> variable to "0". - The <filename>deploy/images/<machine></filename> + The <filename>deploy/images/<replaceable>machine</replaceable></filename> directory can contain multiple kernel module tarballs for the machine.</para></listitem> - <listitem><para><filename><bootloaders></filename>: + <listitem><para><filename><replaceable>bootloaders</replaceable></filename>: Bootloaders supporting the image, if applicable to the target machine. - The <filename>deploy/images/<machine></filename> + The <filename>deploy/images/<replaceable>machine</replaceable></filename> directory can contain multiple bootloaders for the machine.</para></listitem> - <listitem><para><filename><symlinks></filename>: - The <filename>deploy/images/<machine></filename> + <listitem><para><filename><replaceable>symlinks</replaceable></filename>: + The <filename>deploy/images/<replaceable>machine</replaceable></filename> folder contains a symbolic link that points to the most recently built file for each machine. @@ -1280,7 +1280,7 @@ part of the SDK (i.e. the part that runs on the <filename>SDKMACHINE</filename>). When you use - <filename>bitbake -c populate_sdk <imagename></filename> + <filename>bitbake -c populate_sdk <replaceable>imagename</replaceable></filename> to create the SDK, a set of default packages apply. This variable allows you to add more packages. diff --git a/documentation/ref-manual/faq.xml b/documentation/ref-manual/faq.xml index bc147ce70a..da6ce20eef 100644 --- a/documentation/ref-manual/faq.xml +++ b/documentation/ref-manual/faq.xml @@ -321,7 +321,7 @@ <qandaentry> <question> <para> - What’s the difference between <filename>foo</filename> and <filename>foo-native</filename>? + What’s the difference between <replaceable>target</replaceable> and <replaceable>target</replaceable><filename>-native</filename>? </para> </question> <answer> @@ -682,6 +682,115 @@ </answer> </qandaentry> + <qandaentry> + <question> + <para> + Why do <filename>${bindir}</filename> and <filename>${libdir}</filename> have strange values for <filename>-native</filename> recipes? + </para> + </question> + <answer> + <para> + Executables and libraries might need to be used from a + directory other than the directory into which they were + initially installed. + Complicating this situation is the fact that sometimes these + executables and libraries are compiled with the expectation + of being run from that initial installation target directory. + If this is the case, moving them causes problems. + </para> + + <para> + This scenario is a fundamental problem for package maintainers + of mainstream Linux distributions as well as for the + OpenEmbedded build system. + As such, a well-established solution exists. + Makefiles, Autotools configuration scripts, and other build + systems are expected to respect environment variables such as + <filename>bindir</filename>, <filename>libdir</filename>, + and <filename>sysconfdir</filename> that indicate where + executables, libraries, and data reside when a program is + actually run. + They are also expected to respect a + <filename>DESTDIR</filename> environment variable, which is + prepended to all the other variables when the build system + actually installs the files. + It is understood that the program does not actually run from + within <filename>DESTDIR</filename>. + </para> + + <para> + When the OpenEmbedded build system uses a recipe to build a + target-architecture program (i.e. one that is intended for + inclusion on the image being built), that program eventually + runs from the root file system of that image. + Thus, the build system provides a value of "/usr/bin" for + <filename>bindir</filename>, a value of "/usr/lib" for + <filename>libdir</filename>, and so forth. + </para> + + <para> + Meanwhile, <filename>DESTDIR</filename> is a path within the + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. + However, when the recipe builds a native program (i.e. one + that is intended to run on the build machine), that program + is never installed directly to the build machine's root + file system. + Consequently, the build system uses paths within the Build + Directory for <filename>DESTDIR</filename>, + <filename>bindir</filename> and related variables. + To better understand this, consider the following two paths + where the first is relatively normal and the second is not: + <note> + Due to these lengthy examples, the paths are artificially + broken across lines for readability. + </note> + <literallayout class='monospaced'> + /home/maxtothemax/poky-bootchart2/build/tmp/work/i586-poky-linux/zlib/ + 1.2.8-r0/sysroot-destdir/usr/bin + + /home/maxtothemax/poky-bootchart2/build/tmp/work/x86_64-linux/ + zlib-native/1.2.8-r0/sysroot-destdir/home/maxtothemax/poky-bootchart2/ + build/tmp/sysroots/x86_64-linux/usr/bin + </literallayout> + Even if the paths look unusual, they both are correct - + the first for a target and the second for a native recipe. + These paths are a consequence of the + <filename>DESTDIR</filename> mechanism and while they + appear strange, they are correct and in practice very effective. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para> + The files provided by my <filename>-native</filename> recipe do + not appear to be available to other recipes. + Files are missing from the native sysroot, my recipe is + installing to the wrong place, or I am getting permissions + errors during the do_install task in my recipe! What is wrong? + </para> + </question> + <answer> + <para> + This situation results when a build system does + not recognize the environment variables supplied to it by + <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>. + The incident that prompted this FAQ entry involved a Makefile + that used an environment variable named + <filename>BINDIR</filename> instead of the more standard + variable <filename>bindir</filename>. + The makefile's hardcoded default value of "/usr/bin" worked + most of the time, but not for the recipe's + <filename>-native</filename> variant. + For another example, permissions errors might be caused + by a Makefile that ignores <filename>DESTDIR</filename> or uses + a different name for that environment variable. + Check the the build system to see if these kinds of + issues exist. + </para> + </answer> + </qandaentry> </qandaset> </chapter> diff --git a/documentation/ref-manual/figures/buildhistory.png b/documentation/ref-manual/figures/buildhistory.png Binary files differindex edf98d95cf..9a77bde68b 100644 --- a/documentation/ref-manual/figures/buildhistory.png +++ b/documentation/ref-manual/figures/buildhistory.png diff --git a/documentation/ref-manual/introduction.xml b/documentation/ref-manual/introduction.xml index 7e246b1e46..f986f7c28e 100644 --- a/documentation/ref-manual/introduction.xml +++ b/documentation/ref-manual/introduction.xml @@ -73,6 +73,10 @@ Describes the tasks defined by the OpenEmbedded build system. </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> + <listitem><para><emphasis> <link linkend='ref-images'>Images</link>:</emphasis> Describes the standard images that the Yocto Project supports. </para></listitem> @@ -164,6 +168,8 @@ <listitem><para>Debian GNU/Linux 7.2 (Wheezy)</para></listitem> <listitem><para>Debian GNU/Linux 7.3 (Wheezy)</para></listitem> <listitem><para>Debian GNU/Linux 7.4 (Wheezy)</para></listitem> + <listitem><para>Debian GNU/Linux 7.5 (Wheezy)</para></listitem> + <listitem><para>Debian GNU/Linux 7.6 (Wheezy)</para></listitem> <!-- <listitem><para>openSUSE 11.4</para></listitem> <listitem><para>openSUSE 12.1</para></listitem> --> <listitem><para>openSUSE 12.2</para></listitem> @@ -310,11 +316,17 @@ <para> The following list shows the required packages by function given a supported CentOS Linux distribution: - <note>Depending on the CentOS version you are using, other requirements - and dependencies might exist. - For details, you should look at the CentOS sections on the - <ulink url='https://wiki.yoctoproject.org/wiki/Poky/GettingStarted/Dependencies'>Poky/GettingStarted/Dependencies</ulink> - wiki page. + <note> + For CentOS 6.x, some of the versions of the components + provided by the distribution are too old (e.g. Git, Python, + and tar). + It is recommended that you install the buildtools in order + to provide versions that will work with the OpenEmbedded + build system. + For information on how to install the buildtools tarball, + see the + "<link linkend='required-git-tar-and-python-versions'>Required Git, Tar, and Python Versions</link>" + section. </note> <itemizedlist> <listitem><para><emphasis>Essentials:</emphasis> @@ -392,14 +404,14 @@ choose the installation directory. For example, you could choose the following: <literallayout class='monospaced'> - /home/your-username/buildtools + /home/<replaceable>your-username</replaceable>/buildtools </literallayout> </para></listitem> <listitem><para> Source the tools environment setup script by using a command like the following: <literallayout class='monospaced'> - $ source /home/your-username/buildtools/environment-setup-i586-poky-linux + $ source /home/<replaceable>your-username</replaceable>/buildtools/environment-setup-i586-poky-linux </literallayout> Of course, you need to supply your installation directory and be sure to use the right file (i.e. i585 or x86-64). @@ -478,14 +490,14 @@ choose the installation directory. For example, you could choose the following: <literallayout class='monospaced'> - /home/your-username/buildtools + /home/<replaceable>your-username</replaceable>/buildtools </literallayout> </para></listitem> <listitem><para> Source the tools environment setup script by using a command like the following: <literallayout class='monospaced'> - $ source /home/your-username/buildtools/environment-setup-i586-poky-linux + $ source /home/<replaceable>your-username</replaceable>/buildtools/environment-setup-i586-poky-linux </literallayout> Of course, you need to supply your installation directory and be sure to use the right file (i.e. i585 or x86-64). diff --git a/documentation/ref-manual/migration.xml b/documentation/ref-manual/migration.xml index efed11dcb2..d072ecfa0e 100644 --- a/documentation/ref-manual/migration.xml +++ b/documentation/ref-manual/migration.xml @@ -110,7 +110,7 @@ appended to the path used to access the mirror. Here is an example: <literallayout class='monospaced'> - SSTATE_MIRRORS = "file://.* http://someserver.tld/share/sstate/PATH" + SSTATE_MIRRORS = "file://.* http://<replaceable>someserver</replaceable>.tld/share/sstate/PATH" </literallayout> </para> </section> @@ -375,10 +375,11 @@ <listitem><para><emphasis>Shared State Code:</emphasis> The shared state code has been optimized to avoid running unnecessary tasks. - For example, - <filename>bitbake -c rootfs some-image</filename> from - shared state no longer populates the target sysroot - since that is not necessary. + For example, the following no longer populates the target + sysroot since that is not necessary: + <literallayout class='monospaced'> + $ bitbake -c rootfs <replaceable>some-image</replaceable> + </literallayout> Instead, the system just needs to extract the output package contents, re-create the packages, and construct the root filesystem. @@ -832,7 +833,7 @@ This directory is located under <filename>sysroots</filename> and uses a machine-specific name (i.e. - <filename>tmp/sysroots/<machine>/pkgdata</filename>). + <filename>tmp/sysroots/<replaceable>machine</replaceable>/pkgdata</filename>). </para></listitem> </itemizedlist> </para> @@ -1100,7 +1101,7 @@ </para></listitem> <listitem><para> <filename>base-files</filename>: Remove the unnecessary - <filename>media/xxx</filename> directories. + <filename>media/</filename><replaceable>xxx</replaceable> directories. </para></listitem> <listitem><para> <filename>alsa-state</filename>: Provide an empty @@ -1228,7 +1229,7 @@ value against the branch. You can specify the branch using the following form: <literallayout class='monospaced'> - SRC_URI = "git://server.name/repository;branch=<branchname>" + SRC_URI = "git://server.name/repository;branch=<replaceable>branchname</replaceable>" </literallayout> If you do not specify a branch, BitBake looks in the default "master" branch. @@ -1305,10 +1306,10 @@ </section> <section id='migration-1.6-task-taskname-overrides'> - <title><filename>task-<taskname></filename> Overrides</title> + <title><filename>task-</filename><replaceable>taskname</replaceable> Overrides</title> <para> - <filename>task-<taskname></filename> overrides have been + <filename>task-</filename><replaceable>taskname</replaceable> overrides have been adjusted so that tasks whose names contain underscores have the underscores replaced by hyphens for the override so that they now function properly. @@ -1691,6 +1692,327 @@ </para> </section> </section> + +<section id='moving-to-the-yocto-project-1.7-release'> + <title>Moving to the Yocto Project 1.7 Release</title> + + <para> + This section provides migration information for moving to the + Yocto Project 1.7 Release from the prior release. + </para> + + <section id='migration-1.7-changes-to-setting-qemu-packageconfig-options'> + <title>Changes to Setting QEMU <filename>PACKAGECONFIG</filename> Options in <filename>local.conf</filename></title> + + <para> + The QEMU recipe now uses a number of + <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link> + options to enable various optional features. + The method used to set defaults for these options means that + existing + <filename>local.conf</filename> files will need to be be + modified to append to <filename>PACKAGECONFIG</filename> for + <filename>qemu-native</filename> and + <filename>nativesdk-qemu</filename> instead of setting it. + In other words, to enable graphical output for QEMU, you should + now have these lines in <filename>local.conf</filename>: + <literallayout class='monospaced'> + PACKAGECONFIG_append_pn-qemu-native = " sdl" + PACKAGECONFIG_append_pn-nativesdk-qemu = " sdl" + </literallayout> + </para> + </section> + + <section id='migration-1.7-minimum-git-version'> + <title>Minimum Git version</title> + + <para> + The minimum + <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink> version required + on the build host is now 1.7.8 because the + <filename>‐‐list</filename> option is now required by + BitBake's Git fetcher. + As always, if your host distribution does not provide a version of + Git that meets this requirement, you can use the + <filename>buildtools-tarball</filename> that does. + See the + "<link linkend='required-git-tar-and-python-versions'>Required Git, tar, and Python Versions</link>" + section for more information. + </para> + </section> + + <section id='migration-1.7-autotools-class-changes'> + <title>Autotools Class Changes</title> + + <para> + The following + <link linkend='ref-classes-autotools'><filename>autotools</filename></link> + class changes occurred: + <itemizedlist> + <listitem><para><emphasis> + A separate build directory is now used by default:</emphasis> + The <filename>autotools</filename> class has been changed + to use a directory for building + (<link linkend='var-B'><filename>B</filename></link>), + which is separate from the source directory + (<link linkend='var-S'><filename>S</filename></link>). + This is commonly referred to as + <filename>B != S</filename>, or an out-of-tree build.</para> + <para>If the software being built is already capable of + building in a directory separate from the source, you + do not need to do anything. + However, if the software is not capable of being built + in this manner, you will + need to either patch the software so that it can build + separately, or you will need to change the recipe to + inherit the + <link linkend='ref-classes-autotools-brokensep'><filename>autotools-brokensep</filename></link> + class instead of the <filename>autotools</filename> class. + </para></listitem> + <listitem><para><emphasis> + The <filename>‐‐foreign</filename> option is + no longer passed to <filename>automake</filename> when + running <filename>autoconf</filename>:</emphasis> + This option tells <filename>automake</filename> that a + particular software package does not follow the GNU + standards and therefore should not be expected + to distribute certain files such as + <filename>ChangeLog</filename>, + <filename>AUTHORS</filename>, and so forth. + Because the majority of upstream software packages already + tell <filename>automake</filename> to enable foreign mode + themselves, the option is mostly superfluous. + However, some recipes will need patches for this change. + You can easily make the change by patching + <filename>configure.ac</filename> so that it passes + "foreign" to <filename>AM_INIT_AUTOMAKE()</filename>. + See + <ulink url='http://cgit.openembedded.org/openembedded-core/commit/?id=01943188f85ce6411717fb5bf702d609f55813f2'>this commit</ulink> + for an example showing how to make the patch. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-1.7-binary-configuration-scripts-disabled'> + <title>Binary Configuration Scripts Disabled</title> + + <para> + Some of the core recipes that package binary configuration scripts + now disable the scripts due to the + scripts previously requiring error-prone path substitution. + Software that links against these libraries using these scripts + should use the much more robust <filename>pkg-config</filename> + instead. + The list of recipes changed in this version (and their + configuration scripts) is as follows: + <literallayout class='monospaced'> + directfb (directfb-config) + freetype (freetype-config) + gpgme (gpgme-config) + libassuan (libassuan-config) + libcroco (croco-6.0-config) + libgcrypt (libgcrypt-config) + libgpg-error (gpg-error-config) + libksba (ksba-config) + libpcap (pcap-config) + libpcre (pcre-config) + libpng (libpng-config, libpng16-config) + libsdl (sdl-config) + libusb-compat (libusb-config) + libxml2 (xml2-config) + libxslt (xslt-config) + ncurses (ncurses-config) + neon (neon-config) + npth (npth-config) + pth (pth-config) + taglib (taglib-config) + </literallayout> + Additionally, support for <filename>pkg-config</filename> has been + added to some recipes in the previous list in the rare cases + where the upstream software package does not already provide + it. + </para> + </section> + + <section id='migration-1.7-glibc-replaces-eglibc'> + <title><filename>eglibc 2.19</filename> Replaced with <filename>glibc 2.20</filename></title> + + <para> + Because <filename>eglibc</filename> and + <filename>glibc</filename> were already fairly close, this + replacement should not require any significant changes to other + software that links to <filename>eglibc</filename>. + However, there were a number of minor changes in + <filename>glibc 2.20</filename> upstream that could require + patching some software (e.g. the removal of the + <filename>_BSD_SOURCE</filename> feature test macro). + </para> + + <para> + <filename>glibc 2.20</filename> requires version 2.6.32 or greater + of the Linux kernel. + Thus, older kernels will no longer be usable in conjunction with it. + </para> + + <para> + For full details on the changes in <filename>glibc 2.20</filename>, + see the upstream release notes + <ulink url='https://sourceware.org/ml/libc-alpha/2014-09/msg00088.html'>here</ulink>. + </para> + </section> + + <section id='migration-1.7-kernel-module-autoloading'> + <title>Kernel Module Autoloading</title> + + <para> + The + <link linkend='var-module_autoload'><filename>module_autoload_*</filename></link> + variable is now deprecated and a new + <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link> + variable should be used instead. + Also, + <link linkend='var-module_conf'><filename>module_conf_*</filename></link> + must now be used in conjunction with a new + <link linkend='var-KERNEL_MODULE_PROBECONF'><filename>KERNEL_MODULE_PROBECONF</filename></link> + variable. + The new variables no longer require you to specify the module name + as part of the variable name. + This change not only simplifies usage but also allows the values + of these variables to be appropriately incorporated into task + signatures and thus trigger the appropriate tasks to re-execute + when changed. + You should replace any references to + <filename>module_autoload_*</filename> with + <filename>KERNEL_MODULE_AUTOLOAD</filename>, and add any modules + for which <filename>module_conf_*</filename> is specified to + <filename>KERNEL_MODULE_PROBECONF</filename>. + </para> + + <para> + For more information, see the + <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link> + and + <link linkend='var-KERNEL_MODULE_PROBECONF'><filename>KERNEL_MODULE_PROBECONF</filename></link> + variables. + </para> + </section> + + <section id='migration-1.7-qa-check-changes'> + <title>QA Check Changes</title> + + <para> + The following changes have occurred to the QA check process: + <itemizedlist> + <listitem><para> + Additional QA checks <filename>file-rdeps</filename> + and <filename>build-deps</filename> have been added in + order to verify that file dependencies are satisfied + (e.g. package contains a script requiring + <filename>/bin/bash</filename>) and build-time dependencies + are declared, respectively. + For more information, please see the + "<link linkend='ref-qa-checks'>QA Error and Warning Messages</link>" + chapter. + </para></listitem> + <listitem><para> + Package QA checks are now performed during a new + <link linkend='ref-tasks-package_qa'><filename>do_package_qa</filename></link> + task rather than being part of the + <link linkend='ref-tasks-package'><filename>do_package</filename></link> + task. + This allows more parallel execution. + This change is unlikely to be an issue except for highly + customized recipes that disable packaging tasks themselves + by marking them as <filename>noexec</filename>. + For those packages, you will need to disable the + <filename>do_package_qa</filename> task as well. + </para></listitem> + <listitem><para> + Files being overwritten during the + <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link> + task now trigger an error instead of a warning. + Recipes should not be overwriting files written to the + sysroot by other recipes. + If you have these types of recipes, you need to alter them + so that they do not overwrite these files.</para> + <para>You might now receive this error after changes in + configuration or metadata resulting in orphaned files + being left in the sysroot. + If you do receive this error, the way to resolve the issue + is to delete your + <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> + or to move it out of the way and then re-start the build. + Anything that has been fully built up to that point and + does not need rebuilding will be restored from the shared + state cache and the rest of the build will be able to + proceed as normal. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-1.7-removed-recipes'> + <title>Removed Recipes</title> + + <para> + The following recipes have been removed: + <itemizedlist> + <listitem><para> + <filename>x-load</filename>: + This recipe has been superseded by + U-boot SPL for all Cortex-based TI SoCs. + For legacy boards, the <filename>meta-ti</filename> + layer, which contains a maintained recipe, should be used + instead. + </para></listitem> + <listitem><para> + <filename>ubootchart</filename>: + This recipe is obsolete. + A <filename>bootchart2</filename> recipe has been added + to functionally replace it. + </para></listitem> + <listitem><para> + <filename>linux-yocto 3.4</filename>: + Support for the linux-yocto 3.4 kernel has been dropped. + Support for the 3.10 and 3.14 kernels remains, while + support for version 3.17 has been added. + </para></listitem> + <listitem><para> + <filename>eglibc</filename> has been removed in favor of + <filename>glibc</filename>. + See the + "<link linkend='migration-1.7-glibc-replaces-eglibc'><filename>eglibc 2.19</filename> Replaced with <filename>glibc 2.20</filename></link>" + section for more information. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-1.7-miscellaneous-changes'> + <title>Miscellaneous Changes</title> + + <para> + The following miscellaneous change occurred: + <itemizedlist> + <listitem><para> + The build history feature now writes + <filename>build-id.txt</filename> instead of + <filename>build-id</filename>. + Additionally, <filename>build-id.txt</filename> + now contains the full build header as printed by + BitBake upon starting the build. + You should manually remove old "build-id" files from your + existing build history repositories to avoid confusion. + For information on the build history feature, see the + "<link linkend='maintaining-build-output-quality'>Maintaining Build Output Quality</link>" + section. + </para></listitem> + </itemizedlist> + </para> + </section> +</section> + </chapter> <!-- vim: expandtab tw=80 ts=4 diff --git a/documentation/ref-manual/ref-classes.xml b/documentation/ref-manual/ref-classes.xml index e7e9942b3b..fed25b25e6 100644 --- a/documentation/ref-manual/ref-classes.xml +++ b/documentation/ref-manual/ref-classes.xml @@ -102,10 +102,22 @@ </para> <para> + By default, the <filename>autotools</filename> class + uses out-of-tree builds + (<link linkend='var-B'><filename>B</filename></link> <filename>!=</filename> + <link linkend='var-S'><filename>S</filename></link>). + If the software being built by a recipe does not support + using out-of-tree builds, you should have the recipe inherit the + <link linkend='ref-classes-autotools-brokensep'><filename>autotools-brokensep</filename></link> + class. + </para> + + <para> It's useful to have some idea of how the tasks defined by this class work and what they do behind the scenes. <itemizedlist> - <listitem><para><link linkend='ref-tasks-configure'><filename>do_configure</filename></link> ‐ Regenerates the + <listitem><para><link linkend='ref-tasks-configure'><filename>do_configure</filename></link> ‐ + Regenerates the configure script (using <filename>autoreconf</filename>) and then launches it with a standard set of arguments used during cross-compilation. You can pass additional parameters to <filename>configure</filename> through the @@ -123,17 +135,6 @@ </para></listitem> </itemizedlist> </para> - - <note> - It is planned for future Yocto Project releases that by default, the - <filename>autotools</filename> class supports out-of-tree builds - (<link linkend='var-B'><filename>B</filename></link> != - <link linkend='var-S'><filename>S</filename></link>). - If your recipes do not support out-of-tree builds, you should - have them inherit the - <link linkend='ref-classes-autotools-brokensep'><filename>autotools-brokensep</filename></link> - class. - </note> </section> <section id='ref-classes-autotools-brokensep'> @@ -186,6 +187,8 @@ binary from source. The binary package is extracted and new packages in the configured output package format are created. + Extraction and installation of proprietary binaries is a good example + use for this class. <note> For RPMs and other packages that do not contain a subdirectory, you should specify a "subdir" parameter. @@ -229,6 +232,21 @@ </para> </section> +<section id='ref-classes-binconfig-disabled'> + <title><filename>binconfig-disabled.bbclass</filename></title> + + <para> + An alternative version of the + <link linkend='ref-classes-binconfig'><filename>binconfig</filename></link> + class, which disables binary configuration scripts by making them + return an error in favor of using <filename>pkg-config</filename> + to query the information. + The scripts to be disabled should be specified using the + <link linkend='var-BINCONFIG'><filename>BINCONFIG</filename></link> + variable within the recipe inheriting the class. + </para> +</section> + <section id='ref-classes-blacklist'> <title><filename>blacklist.bbclass</filename></title> @@ -364,6 +382,18 @@ </para> </section> +<section id='ref-classes-buildstats-summary'> + <title><filename>buildstats-summary.bbclass</filename></title> + + <para> + When inherited globally, prints statistics at the end of the build + on sstate re-use. + In order to function, this class requires the + <link linkend='ref-classes-buildstats'><filename>buildstats</filename></link> + class be enabled. + </para> +</section> + <section id='ref-classes-ccache'> <title><filename>ccache.bbclass</filename></title> @@ -431,6 +461,19 @@ </para> </section> +<section id='ref-classes-compress_doc'> + <title><filename>compress_doc.bbclass</filename></title> + + <para> + Enables compression for man pages and info pages. + This class is intended to be inherited globally. + The default compression mechanism is gz (gzip) but you can + select an alternative mechanism by setting the + <link linkend='var-DOC_COMPRESS'><filename>DOC_COMPRESS</filename></link> + variable. + </para> +</section> + <section id='ref-classes-copyleft_compliance'> <title><filename>copyleft_compliance.bbclass</filename></title> @@ -445,6 +488,20 @@ </para> </section> +<section id='ref-classes-copyleft_filter'> + <title><filename>copyleft_filter.bbclass</filename></title> + + <para> + A class used by the + <link linkend='ref-classes-archiver'><filename>archiver</filename></link> + and + <link linkend='ref-classes-copyleft_compliance'><filename>copyleft_compliance</filename></link> + classes for filtering licenses. + The <filename>copyleft_filter</filename> class is an internal class + and is not intended to be used directly. + </para> +</section> + <section id='ref-classes-core-image'> <title><filename>core-image.bbclass</filename></title> @@ -881,7 +938,8 @@ <itemizedlist> <listitem><para> <link linkend='var-INITRD'><filename>INITRD</filename></link>: - Indicates a filesystem image to use as an initrd (optional). + Indicates list of filesystem images to concatenate and use + as an initial RAM disk (initrd) (optional). </para></listitem> <listitem><para> <link linkend='var-ROOTFS'><filename>ROOTFS</filename></link>: @@ -979,6 +1037,36 @@ </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> @@ -1332,6 +1420,35 @@ Currently, this test triggers too many false positives and thus is not normally enabled. </para></listitem> + <listitem><para><emphasis><filename>build-deps:</filename></emphasis> + Determines if a build-time dependency that is specified through + <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>, + explicit + <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>, + or task-level dependencies exists to match any runtime + dependency. + This determination is particularly useful to discover where + runtime dependencies are detected and added during packaging. + If no explicit dependency has been specified within the + metadata, at the packaging stage it is too late to ensure that + the dependency is built, and thus you can end up with an + error when the package is installed into the image during the + <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link> + task because the auto-detected dependency was not satisfied. + An example of this would be where the + <link linkend='ref-classes-update-rc.d'><filename>update-rc.d</filename></link> + class automatically adds a dependency on the + <filename>initscripts-functions</filename> package to packages + that install an initscript that refers to + <filename>/etc/init.d/functions</filename>. + The recipe should really have an explicit + <filename>RDEPENDS</filename> for the package in question on + <filename>initscripts-functions</filename> so that the + OpenEmbedded build system is able to ensure that the + <filename>initscripts</filename> recipe is actually built and + thus the <filename>initscripts-functions</filename> package is + made available. + </para></listitem> <listitem><para><emphasis><filename>compile-host-path:</filename></emphasis> Checks the <link linkend='ref-tasks-compile'><filename>do_compile</filename></link> @@ -1383,6 +1500,25 @@ Some very rare cases do exist for dynamically loaded modules where these symlinks are needed instead in the main package. </para></listitem> + <listitem><para><emphasis><filename>file-rdeps:</filename></emphasis> + Checks that file-level dependencies identified by the + OpenEmbedded build system at packaging time are satisfied. + For example, a shell script might start with the line + <filename>#!/bin/bash</filename>. + This line would translate to a file dependency on + <filename>/bin/bash</filename>. + Of the three package managers that the OpenEmbedded build + system supports, only RPM directly handles file-level + dependencies, resolving them automatically to packages + providing the files. + However, the lack of that functionality in the other two + package managers does not mean the dependencies do not still + need resolving. + This QA check attempts to ensure that explicitly declared + <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> + exist to handle any file-level dependency detected in + packaged files. + </para></listitem> <listitem><para><emphasis><filename>files-invalid:</filename></emphasis> Checks for <link linkend='var-FILES'><filename>FILES</filename></link> @@ -1895,13 +2031,13 @@ You can create a recipe that builds tools that run natively on the host a couple different ways: <itemizedlist> - <listitem><para>Create a <filename>myrecipe-native.bb</filename> + <listitem><para>Create a <replaceable>myrecipe</replaceable><filename>-native.bb</filename> that inherits the <filename>native</filename> class. If you use this method, you must order the inherit statement in the recipe after all other inherit statements so that the <filename>native</filename> class is inherited last. </para></listitem> - <listitem><para>Create or modify a target recipe that has adds + <listitem><para>Create or modify a target recipe that contains the following: <literallayout class='monospaced'> <link linkend='var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link> = "native" @@ -1936,7 +2072,7 @@ You can create a recipe that builds tools that run on the SDK machine a couple different ways: <itemizedlist> - <listitem><para>Create a <filename>myrecipe-nativesdk.bb</filename> + <listitem><para>Create a <replaceable>myrecipe</replaceable><filename>-nativesdk.bb</filename> recipe that inherits the <filename>nativesdk</filename> class. If you use this method, you must order the inherit statement in the recipe after all other inherit statements so that the @@ -2339,7 +2475,7 @@ <itemizedlist> <listitem><para><emphasis><filename>populate_sdk_base</filename>:</emphasis> The base class supporting SDK creation under all package - managers (i.e. DEB, RPM, and IPK).</para></listitem> + managers (i.e. DEB, RPM, and opkg).</para></listitem> <listitem><para><emphasis><filename>populate_sdk_deb</filename>:</emphasis> Supports creation of the SDK given the Debian package manager. </para></listitem> @@ -2347,13 +2483,14 @@ Supports creation of the SDK given the RPM package manager. </para></listitem> <listitem><para><emphasis><filename>populate_sdk_ipk</filename>:</emphasis> - Supports creation of the SDK given the IPK package manager. + Supports creation of the SDK given the opkg (IPK format) + package manager. </para></listitem> </itemizedlist> </para> <para> - The <filename>populate_sdk_base</filename> package inherits the + The <filename>populate_sdk_base</filename> class inherits the appropriate <filename>populate_sdk_*</filename> (i.e. <filename>deb</filename>, <filename>rpm</filename>, and <filename>ipk</filename>) based on @@ -2364,8 +2501,8 @@ The base class ensures all source and destination directories are established and then populates the SDK. After populating the SDK, the <filename>populate_sdk_base</filename> - class constructs two images: - <link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link><filename>-nativesdk</filename>, + class constructs two sysroots: + <filename>${</filename><link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link><filename>}-nativesdk</filename>, which contains the cross-compiler and associated tooling, and the target, which contains a target root filesystem that is configured for the SDK usage. @@ -2373,8 +2510,8 @@ <link linkend='var-SDK_OUTPUT'><filename>SDK_OUTPUT</filename></link>, which consists of the following: <literallayout class='monospaced'> - ${SDK_OUTPUT}/<sdk_arch-nativesdk pkgs> - ${SDK_OUTPUT}/${SDKTARGETSYSROOT}/<target pkgs> + ${SDK_OUTPUT}/${SDK_ARCH}<replaceable>-nativesdk-pkgs</replaceable> + ${SDK_OUTPUT}/${SDKTARGETSYSROOT}/<replaceable>target-pkgs</replaceable> </literallayout> </para> @@ -2480,6 +2617,22 @@ </para> </section> +<section id='ref-classes-ptest-gnome'> + <title><filename>ptest-gnome.bbclass</filename></title> + + <para> + Enables package tests (ptests) specifically for GNOME packages, + which have tests intended to be executed with + <filename>gnome-desktop-testing</filename>. + </para> + + <para> + For information on setting up and running ptests, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest'>Testing Packages With ptest</ulink>" + section in the Yocto Project Development Manual. + </para> +</section> + <section id='ref-classes-python-dir'> <title><filename>python-dir.bbclass</filename></title> @@ -2863,37 +3016,37 @@ <para> The class supports the following variables: <itemizedlist> - <listitem><para><emphasis><link linkend='var-INITRD'><filename>INITRD</filename></link>:</emphasis> - Indicates a filesystem image to use as an initial RAM disk - (initrd). + <listitem><para><link linkend='var-INITRD'><filename>INITRD</filename></link>: + Indicates list of filesystem images to concatenate and use as + an initial RAM disk (initrd). This variable is optional.</para></listitem> - <listitem><para><emphasis><link linkend='var-ROOTFS'><filename>ROOTFS</filename></link>:</emphasis> + <listitem><para><link linkend='var-ROOTFS'><filename>ROOTFS</filename></link>: Indicates a filesystem image to include as the root filesystem. This variable is optional.</para></listitem> - <listitem><para><emphasis><link linkend='var-AUTO_SYSLINUXMENU'><filename>AUTO_SYSLINUXMENU</filename></link>:</emphasis> + <listitem><para><link linkend='var-AUTO_SYSLINUXMENU'><filename>AUTO_SYSLINUXMENU</filename></link>: Enables creating an automatic menu when set to "1". </para></listitem> - <listitem><para><emphasis><link linkend='var-LABELS'><filename>LABELS</filename></link>:</emphasis> + <listitem><para><link linkend='var-LABELS'><filename>LABELS</filename></link>: Lists targets for automatic configuration. </para></listitem> - <listitem><para><emphasis><link linkend='var-APPEND'><filename>APPEND</filename></link>:</emphasis> + <listitem><para><link linkend='var-APPEND'><filename>APPEND</filename></link>: Lists append string overrides for each label. </para></listitem> - <listitem><para><emphasis><link linkend='var-SYSLINUX_OPTS'><filename>SYSLINUX_OPTS</filename></link>:</emphasis> + <listitem><para><link linkend='var-SYSLINUX_OPTS'><filename>SYSLINUX_OPTS</filename></link>: Lists additional options to add to the syslinux file. Semicolon characters separate multiple options. </para></listitem> - <listitem><para><emphasis><link linkend='var-SYSLINUX_SPLASH'><filename>SYSLINUX_SPLASH</filename></link>:</emphasis> + <listitem><para><link linkend='var-SYSLINUX_SPLASH'><filename>SYSLINUX_SPLASH</filename></link>: Lists a background for the VGA boot menu when you are using the boot menu.</para></listitem> - <listitem><para><emphasis><link linkend='var-SYSLINUX_DEFAULT_CONSOLE'><filename>SYSLINUX_DEFAULT_CONSOLE</filename></link>:</emphasis> + <listitem><para><link linkend='var-SYSLINUX_DEFAULT_CONSOLE'><filename>SYSLINUX_DEFAULT_CONSOLE</filename></link>: Set to "console=ttyX" to change kernel boot default console. </para></listitem> - <listitem><para><emphasis><link linkend='var-SYSLINUX_SERIAL'><filename>SYSLINUX_SERIAL</filename></link>:</emphasis> + <listitem><para><link linkend='var-SYSLINUX_SERIAL'><filename>SYSLINUX_SERIAL</filename></link>: Sets an alternate serial port. Or, turns off serial when the variable is set with an empty string.</para></listitem> - <listitem><para><emphasis><link linkend='var-SYSLINUX_SERIAL_TTY'><filename>SYSLINUX_SERIAL_TTY</filename></link>:</emphasis> + <listitem><para><link linkend='var-SYSLINUX_SERIAL_TTY'><filename>SYSLINUX_SERIAL_TTY</filename></link>: Sets an alternate "console=tty..." kernel boot argument. </para></listitem> </itemizedlist> @@ -3003,6 +3156,27 @@ </para> </section> +<section id='ref-classes-texinfo'> + <title><filename>texinfo.bbclass</filename></title> + + <para> + This class should be inherited by recipes whose upstream packages + invoke the <filename>texinfo</filename> utilities at build-time. + Native and cross recipes are made to use the dummy scripts provided + by <filename>texinfo-dummy-native</filename>, for improved performance. + Target architecture recipes use the genuine + Texinfo utilities. + By default, they use the Texinfo utilities on the host system. + <note> + If you want to use the Texinfo recipe shipped with the build + system, you can remove "texinfo-native" from + <link linkend='var-ASSUME_PROVIDED'><filename>ASSUME_PROVIDED</filename></link> + and makeinfo from + <link linkend='var-SANITY_REQUIRED_UTILITIES'><filename>SANITY_REQUIRED_UTILITIES</filename></link>. + </note> + </para> +</section> + <section id='ref-classes-tinderclient'> <title><filename>tinderclient.bbclass</filename></title> @@ -3078,6 +3252,21 @@ </para> </section> +<section id='ref-classes-uninative'> + <title><filename>uninative.bbclass</filename></title> + + <para> + Provides a means of reusing <filename>native/cross</filename> over + multiple distros. + <note> + Currently, the method used by the <filename>uninative</filename> + class is experimental. + </note> + For more information, see the commit message + <ulink url='http://cgit.openembedded.org/openembedded-core/commit/?id=e66c96ae9c7ba21ebd04a4807390f0031238a85a'>here</ulink>. + </para> +</section> + <section id='ref-classes-update-alternatives'> <title><filename>update-alternatives.bbclass</filename></title> diff --git a/documentation/ref-manual/ref-features.xml b/documentation/ref-manual/ref-features.xml index 4aafaea674..230cabd155 100644 --- a/documentation/ref-manual/ref-features.xml +++ b/documentation/ref-manual/ref-features.xml @@ -7,8 +7,8 @@ <para> This chapter provides a reference of shipped machine and distro features - you can include as part of the image, a reference on image types you can - build, and a reference on feature backfilling. + you can include as part of your image, a reference on image features you can + select, and a reference on feature backfilling. </para> <para> @@ -16,7 +16,10 @@ should be included in the generated images. Distributions can select which features they want to support through the <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename> - variable, which is set in the <filename>poky.conf</filename> distribution configuration file. + variable, which is set or appended to in a distribution's configuration file such as + <filename>poky.conf</filename>, + <filename>poky-tiny.conf</filename>, + <filename>poky-lsb.conf</filename> and so forth. Machine features are set in the <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename> variable, which is set in the machine configuration file and @@ -39,7 +42,7 @@ changed based on a given feature: <literallayout class='monospaced'> $ cd poky - $ git grep 'contains.*MACHINE_FEATURES.*<feature>' + $ git grep 'contains.*MACHINE_FEATURES.*<replaceable>feature</replaceable>' </literallayout> </para> @@ -69,16 +72,26 @@ </para></listitem> <listitem><para><emphasis>bluetooth:</emphasis> Hardware has integrated BT </para></listitem> + <listitem><para><emphasis>efi:</emphasis> Support for booting through EFI + </para></listitem> <listitem><para><emphasis>ext2:</emphasis> Hardware HDD or Microdrive </para></listitem> <listitem><para><emphasis>irda:</emphasis> Hardware has IrDA support </para></listitem> <listitem><para><emphasis>keyboard:</emphasis> Hardware has a keyboard </para></listitem> + <listitem><para><emphasis>pcbios:</emphasis> Support for booting through BIOS + </para></listitem> <listitem><para><emphasis>pci:</emphasis> Hardware has a PCI bus </para></listitem> <listitem><para><emphasis>pcmcia:</emphasis> Hardware has PCMCIA or CompactFlash sockets </para></listitem> + <listitem><para><emphasis>phone:</emphasis> Mobile phone (voice) support + </para></listitem> + <listitem><para><emphasis>qvga:</emphasis> Machine has a QVGA (320x240) display + </para></listitem> + <listitem><para><emphasis>rtc:</emphasis> Machine has a Real-Time Clock + </para></listitem> <listitem><para><emphasis>screen:</emphasis> Hardware has a screen </para></listitem> <listitem><para><emphasis>serial:</emphasis> Hardware has serial support (usually RS232) @@ -89,6 +102,8 @@ </para></listitem> <listitem><para><emphasis>usbhost:</emphasis> Hardware is USB Host capable </para></listitem> + <listitem><para><emphasis>vfat:</emphasis> FAT file system support + </para></listitem> <listitem><para><emphasis>wifi:</emphasis> Hardware has integrated WiFi </para></listitem> </itemizedlist> @@ -192,51 +207,100 @@ <title>Image Features</title> <para> - The contents of images generated by the OpenEmbedded build system can be controlled by the - <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename> - and <filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename> + The contents of images generated by the OpenEmbedded build system + can be controlled by the + <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link> + and + <link linkend='var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></link> variables that you typically configure in your image recipes. Through these variables, you can add several different - predefined packages such as development utilities or packages with debug - information needed to investigate application problems or profile applications. + predefined packages such as development utilities or packages with + debug information needed to investigate application problems or + profile applications. </para> <para> - Current list of - <filename>IMAGE_FEATURES</filename> contains the following: + The following image features are available for all images: <itemizedlist> - <listitem><para><emphasis>dbg-pkgs:</emphasis> Installs debug symbol packages for all packages - installed in a given image.</para></listitem> - <listitem><para><emphasis>dev-pkgs:</emphasis> Installs development packages (headers and - extra library links) for all packages installed in a given image.</para></listitem> - <listitem><para><emphasis>doc-pkgs:</emphasis> Installs documentation packages for all packages - installed in a given image.</para></listitem> - <listitem><para><emphasis>nfs-server:</emphasis> Installs an NFS server.</para></listitem> - <listitem><para><emphasis>read-only-rootfs:</emphasis> Creates - an image whose root filesystem is read-only. + <listitem><para><emphasis>dbg-pkgs:</emphasis> + Installs debug symbol packages for all packages installed + in a given image. + </para></listitem> + <listitem><para><emphasis>debug-tweaks:</emphasis> + Makes an image suitable for development (e.g. + allows root logins without passwords). + </para></listitem> + <listitem><para><emphasis>dev-pkgs:</emphasis> + Installs development packages (headers and extra library + links) for all packages installed in a given image. + </para></listitem> + <listitem><para><emphasis>doc-pkgs:</emphasis> Installs + documentation packages for all packages installed in a + given image. + </para></listitem> + <listitem><para><emphasis>package-management:</emphasis> + Installs package management tools and preserves the package + manager database. + </para></listitem> + <listitem><para><emphasis>ptest-pkgs:</emphasis> + Installs ptest packages for all ptest-enabled recipes. + </para></listitem> + <listitem><para><emphasis>read-only-rootfs:</emphasis> + Creates an image whose root filesystem is read-only. See the "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem'>Creating a Read-Only Root Filesystem</ulink>" section in the Yocto Project Development Manual for more - information.</para></listitem> - <listitem><para><emphasis>splash:</emphasis> Enables showing a splash screen during boot. - By default, this screen is provided by <filename>psplash</filename>, which does - allow customization. - If you prefer to use an alternative splash screen package, you can do so by - setting the <filename>SPLASH</filename> variable - to a different package name (or names) within the image recipe or at the distro - configuration level.</para></listitem> - <listitem><para><emphasis>ssh-server-dropbear:</emphasis> Installs the Dropbear minimal - SSH server. - </para></listitem> - <listitem><para><emphasis>ssh-server-openssh:</emphasis> Installs the OpenSSH SSH server, - which is more full-featured than Dropbear. - Note that if both the OpenSSH SSH server and the Dropbear minimal SSH server - are present in <filename>IMAGE_FEATURES</filename>, then OpenSSH will take - precedence and Dropbear will not be installed.</para></listitem> - <listitem><para><emphasis>staticdev-pkgs:</emphasis> Installs static development - packages (i.e. static libraries containing <filename>*.a</filename> files) for all - packages installed in a given image.</para></listitem> - <listitem><para><emphasis>tools-debug:</emphasis> Installs debugging tools such as + information. + </para></listitem> + <listitem><para><emphasis>splash:</emphasis> + Enables showing a splash screen during boot. + By default, this screen is provided by + <filename>psplash</filename>, which does allow + customization. + If you prefer to use an alternative splash screen package, + you can do so by setting the <filename>SPLASH</filename> + variable to a different package name (or names) within the + image recipe or at the distro configuration level. + </para></listitem> + <listitem><para><emphasis>staticdev-pkgs:</emphasis> + Installs static development packages, which are + static libraries (i.e. <filename>*.a</filename> files), for + all packages installed in a given image. + </para></listitem> + </itemizedlist> + </para> + + <para> + Some image features are available only when you inherit the + <link linkend='ref-classes-core-image'><filename>core-image</filename></link> + class. + The current list of these valid features is as follows: + <itemizedlist> + <listitem><para><emphasis>eclipse-debug:</emphasis> Provides + Eclipse remote debugging support. + </para></listitem> + <listitem><para><emphasis>hwcodecs:</emphasis> Installs + hardware acceleration codecs. + </para></listitem> + <listitem><para><emphasis>nfs-server:</emphasis> + Installs an NFS server. + </para></listitem> + <listitem><para><emphasis>qt4-pkgs:</emphasis> + Supports Qt4/X11 and demo applications. + </para></listitem> + <listitem><para><emphasis>ssh-server-dropbear:</emphasis> + Installs the Dropbear minimal SSH server. + </para></listitem> + <listitem><para><emphasis>ssh-server-openssh:</emphasis> + Installs the OpenSSH SSH server, which is more + full-featured than Dropbear. + Note that if both the OpenSSH SSH server and the Dropbear + minimal SSH server are present in + <filename>IMAGE_FEATURES</filename>, then OpenSSH will take + precedence and Dropbear will not be installed. + </para></listitem> + <listitem><para><emphasis>tools-debug:</emphasis> + Installs debugging tools such as <filename>strace</filename> and <filename>gdb</filename>. For information on GDB, see the "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-gdb-remotedebug'>Debugging With the GNU Project Debugger (GDB) Remotely</ulink>" @@ -244,23 +308,33 @@ For information on tracing and profiling, see the <ulink url='&YOCTO_DOCS_PROF_URL;'>Yocto Project Profiling and Tracing Manual</ulink>. </para></listitem> - <listitem><para><emphasis>tools-profile:</emphasis> Installs profiling tools such as - <filename>oprofile</filename>, <filename>exmap</filename>, and - <filename>LTTng</filename>. + <listitem><para><emphasis>tools-profile:</emphasis> + Installs profiling tools such as + <filename>oprofile</filename>, <filename>exmap</filename>, + and <filename>LTTng</filename>. For general information on user-space tools, see the "<ulink url='&YOCTO_DOCS_ADT_URL;#user-space-tools'>User-Space Tools</ulink>" - section in the Yocto Project Application Developer's Guide.</para></listitem> - <listitem><para><emphasis>tools-sdk:</emphasis> Installs a full SDK that runs on the device. + section in the Yocto Project Application Developer's + Guide. + </para></listitem> + <listitem><para><emphasis>tools-sdk:</emphasis> + Installs a full SDK that runs on the device. + </para></listitem> + <listitem><para><emphasis>tools-testapps:</emphasis> + Installs device testing tools (e.g. touchscreen debugging). </para></listitem> - <listitem><para><emphasis>tools-testapps:</emphasis> Installs device testing tools (e.g. - touchscreen debugging).</para></listitem> - <listitem><para><emphasis>x11:</emphasis> Installs the X server</para></listitem> - <listitem><para><emphasis>x11-base:</emphasis> Installs the X server with a - minimal environment.</para></listitem> - <listitem><para><emphasis>x11-sato:</emphasis> Installs the OpenedHand Sato environment. + <listitem><para><emphasis>x11:</emphasis> + Installs the X server. + </para></listitem> + <listitem><para><emphasis>x11-base:</emphasis> + Installs the X server with a minimal environment. + </para></listitem> + <listitem><para><emphasis>x11-sato:</emphasis> + Installs the OpenedHand Sato environment. </para></listitem> </itemizedlist> </para> + </section> <section id='ref-features-backfill'> diff --git a/documentation/ref-manual/ref-images.xml b/documentation/ref-manual/ref-images.xml index 7727e0a869..d15ca5b93a 100644 --- a/documentation/ref-manual/ref-images.xml +++ b/documentation/ref-manual/ref-images.xml @@ -13,153 +13,156 @@ </para> <note> - Building an image without GNU General Public License Version 3 (GPLv3) components + Building an image without GNU General Public License Version 3 (GPLv3), + GNU Lesser General Public License Version 3 (LGPLv3), and the + GNU Affero General Public License Version 3 (AGPL-3.0) components is only supported for minimal and base images. - Furthermore, if you are going to build an image using non-GPLv3 components, - you must make the following changes in the <filename>local.conf</filename> file - before using the BitBake command to build the minimal or base image: + Furthermore, if you are going to build an image using non-GPLv3 and + similarly licensed components, you must make the following changes in + the <filename>local.conf</filename> file before using the BitBake + command to build the minimal or base image: <literallayout class='monospaced'> 1. Comment out the EXTRA_IMAGE_FEATURES line - 2. Set INCOMPATIBLE_LICENSE = "GPLv3" + 2. Set INCOMPATIBLE_LICENSE = "GPL-3.0 LGPL-3.0 AGPL-3.0" </literallayout> </note> <para> - From within the <filename>poky</filename> Git repository, use the following command to list - the supported images: + From within the <filename>poky</filename> Git repository, you can use + the following command to display the list of directories within the + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> + that containe image recipe files: <literallayout class='monospaced'> $ ls meta*/recipes*/images/*.bb </literallayout> - These recipes reside in the <filename>meta/recipes-core/images</filename>, - <filename>meta/recipes-extended/images</filename>, - <filename>meta/recipes-graphics/images</filename>, - <filename>meta/recipes-qt/images</filename>, - <filename>meta/recipes-rt/images</filename>, - <filename>meta/recipes-sato/images</filename>, and - <filename>meta-skeleton/recipes-multilib/images</filename> directories - within the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. - Although the recipe names are somewhat explanatory, here is a list that describes them: </para> - <itemizedlist> - <listitem><para><emphasis><filename>build-appliance-image</filename>:</emphasis> - An example virtual machine that contains all the pieces required to - run builds using the build system as well as the build system itself. - You can boot and run the image using either the - <ulink url='http://www.vmware.com/products/player/overview.html'>VMware Player</ulink> - or <ulink url='http://www.vmware.com/products/workstation/overview.html'>VMware Workstation</ulink>. - For more information on this image, see the - <ulink url='&YOCTO_HOME_URL;/documentation/build-appliance'>Build Appliance</ulink> page on - the Yocto Project website.</para></listitem> - <listitem><para><emphasis><filename>core-image-base</filename>:</emphasis> - A console-only image that fully supports the target device hardware.</para></listitem> - <listitem><para><emphasis><filename>core-image-minimal</filename>:</emphasis> - A small image just capable of allowing a device to boot.</para></listitem> - <listitem><para><emphasis><filename>core-image-minimal-dev</filename>:</emphasis> - A <filename>core-image-minimal</filename> image suitable for development work - using the host. - The image includes headers and libraries you can use in a host development - environment. - </para></listitem> - <listitem><para id='images-core-image-minimal-initramfs'><emphasis><filename>core-image-minimal-initramfs</filename>:</emphasis> - A <filename>core-image-minimal</filename> image that has the Minimal RAM-based - Initial Root Filesystem (initramfs) as part of the kernel, - which allows the system to find the first “init” program more efficiently. - See the - <link linkend='var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></link> - variable for additional information helpful when working with - initramfs images. - </para></listitem> - <listitem><para><emphasis><filename>core-image-minimal-mtdutils</filename>:</emphasis> - A <filename>core-image-minimal</filename> image that has support - for the Minimal MTD Utilities, which let the user interact with the - MTD subsystem in the kernel to perform operations on flash devices. - </para></listitem> - <listitem><para><emphasis><filename>core-image-full-cmdline</filename>:</emphasis> - A console-only image with more full-featured Linux system - functionality installed.</para></listitem> - <listitem><para><emphasis><filename>core-image-lsb</filename>:</emphasis> - An image that conforms to the Linux Standard Base (LSB) - specification. - This image requires a distribution configuration that - enables LSB compliance (e.g. <filename>poky-lsb</filename>). - If you build <filename>core-image-lsb</filename> without that - configuration, the image will not be LSB-compliant. - </para></listitem> - <listitem><para><emphasis><filename>core-image-lsb-dev</filename>:</emphasis> - A <filename>core-image-lsb</filename> image that is suitable for development work - using the host. - The image includes headers and libraries you can use in a host development - environment. - This image requires a distribution configuration that - enables LSB compliance (e.g. <filename>poky-lsb</filename>). - If you build <filename>core-image-lsb-dev</filename> without that - configuration, the image will not be LSB-compliant. - </para></listitem> - <listitem><para><emphasis><filename>core-image-lsb-sdk</filename>:</emphasis> - A <filename>core-image-lsb</filename> that includes everything in - meta-toolchain but also includes development headers and libraries - to form a complete standalone SDK. - This image requires a distribution configuration that - enables LSB compliance (e.g. <filename>poky-lsb</filename>). - If you build <filename>core-image-lsb-sdk</filename> without that - configuration, the image will not be LSB-compliant. - This image is suitable for development using the target.</para></listitem> - <listitem><para><emphasis><filename>core-image-testmaster</filename>:</emphasis> - A "master" image designed to be used for automated runtime testing. - Provides a "known good" image that is deployed to a separate - partition so that you can boot into it and use it to deploy a - second image to be tested. - You can find more information about runtime testing in the - "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>" - section in the Yocto Project Development Manual. - </para></listitem> - <listitem><para><emphasis><filename>core-image-clutter</filename>:</emphasis> - An image with support for the Open GL-based toolkit Clutter, which enables development of - rich and animated graphical user interfaces.</para></listitem> - <listitem><para><emphasis><filename>core-image-directfb</filename>:</emphasis> - An image that uses <filename>directfb</filename> instead of X11. - </para></listitem> - <listitem><para><emphasis><filename>core-image-x11</filename>:</emphasis> - A very basic X11 image with a terminal. - </para></listitem> - <listitem><para><emphasis><filename>core-image-weston</filename>:</emphasis> - A very basic Wayland image with a terminal. - This image provides the Wayland protocol libraries and the - reference Weston compositor. - For more information, see the - "<link linkend='wayland'>Wayland</link>" section. - </para></listitem> - <listitem><para><emphasis><filename>qt4e-demo-image</filename>:</emphasis> - An image that launches into the demo application for the embedded - (not based on X11) version of Qt.</para></listitem> - <listitem><para><emphasis><filename>core-image-rt</filename>:</emphasis> - A <filename>core-image-minimal</filename> image plus a real-time test suite and - tools appropriate for real-time use.</para></listitem> - <listitem><para><emphasis><filename>core-image-rt-sdk</filename>:</emphasis> - A <filename>core-image-rt</filename> image that includes everything in - <filename>meta-toolchain</filename>. - The image also includes development headers and libraries to form a complete - stand-alone SDK and is suitable for development using the target. - </para></listitem> - <listitem><para><emphasis><filename>core-image-sato</filename>:</emphasis> - An image with Sato support, a mobile environment and visual style that works well - with mobile devices. - The image supports X11 with a Sato theme and applications such as - a terminal, editor, file manager, media player, and so forth. - </para></listitem> - <listitem><para><emphasis><filename>core-image-sato-dev</filename>:</emphasis> - A <filename>core-image-sato</filename> image suitable for development - using the host. - The image includes libraries needed to build applications on the device itself, - testing and profiling tools, and debug symbols. - This image was formerly <filename>core-image-sdk</filename>. - </para></listitem> - <listitem><para><emphasis><filename>core-image-sato-sdk</filename>:</emphasis> - A <filename>core-image-sato</filename> image that includes everything in meta-toolchain. - The image also includes development headers and libraries to form a complete standalone SDK - and is suitable for development using the target.</para></listitem> - </itemizedlist> + <para> + Following is a list of supported recipes: + <itemizedlist> + <listitem><para><filename>build-appliance-image</filename>: + An example virtual machine that contains all the pieces required to + run builds using the build system as well as the build system itself. + You can boot and run the image using either the + <ulink url='http://www.vmware.com/products/player/overview.html'>VMware Player</ulink> + or <ulink url='http://www.vmware.com/products/workstation/overview.html'>VMware Workstation</ulink>. + For more information on this image, see the + <ulink url='&YOCTO_HOME_URL;/documentation/build-appliance'>Build Appliance</ulink> page on + the Yocto Project website.</para></listitem> + <listitem><para><filename>core-image-base</filename>: + A console-only image that fully supports the target device hardware.</para></listitem> + <listitem><para><filename>core-image-clutter</filename>: + An image with support for the Open GL-based toolkit Clutter, which enables development of + rich and animated graphical user interfaces.</para></listitem> + <listitem><para><filename>core-image-directfb</filename>: + An image that uses <filename>directfb</filename> instead of X11. + </para></listitem> + <listitem><para><filename>core-image-full-cmdline</filename>: + A console-only image with more full-featured Linux system + functionality installed.</para></listitem> + <listitem><para><filename>core-image-lsb</filename>: + An image that conforms to the Linux Standard Base (LSB) + specification. + This image requires a distribution configuration that + enables LSB compliance (e.g. <filename>poky-lsb</filename>). + If you build <filename>core-image-lsb</filename> without that + configuration, the image will not be LSB-compliant. + </para></listitem> + <listitem><para><filename>core-image-lsb-dev</filename>: + A <filename>core-image-lsb</filename> image that is suitable for development work + using the host. + The image includes headers and libraries you can use in a host development + environment. + This image requires a distribution configuration that + enables LSB compliance (e.g. <filename>poky-lsb</filename>). + If you build <filename>core-image-lsb-dev</filename> without that + configuration, the image will not be LSB-compliant. + </para></listitem> + <listitem><para><filename>core-image-lsb-sdk</filename>: + A <filename>core-image-lsb</filename> that includes everything in + meta-toolchain but also includes development headers and libraries + to form a complete standalone SDK. + This image requires a distribution configuration that + enables LSB compliance (e.g. <filename>poky-lsb</filename>). + If you build <filename>core-image-lsb-sdk</filename> without that + configuration, the image will not be LSB-compliant. + This image is suitable for development using the target.</para></listitem> + <listitem><para><filename>core-image-minimal</filename>: + A small image just capable of allowing a device to boot.</para></listitem> + <listitem><para><filename>core-image-minimal-dev</filename>: + A <filename>core-image-minimal</filename> image suitable for development work + using the host. + The image includes headers and libraries you can use in a host development + environment. + </para></listitem> + <listitem><para id='images-core-image-minimal-initramfs'><filename>core-image-minimal-initramfs</filename>: + A <filename>core-image-minimal</filename> image that has the Minimal RAM-based + Initial Root Filesystem (initramfs) as part of the kernel, + which allows the system to find the first “init” program more efficiently. + See the + <link linkend='var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></link> + variable for additional information helpful when working with + initramfs images. + </para></listitem> + <listitem><para><filename>core-image-minimal-mtdutils</filename>: + A <filename>core-image-minimal</filename> image that has support + for the Minimal MTD Utilities, which let the user interact with the + MTD subsystem in the kernel to perform operations on flash devices. + </para></listitem> + <listitem><para><filename>core-image-rt</filename>: + A <filename>core-image-minimal</filename> image plus a real-time test suite and + tools appropriate for real-time use.</para></listitem> + <listitem><para><filename>core-image-rt-sdk</filename>: + A <filename>core-image-rt</filename> image that includes everything in + <filename>meta-toolchain</filename>. + The image also includes development headers and libraries to form a complete + stand-alone SDK and is suitable for development using the target. + </para></listitem> + <listitem><para><filename>core-image-sato</filename>: + An image with Sato support, a mobile environment and visual style that works well + with mobile devices. + The image supports X11 with a Sato theme and applications such as + a terminal, editor, file manager, media player, and so forth. + </para></listitem> + <listitem><para><filename>core-image-sato-dev</filename>: + A <filename>core-image-sato</filename> image suitable for development + using the host. + The image includes libraries needed to build applications on the device itself, + testing and profiling tools, and debug symbols. + This image was formerly <filename>core-image-sdk</filename>. + </para></listitem> + <listitem><para><filename>core-image-sato-sdk</filename>: + A <filename>core-image-sato</filename> image that includes everything in meta-toolchain. + The image also includes development headers and libraries to form a complete standalone SDK + and is suitable for development using the target.</para></listitem> + <listitem><para><filename>core-image-testmaster</filename>: + A "master" image designed to be used for automated runtime testing. + Provides a "known good" image that is deployed to a separate + partition so that you can boot into it and use it to deploy a + second image to be tested. + You can find more information about runtime testing in the + "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>" + section in the Yocto Project Development Manual. + </para></listitem> + <listitem><para><filename>core-image-testmaster-initramfs</filename>: + A RAM-based Initial Root Filesystem (initramfs) image tailored for + use with the <filename>core-image-testmaster</filename> image. + </para></listitem> + <listitem><para><filename>core-image-weston</filename>: + A very basic Wayland image with a terminal. + This image provides the Wayland protocol libraries and the + reference Weston compositor. + For more information, see the + "<link linkend='wayland'>Wayland</link>" section. + </para></listitem> + <listitem><para><filename>core-image-x11</filename>: + A very basic X11 image with a terminal. + </para></listitem> + <listitem><para><filename>qt4e-demo-image</filename>: + An image that launches into the demo application for the embedded + (not based on X11) version of Qt.</para></listitem> + </itemizedlist> + </para> </chapter> <!-- vim: expandtab tw=80 ts=4 diff --git a/documentation/ref-manual/ref-manual-customization.xsl b/documentation/ref-manual/ref-manual-customization.xsl index 05c9b979b1..1bee3bd5d3 100644 --- a/documentation/ref-manual/ref-manual-customization.xsl +++ b/documentation/ref-manual/ref-manual-customization.xsl @@ -1,7 +1,7 @@ <?xml version='1.0'?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0"> - <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl" /> + <xsl:import href="http://docbook.sourceforge.net/release/xsl/1.76.1/xhtml/docbook.xsl" /> <xsl:include href="../template/permalinks.xsl"/> <xsl:include href="../template/section.title.xsl"/> @@ -9,6 +9,7 @@ <xsl:include href="../template/division.title.xsl"/> <xsl:include href="../template/formal.object.heading.xsl"/> <xsl:include href="../template/gloss-permalinks.xsl"/> + <xsl:include href="../template/qa-code-permalinks.xsl"/> <xsl:param name="html.stylesheet" select="'ref-style.css'" /> <xsl:param name="chapter.autolabel" select="1" /> diff --git a/documentation/ref-manual/ref-manual.xml b/documentation/ref-manual/ref-manual.xml index 3eff7de712..cf586e721d 100644 --- a/documentation/ref-manual/ref-manual.xml +++ b/documentation/ref-manual/ref-manual.xml @@ -84,9 +84,14 @@ </revision> <revision> <revnumber>1.7</revnumber> - <date>Fall of 2014</date> + <date>October 2014</date> <revremark>Released with the Yocto Project 1.7 Release.</revremark> </revision> + <revision> + <revnumber>1.8</revnumber> + <date>Sometime in 2015</date> + <revremark>Released with the Yocto Project 1.8 Release.</revremark> + </revision> </revhistory> <copyright> diff --git a/documentation/ref-manual/ref-qa-checks.xml b/documentation/ref-manual/ref-qa-checks.xml index 15c1bbe4f5..871cd294f6 100644 --- a/documentation/ref-manual/ref-qa-checks.xml +++ b/documentation/ref-manual/ref-qa-checks.xml @@ -59,10 +59,21 @@ <section id='qa-errors-and-warnings'> <title>Errors and Warnings</title> +<!-- +This section uses the <para><code> construct to enable permalinks for the +various QA issue and warning messages. The file templates/qa-code-permalinks.xsl +is used to locate the construct and generate the permalink. This solution +leverages the fact that right now this section in the ref-manual is the only +place is all the YP docs that uses the <para><code> construct. If, in the +future, that construct were to appear in the ref-manual, a generic permalink +would be generated for the text between <code></code>. If a better solution +can be found then it should be implemented. I can't find one at the moment. +--> + <para> <itemizedlist> <listitem> - <para> + <para id='qa-issue-libexec'> <code> <packagename>: <path> is using libexec please relocate to <libexecdir> [libexec] </code> @@ -87,7 +98,7 @@ <para> <itemizedlist> <listitem> - <para> + <para id='qa-issue-rpaths'> <code> package <packagename> contains bad RPATH <rpath> in file <file> [rpaths] </code> @@ -119,7 +130,7 @@ <para> <itemizedlist> <listitem> - <para> + <para id='qa-issue-useless-rpaths'> <code> <packagename>: <file> contains probably-redundant RPATH <rpath> [useless-rpaths] </code> @@ -147,7 +158,63 @@ <para> <itemizedlist> <listitem> + <para id='qa-issue-file-rdeps'> + <code> + <packagename> requires <files>, but no providers in its RDEPENDS [file-rdeps] + </code> + </para> + <para> + A file-level dependency has been identified from the + specified package on the specified files, but there is + no explicit corresponding entry in + <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>. + If particular files are required at runtime then + <filename>RDEPENDS</filename> should be declared in the + recipe to ensure the packages providing them are built. + </para> + + <para> + + </para> + </listitem> + </itemizedlist> + </para> + + <para> + <itemizedlist> + <listitem> + <para id='qa-issue-build-deps'> + <code> + <packagename1> rdepends on <packagename2>, but it isn't a build dependency? [build-deps] + </code> + </para> + + <para> + A runtime dependency exists between the two specified + packages, but there is nothing explicit within the recipe + to enable the OpenEmbedded build system to ensure that + dependency is satisfied. + This condition is usually triggered by an + <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> + value being added at the packaging stage rather than up + front, which is usually automatic based on the contents of + the package. + In most cases, you should change the recipe to add an + explicit <filename>RDEPENDS</filename> for the dependency. + </para> + + <para> + + </para> + </listitem> + </itemizedlist> + </para> + + <para> + <itemizedlist> + <listitem> + <para id='qa-issue-dev-so'> <code> non -dev/-dbg/-nativesdk package contains symlink .so: <packagename> path '<path>' [dev-so] </code> @@ -178,7 +245,7 @@ <para> <itemizedlist> <listitem> - <para> + <para id='qa-issue-staticdev'> <code> non -staticdev package contains static .a library: <packagename> path '<path>' [staticdev] </code> @@ -205,7 +272,7 @@ <para> <itemizedlist> <listitem> - <para> + <para id='qa-issue-libdir'> <code> <packagename>: found library in wrong location [libdir] </code> @@ -236,7 +303,7 @@ <para> <itemizedlist> <listitem> - <para> + <para id='qa-issue-debug-files'> <code> non debug package contains .debug directory: <packagename> path <path> [debug-files] </code> @@ -269,7 +336,7 @@ <para> <itemizedlist> <listitem> - <para> + <para id='qa-issue-arch'> <code> Architecture did not match (<machine_arch> to <file_arch>) on <file> [arch] </code> @@ -308,7 +375,7 @@ <para> <itemizedlist> <listitem> - <para> + <para id='qa-issue-arch-bit-size-no-match'> <code> Bit size did not match (<machine_bits> to <file_bits>) <recipe> on <file> [arch] </code> @@ -347,7 +414,7 @@ <para> <itemizedlist> <listitem> - <para> + <para id='qa-issue-arch-endianness-no-match'> <code> Endianness did not match (<machine_endianness> to <file_endianness>) on <file> [arch] </code> @@ -386,7 +453,7 @@ <para> <itemizedlist> <listitem> - <para> + <para id='qa-issue-textrel'> <code> ELF binary '<file>' has relocations in .text [textrel] </code> @@ -397,13 +464,6 @@ <filename>.text</filename> sections. This situation can result in a performance impact at runtime. - <note> - A bug currently exists that causes this - warning to appear erroneously. - See - <ulink url='https://bugzilla.yoctoproject.org/show_bug.cgi?id=6104'></ulink> - for more information. - </note> </para> <para> @@ -416,7 +476,7 @@ <para> <itemizedlist> <listitem> - <para> + <para id='qa-issue-ldflags'> <code> No GNU_HASH in the elf binary: '<file>' [ldflags] </code> @@ -448,7 +508,7 @@ <para> <itemizedlist> <listitem> - <para> + <para id='qa-issue-xorg-driver-abi'> <code> Package <packagename> contains Xorg driver (<driver>) but no xorg-abi- dependencies [xorg-driver-abi] </code> @@ -478,7 +538,7 @@ <para> <itemizedlist> <listitem> - <para> + <para id='qa-issue-infodir'> <code> The /usr/share/info/dir file is not meant to be shipped in a particular package. [infodir] </code> @@ -506,7 +566,7 @@ <para> <itemizedlist> <listitem> - <para> + <para id='qa-issue-symlink-to-sysroot'> <code> Symlink <path> in <packagename> points to TMPDIR [symlink-to-sysroot] </code> @@ -533,7 +593,7 @@ <para> <itemizedlist> <listitem> - <para> + <para id='qa-issue-la'> <code> <file> failed sanity test (workdir) in path <path> [la] </code> @@ -559,7 +619,7 @@ <para> <itemizedlist> <listitem> - <para> + <para id='qa-issue-pkgconfig'> <code> <file> failed sanity test (tmpdir) in path <path> [pkgconfig] </code> @@ -584,7 +644,7 @@ <para> <itemizedlist> <listitem> - <para> + <para id='qa-issue-debug-deps'> <code> <packagename> rdepends on <debug_packagename> [debug-deps] </code> @@ -632,7 +692,7 @@ <para> <itemizedlist> <listitem> - <para> + <para id='qa-issue-dev-deps'> <code> <packagename> rdepends on <dev_packagename> [dev-deps] </code> @@ -667,7 +727,7 @@ files that it should not have (e.g. a non-symlink <filename>.so</filename> file) or it might have been added manually (e.g. by adding to - <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>. + <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>). </para> <para> @@ -680,7 +740,7 @@ <para> <itemizedlist> <listitem> - <para> + <para id='qa-issue-dep-cmp'> <code> <var>_<packagename> is invalid: <comparison> (<value>) only comparisons <, =, >, <=, and >= are allowed [dep-cmp] </code> @@ -711,7 +771,7 @@ <para> <itemizedlist> <listitem> - <para> + <para id='qa-issue-compile-host-path'> <code> <recipename>: The compile log indicates that host include and/or library paths were used. Please check the log '<logfile>' for more information. [compile-host-path] </code> @@ -736,7 +796,7 @@ <para> <itemizedlist> <listitem> - <para> + <para id='qa-issue-install-host-path'> <code> <recipename>: The install log indicates that host include and/or library paths were used. Please check the log '<logfile>' for more information. [install-host-path] </code> @@ -761,7 +821,7 @@ <para> <itemizedlist> <listitem> - <para> + <para id='qa-issue-autoconf-log'> <code> This autoconf log indicates errors, it looked at host include and/or library paths while determining system capabilities. Rerun configure task after fixing this. The path was '<path>' </code> @@ -786,7 +846,7 @@ <para> <itemizedlist> <listitem> - <para> + <para id='qa-issue-pkgname'> <code> <packagename> doesn't match the [a-z0-9.+-]+ regex [pkgname] </code> @@ -818,7 +878,7 @@ <para> <itemizedlist> <listitem> - <para> + <para id='qa-issue-unknown-configure-option'> <code> <recipe>: configure was passed unrecognized options: <options> [unknown-configure-option] </code> @@ -854,7 +914,7 @@ <para> <itemizedlist> <listitem> - <para> + <para id='qa-issue-pn-overrides'> <code> Recipe <recipefile> has PN of "<recipename>" which is in OVERRIDES, this can result in unexpected behavior. [pn-overrides] </code> @@ -894,7 +954,7 @@ <para> <itemizedlist> <listitem> - <para> + <para id='qa-issue-pkgvarcheck'> <code> <recipefile>: Variable <variable> is set as not being package specific, please fix this. [pkgvarcheck] </code> @@ -932,7 +992,7 @@ <para> <itemizedlist> <listitem> - <para> + <para id='qa-issue-already-stripped'> <code> File '<file>' from <recipename> was already stripped, this will prevent future debugging! [already-stripped] </code> @@ -977,7 +1037,7 @@ <para> <itemizedlist> <listitem> - <para> + <para id='qa-issue-packages-list'> <code> <packagename> is listed in PACKAGES multiple times, this leads to packaging errors. [packages-list] </code> @@ -1002,7 +1062,7 @@ <para> <itemizedlist> <listitem> - <para> + <para id='qa-issue-files-invalid'> <code> FILES variable for package <packagename> contains '//' which is invalid. Attempting to fix this but you should correct the metadata. [files-invalid] </code> @@ -1025,7 +1085,7 @@ <para> <itemizedlist> <listitem> - <para> + <para id='qa-issue-installed-vs-shipped'> <code> <recipename>: Files/directories were installed but not shipped [installed-vs-shipped] </code> @@ -1065,7 +1125,7 @@ <para> <itemizedlist> <listitem> - <para> + <para id='qa-issue-old-and-new-package-and-version-names'> <code> <oldpackage>-<oldpkgversion> was registered as shlib provider for <library>, changing it to <newpackage>-<newpkgversion> because it was built later </code> @@ -1151,7 +1211,6 @@ enabled by default: </note> </para> </section> - </chapter> <!-- vim: expandtab tw=80 ts=4 diff --git a/documentation/ref-manual/ref-structure.xml b/documentation/ref-manual/ref-structure.xml index 389e75ad97..14419d3a84 100644 --- a/documentation/ref-manual/ref-structure.xml +++ b/documentation/ref-manual/ref-structure.xml @@ -63,9 +63,8 @@ </para> <para> - For more information on BitBake, see the BitBake documentation - included in the <filename>bitbake/doc/manual</filename> directory of the - <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. + For more information on BitBake, see the + <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>. </para> </section> @@ -316,7 +315,7 @@ commands. Following is the script syntax: <literallayout class='monospaced'> - $ source oe-init-build-env-memres <port_number> <build_dir> + $ source oe-init-build-env-memres <replaceable>port_number</replaceable> <replaceable>build_dir</replaceable> </literallayout> The script uses other scripts within the <filename>scripts</filename> directory to do the bulk of the work. @@ -500,7 +499,7 @@ the variable in the top-level build environment setup script as follows: <literallayout class='monospaced'> - TEMPLATECONF=<your_layer>/conf + TEMPLATECONF=<replaceable>your_layer</replaceable>/conf </literallayout> Once the build process gets the sample file, it uses <filename>sed</filename> to substitute final @@ -555,7 +554,7 @@ you can base your build from any layer by setting the variable in the top-level build environment setup script as follows: <literallayout class='monospaced'> - TEMPLATECONF=<your_layer>/conf + TEMPLATECONF=<replaceable>your_layer</replaceable>/conf </literallayout> Once the build process gets the sample file, it uses <filename>sed</filename> to substitute final diff --git a/documentation/ref-manual/ref-style.css b/documentation/ref-manual/ref-style.css index e04b5006b4..e77ba718b3 100644 --- a/documentation/ref-manual/ref-style.css +++ b/documentation/ref-manual/ref-style.css @@ -201,8 +201,17 @@ div.variablelist dl { .variablelist dl dt, .variablelist dl dt span.term { font-weight: normal; - width: 20em; + width: 0em; text-align: right; + margin-top: 4em; + margin-left: .5em; + margin-bottom: 0em; + -webkit-column-count: 2; /* Chrome, Safari, Opera */ + -moz-column-count: 2; /* Firefox */ + column-count: 2; + -webkit-column-gap: 4px; /* Chrome, Safari, Opera */ + -moz-column-gap: 4px; /* Firefox */ + column-gap: 4px; } .variablelist dl dt { @@ -211,8 +220,8 @@ div.variablelist dl { .glossary dl dd, .variablelist dl dd { - margin-top: -1em; - margin-left: 25.5em; + margin-top: -3.5em; + margin-left: 15.5em; } .glossary dd p, diff --git a/documentation/ref-manual/ref-tasks.xml b/documentation/ref-manual/ref-tasks.xml index fc23a7ba0d..f325f0e233 100644 --- a/documentation/ref-manual/ref-tasks.xml +++ b/documentation/ref-manual/ref-tasks.xml @@ -129,6 +129,17 @@ </para> </section> + <section id='ref-tasks-package_qa'> + <title><filename>do_package_qa</filename></title> + + <para> + Runs QA checks on packaged files. + For more information on these checks, see the + <link linkend='ref-classes-insane'><filename>insane</filename></link> + class. + </para> + </section> + <section id='ref-tasks-package_write_deb'> <title><filename>do_package_write_deb</filename></title> @@ -313,7 +324,7 @@ <para> You can run this task using BitBake as follows: <literallayout class='monospaced'> - $ bitbake -c clean <recipe> + $ bitbake -c clean <replaceable>recipe</replaceable> </literallayout> </para> @@ -327,7 +338,7 @@ If you want to remove the sstate cache files for the recipe, you need to use the <link linkend='ref-tasks-cleansstate'><filename>do_cleansstate</filename></link> - task instead (i.e. <filename>bitbake -c cleansstate <recipe></filename>). + task instead (i.e. <filename>bitbake -c cleansstate</filename> <replaceable>recipe</replaceable>). </para> </section> @@ -348,7 +359,7 @@ <para> You can run this task using BitBake as follows: <literallayout class='monospaced'> - $ bitbake -c cleanall <recipe> + $ bitbake -c cleanall <replaceable>recipe</replaceable> </literallayout> </para> @@ -378,7 +389,7 @@ <para> You can run this task using BitBake as follows: <literallayout class='monospaced'> - $ bitbake -c cleansstate <recipe> + $ bitbake -c cleansstate <replaceable>recipe</replaceable> </literallayout> </para> @@ -393,7 +404,7 @@ If you need to build a target from scratch using remote mirrors, use the "-f" option as follows: <literallayout class='monospaced'> - $ bitbake -f -c do_cleansstate <target> + $ bitbake -f -c do_cleansstate <replaceable>target</replaceable> </literallayout> </note> </para> diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml index cb43016fe2..e3272fec79 100644 --- a/documentation/ref-manual/ref-variables.xml +++ b/documentation/ref-manual/ref-variables.xml @@ -20,9 +20,9 @@ <link linkend='var-B'>B</link> <link linkend='var-CFLAGS'>C</link> <link linkend='var-D'>D</link> - <link linkend='var-ENABLE_BINARY_LOCALE_GENERATION'>E</link> + <link linkend='var-EFI_PROVIDER'>E</link> <link linkend='var-FEATURE_PACKAGES'>F</link> - <link linkend='var-GROUPADD_PARAM'>G</link> + <link linkend='var-GLIBC_GENERATE_LOCALES'>G</link> <link linkend='var-HOMEPAGE'>H</link> <link linkend='var-ICECC_DISABLED'>I</link> <!-- <link linkend='var-glossary-j'>J</link> --> @@ -39,14 +39,17 @@ <link linkend='var-UBOOT_CONFIG'>U</link> <!-- <link linkend='var-glossary-v'>V</link> --> <link linkend='var-WARN_QA'>W</link> -<!-- <link linkend='var-glossary-x'>X</link> --> + <link linkend='var-XSERVER'>X</link> <!-- <link linkend='var-glossary-y'>Y</link> --> <!-- <link linkend='var-glossary-z'>Z</link>--> </para> <glossdiv id='var-glossary-a'><title>A</title> - <glossentry id='var-ABIEXTENSION'><glossterm>ABIEXTENSION</glossterm> + <glossentry id='var-ABIEXTENSION'><glossterm><imagedata fileref="figures/define-generic.png" />ABIEXTENSION</glossterm> + <info> + ABIEXTENSION[doc] = "Extension to the Application Binary Interface (ABI) field of the GNU canonical architecture name (e.g. "eabi")." + </info> <glossdef> <para> Extension to the Application Binary Interface (ABI) @@ -66,7 +69,10 @@ </glossdef> </glossentry> - <glossentry id='var-ALLOW_EMPTY'><glossterm>ALLOW_EMPTY</glossterm> + <glossentry id='var-ALLOW_EMPTY'><glossterm><imagedata fileref="figures/define-generic.png" />ALLOW_EMPTY</glossterm> + <info> + ALLOW_EMPTY[doc] = "Specifies if an output package should still be produced if it is empty." + </info> <glossdef> <para> Specifies if an output package should still be produced if it is empty. @@ -86,9 +92,12 @@ </literallayout> </para> </glossdef> - </glossentry> + </glossentry> - <glossentry id='var-ALTERNATIVE'><glossterm>ALTERNATIVE</glossterm> + <glossentry id='var-ALTERNATIVE'><glossterm><imagedata fileref="figures/define-generic.png" />ALTERNATIVE</glossterm> + <info> + ALTERNATIVE[doc] = "Lists commands in a package that need an alternative binary naming scheme." + </info> <glossdef> <para> Lists commands in a package that need an alternative @@ -113,9 +122,12 @@ section. </para> </glossdef> - </glossentry> + </glossentry> - <glossentry id='var-ALTERNATIVE_LINK_NAME'><glossterm>ALTERNATIVE_LINK_NAME</glossterm> + <glossentry id='var-ALTERNATIVE_LINK_NAME'><glossterm><imagedata fileref="figures/define-generic.png" />ALTERNATIVE_LINK_NAME</glossterm> + <info> + ALTERNATIVE_LINK_NAME[doc] = "Used by the alternatives system to map duplicated commands to actual locations." + </info> <glossdef> <para> Used by the alternatives system to map duplicated commands @@ -136,7 +148,7 @@ <note> If <filename>ALTERNATIVE_LINK_NAME</filename> is not defined, it defaults to - <filename>${bindir}/<name></filename>. + <filename>${bindir}/<replaceable>name</replaceable></filename>. </note> </para> @@ -146,9 +158,12 @@ section. </para> </glossdef> - </glossentry> + </glossentry> - <glossentry id='var-ALTERNATIVE_PRIORITY'><glossterm>ALTERNATIVE_PRIORITY</glossterm> + <glossentry id='var-ALTERNATIVE_PRIORITY'><glossterm><imagedata fileref="figures/define-generic.png" />ALTERNATIVE_PRIORITY</glossterm> + <info> + ALTERNATIVE_PRIORITY[doc] = "Used by the alternatives system to create default priorities for duplicated commands." + </info> <glossdef> <para> Used by the alternatives system to create default @@ -159,9 +174,9 @@ a default for specific commands tied to particular packages. Here are the available syntax forms: <literallayout class='monospaced'> - ALTERNATIVE_PRIORITY = "<priority>" - ALTERNATIVE_PRIORITY[<name>] = "<priority>" - ALTERNATIVE_PRIORITY_<pkg>[<name>] = "<priority>" + ALTERNATIVE_PRIORITY = "<replaceable>priority</replaceable>" + ALTERNATIVE_PRIORITY[<replaceable>name</replaceable>] = "<replaceable>priority</replaceable>" + ALTERNATIVE_PRIORITY_<replaceable>pkg</replaceable>[<replaceable>name</replaceable>] = "<replaceable>priority</replaceable>" </literallayout> </para> @@ -171,9 +186,12 @@ section. </para> </glossdef> - </glossentry> + </glossentry> - <glossentry id='var-ALTERNATIVE_TARGET'><glossterm>ALTERNATIVE_TARGET</glossterm> + <glossentry id='var-ALTERNATIVE_TARGET'><glossterm><imagedata fileref="figures/define-generic.png" />ALTERNATIVE_TARGET</glossterm> + <info> + ALTERNATIVE_TARGET[doc] = "Used by the alternatives system to create default link locations for duplicated commands." + </info> <glossdef> <para> Used by the alternatives system to create default link @@ -185,9 +203,9 @@ a default for specific commands tied to particular packages. Here are the available syntax forms: <literallayout class='monospaced'> - ALTERNATIVE_TARGET = "<target>" - ALTERNATIVE_TARGET[<name>] = "<target>" - ALTERNATIVE_TARGET_<pkg>[<name>] = "<target>" + ALTERNATIVE_TARGET = "<replaceable>target</replaceable>" + ALTERNATIVE_TARGET[<replaceable>name</replaceable>] = "<replaceable>target</replaceable>" + ALTERNATIVE_TARGET_<replaceable>pkg</replaceable>[<replaceable>name</replaceable>] = "<replaceable>target</replaceable>" </literallayout> <note> <para> @@ -222,9 +240,12 @@ section. </para> </glossdef> - </glossentry> + </glossentry> - <glossentry id='var-APPEND'><glossterm>APPEND</glossterm> + <glossentry id='var-APPEND'><glossterm><imagedata fileref="figures/define-generic.png" />APPEND</glossterm> + <info> + APPEND[doc] = "An override list of append strings for each LABEL." + </info> <glossdef> <para> An override list of append strings for each @@ -237,32 +258,65 @@ class for more information on how this variable is used. </para> </glossdef> - </glossentry> + </glossentry> - <glossentry id='var-AUTHOR'><glossterm>AUTHOR</glossterm> + <glossentry id='var-ASSUME_PROVIDED'><glossterm><imagedata fileref="figures/define-generic.png" />ASSUME_PROVIDED</glossterm> + <info> + ASSUME_PROVIDED[doc] = "Lists recipe names (PN values) BitBake does not attempt to build." + </info> + <glossdef> + <para> + Lists recipe names + (<link linkend='var-PN'><filename>PN</filename></link> + values) BitBake does not attempt to build. + Instead, BitBake assumes these recipes have already been + built. + </para> + + <para> + In OpenEmbedded Core, <filename>ASSUME_PROVIDED</filename> + mostly specifies native tools that should not be built. + An example is <filename>git-native</filename>, which when + specified, allows for the Git binary from the host to be + used rather than building <filename>git-native</filename>. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-AUTHOR'><glossterm><imagedata fileref="figures/define-generic.png" />AUTHOR</glossterm> + <info> + AUTHOR[doc] = "Email address used to contact the original author or authors in order to send patches and forward bugs." + </info> <glossdef> <para>The email address used to contact the original author or authors in order to send patches and forward bugs.</para> </glossdef> - </glossentry> + </glossentry> - <glossentry id='var-AUTO_SYSLINUXMENU'><glossterm>AUTO_SYSLINUXMENU</glossterm> + <glossentry id='var-AUTO_SYSLINUXMENU'><glossterm><imagedata fileref="figures/define-generic.png" />AUTO_SYSLINUXMENU</glossterm> + <info> + AUTO_SYSLINUXMENU[doc] = "Enables creating an automatic menu for the syslinux bootloader." + </info> <glossdef> <para> - Enables creating an automatic menu. - You must set this in your recipe. + Enables creating an automatic menu for the syslinux + bootloader. + You must set this variable in your recipe. The <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link> class checks this variable. </para> </glossdef> - </glossentry> + </glossentry> - <glossentry id='var-AUTOREV'><glossterm>AUTOREV</glossterm> + <glossentry id='var-AUTOREV'><glossterm><imagedata fileref="figures/define-generic.png" />AUTOREV</glossterm> + <info> + AUTOREV[doc] = "When SRCREV is set to the value of this variable, it specifies to use the latest source revision in the repository." + </info> <glossdef> <para>When <filename><link linkend='var-SRCREV'>SRCREV</link></filename> - is set to the value of this variable, it specifies to use the latest - source revision in the repository. + is set to the value of this variable, it specifies to use + the latest source revision in the repository. Here is an example: <literallayout class='monospaced'> SRCREV = "${AUTOREV}" @@ -271,9 +325,12 @@ </glossdef> </glossentry> - <glossentry id='var-AVAILTUNES'><glossterm>AVAILTUNES</glossterm> + <glossentry id='var-AVAILTUNES'><glossterm><imagedata fileref="figures/define-generic.png" />AVAILTUNES</glossterm> + <info> + AVAILTUNES[doc] = "The list of defined CPU and Application Binary Interface (ABI) tunings (i.e. "tunes") available for use by the OpenEmbedded build system." + </info> <glossdef> - <para> + <para id='var-define-AVAILTUNES'> The list of defined CPU and Application Binary Interface (ABI) tunings (i.e. "tunes") available for use by the OpenEmbedded build system. @@ -298,12 +355,14 @@ </glossdef> </glossentry> - </glossdiv> <glossdiv id='var-glossary-b'><title>B</title> - <glossentry id='var-B'><glossterm>B</glossterm> + <glossentry id='var-B'><glossterm><imagedata fileref="figures/define-generic.png" />B</glossterm> + <info> + B[doc] = "The Build Directory. The OpenEmbedded build system places generated objects into the Build Directory during a recipe's build process." + </info> <glossdef> <para> The directory within the @@ -326,7 +385,10 @@ </glossdef> </glossentry> - <glossentry id='var-BAD_RECOMMENDATIONS'><glossterm>BAD_RECOMMENDATIONS</glossterm> + <glossentry id='var-BAD_RECOMMENDATIONS'><glossterm><imagedata fileref="figures/define-generic.png" />BAD_RECOMMENDATIONS</glossterm> + <info> + BAD_RECOMMENDATIONS[doc] = "A list of packages not to install despite being recommended by a recipe. Support for this variable exists only when using the IPK packaging backend." + </info> <glossdef> <para> Lists "recommended-only" packages to not install. @@ -338,13 +400,13 @@ being installed by listing them with the <filename>BAD_RECOMMENDATIONS</filename> variable: <literallayout class='monospaced'> - BAD_RECOMMENDATIONS = "<package_name> <package_name> <package_name> ..." + BAD_RECOMMENDATIONS = "<replaceable>package_name</replaceable> <replaceable>package_name</replaceable> <replaceable>package_name</replaceable> ..." </literallayout> You can set this variable globally in your <filename>local.conf</filename> file or you can attach it to a specific image recipe by using the recipe name override: <literallayout class='monospaced'> - BAD_RECOMMENDATIONS_pn-<target_image> = "<package_name>" + BAD_RECOMMENDATIONS_pn-<replaceable>target_image</replaceable> = "<replaceable>package_name</replaceable>" </literallayout> </para> @@ -374,7 +436,10 @@ </glossdef> </glossentry> - <glossentry id='var-BASE_LIB'><glossterm>BASE_LIB</glossterm> + <glossentry id='var-BASE_LIB'><glossterm><imagedata fileref="figures/define-generic.png" />BASE_LIB</glossterm> + <info> + BASE_LIB[doc] = "The library directory name for the CPU or Application Binary Interface (ABI) tune." + </info> <glossdef> <para> The library directory name for the CPU or Application @@ -396,7 +461,10 @@ </glossdef> </glossentry> - <glossentry id='var-BB_DANGLINGAPPENDS_WARNONLY'><glossterm>BB_DANGLINGAPPENDS_WARNONLY</glossterm> + <glossentry id='var-BB_DANGLINGAPPENDS_WARNONLY'><glossterm><imagedata fileref="figures/define-generic.png" />BB_DANGLINGAPPENDS_WARNONLY</glossterm> + <info> + BB_DANGLINGAPPENDS_WARNONLY[doc] = "Defines how BitBake handles situations where an append file (.bbappend) has no corresponding recipe file (.bb)." + </info> <glossdef> <para> Defines how BitBake handles situations where an append @@ -430,7 +498,10 @@ </glossdef> </glossentry> - <glossentry id='var-BB_DISKMON_DIRS'><glossterm>BB_DISKMON_DIRS</glossterm> + <glossentry id='var-BB_DISKMON_DIRS'><glossterm><imagedata fileref="figures/define-generic.png" />BB_DISKMON_DIRS</glossterm> + <info> + BB_DISKMON_DIRS[doc] = "Monitors disk space and available inodes during the build and allows you to control the build based on these parameters." + </info> <glossdef> <para> Monitors disk space and available inodes during the build @@ -445,11 +516,11 @@ <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. Use the following form: <literallayout class='monospaced'> - BB_DISKMON_DIRS = "<action>,<dir>,<threshold> [...]" + BB_DISKMON_DIRS = "<replaceable>action</replaceable>,<replaceable>dir</replaceable>,<replaceable>threshold</replaceable> [...]" where: - <action> is: + <replaceable>action</replaceable> is: ABORT: Immediately abort the build when a threshold is broken. STOPTASKS: Stop the build after the currently @@ -463,14 +534,14 @@ which must be defined in the conf/local.conf file. - <dir> is: + <replaceable>dir</replaceable> is: Any directory you choose. You can specify one or more directories to monitor by separating the groupings with a space. If two directories are on the same device, only the first directory is monitored. - <threshold> is: + <replaceable>threshold</replaceable> is: Either the minimum available disk space, the minimum number of free inodes, or both. You must specify at least one. To @@ -525,7 +596,10 @@ </glossdef> </glossentry> - <glossentry id='var-BB_DISKMON_WARNINTERVAL'><glossterm>BB_DISKMON_WARNINTERVAL</glossterm> + <glossentry id='var-BB_DISKMON_WARNINTERVAL'><glossterm><imagedata fileref="figures/define-generic.png" />BB_DISKMON_WARNINTERVAL</glossterm> + <info> + BB_DISKMON_WARNINTERVAL[doc] = "Defines the disk space and free inode warning intervals. To set these intervals, define the variable in the conf/local.conf file in the Build Directory." + </info> <glossdef> <para> Defines the disk space and free inode warning intervals. @@ -559,16 +633,16 @@ When specifying the variable in your configuration file, use the following form: <literallayout class='monospaced'> - BB_DISKMON_WARNINTERVAL = "<disk_space_interval>,<disk_inode_interval>" + BB_DISKMON_WARNINTERVAL = "<replaceable>disk_space_interval</replaceable>,<replaceable>disk_inode_interval</replaceable>" where: - <disk_space_interval> is: + <replaceable>disk_space_interval</replaceable> is: An interval of memory expressed in either G, M, or K for Gbytes, Mbytes, or Kbytes, respectively. You cannot use GB, MB, or KB. - <disk_inode_interval> is: + <replaceable>disk_inode_interval</replaceable> is: An interval of free inodes expressed in either G, M, or K for Gbytes, Mbytes, or Kbytes, respectively. You cannot use GB, MB, or KB. @@ -593,7 +667,10 @@ </glossdef> </glossentry> - <glossentry id='var-BB_GENERATE_MIRROR_TARBALLS'><glossterm>BB_GENERATE_MIRROR_TARBALLS</glossterm> + <glossentry id='var-BB_GENERATE_MIRROR_TARBALLS'><glossterm><imagedata fileref="figures/define-generic.png" />BB_GENERATE_MIRROR_TARBALLS</glossterm> + <info> + BB_GENERATE_MIRROR_TARBALLS[doc] = "Causes tarballs of the Git repositories to be placed in the DL_DIR directory." + </info> <glossdef> <para> Causes tarballs of the Git repositories, including the @@ -616,13 +693,16 @@ </glossdef> </glossentry> - <glossentry id='var-BB_NUMBER_THREADS'><glossterm>BB_NUMBER_THREADS</glossterm> + <glossentry id='var-BB_NUMBER_THREADS'><glossterm><imagedata fileref="figures/define-generic.png" />BB_NUMBER_THREADS</glossterm> + <info> + BB_NUMBER_THREADS[doc] = "The maximum number of tasks BitBake should run in parallel at any one time. A good rule of thumb is for this variable to be twice the number of cores." + </info> <glossdef> <para> The maximum number of tasks BitBake should run in parallel at any one time. If your host development system supports multiple cores, - a good rule of thumb is to set this variable to twice the + a good rule of thumb is to have this variable be twice the number of cores. </para> @@ -633,7 +713,10 @@ </glossdef> </glossentry> - <glossentry id='var-BBCLASSEXTEND'><glossterm>BBCLASSEXTEND</glossterm> + <glossentry id='var-BBCLASSEXTEND'><glossterm><imagedata fileref="figures/define-generic.png" />BBCLASSEXTEND</glossterm> + <info> + BBCLASSEXTEND[doc] = "Allows you to extend a recipe so that it builds variants of the software. Common variants for recipes are 'native', 'cross', 'nativesdk' and multilibs." + </info> <glossdef> <para> Allows you to extend a recipe so that it builds variants of the software. @@ -643,7 +726,7 @@ which is a compiler built to run on the build machine but produces binaries that run on the target <link linkend='var-MACHINE'><filename>MACHINE</filename></link>; "nativesdk", which targets the SDK machine instead of <filename>MACHINE</filename>; - and "mulitlibs" in the form "<filename>multilib:<multilib_name></filename>". + and "mulitlibs" in the form "<filename>multilib:</filename><replaceable>multilib_name</replaceable>". </para> <para> @@ -651,13 +734,16 @@ is as simple as adding the following to your recipe: <literallayout class='monospaced'> BBCLASSEXTEND =+ "native nativesdk" - BBCLASSEXTEND =+ "multilib:<multilib_name>" + BBCLASSEXTEND =+ "multilib:<replaceable>multilib_name</replaceable>" </literallayout> </para> </glossdef> </glossentry> - <glossentry id='var-BBFILE_COLLECTIONS'><glossterm>BBFILE_COLLECTIONS</glossterm> + <glossentry id='var-BBFILE_COLLECTIONS'><glossterm><imagedata fileref="figures/define-generic.png" />BBFILE_COLLECTIONS</glossterm> + <info> + BBFILE_COLLECTIONS[doc] = "Lists the names of configured layers. These names are used to find the other BBFILE_* variables." + </info> <glossdef> <para>Lists the names of configured layers. These names are used to find the other <filename>BBFILE_*</filename> @@ -668,7 +754,10 @@ </glossdef> </glossentry> - <glossentry id='var-BBFILE_PATTERN'><glossterm>BBFILE_PATTERN</glossterm> + <glossentry id='var-BBFILE_PATTERN'><glossterm><imagedata fileref="figures/define-generic.png" />BBFILE_PATTERN</glossterm> + <info> + BBFILE_PATTERN[doc] = "Variable that expands to match files from BBFILES in a particular layer. This variable is used in the layer.conf file and must be suffixed with the name of a layer." + </info> <glossdef> <para>Variable that expands to match files from <link linkend='var-BBFILES'><filename>BBFILES</filename></link> @@ -679,7 +768,10 @@ </glossdef> </glossentry> - <glossentry id='var-BBFILE_PRIORITY'><glossterm>BBFILE_PRIORITY</glossterm> + <glossentry id='var-BBFILE_PRIORITY'><glossterm><imagedata fileref="figures/define-generic.png" />BBFILE_PRIORITY</glossterm> + <info> + BBFILE_PRIORITY[doc] = "Assigns the priority for recipe files in each layer. Setting this variable allows you to prioritize a layer against other layers that contain the same recipe." + </info> <glossdef> <para>Assigns the priority for recipe files in each layer.</para> <para>This variable is useful in situations where the same recipe appears in @@ -710,19 +802,28 @@ </glossdef> </glossentry> - <glossentry id='var-BBFILES'><glossterm>BBFILES</glossterm> + <glossentry id='var-BBFILES'><glossterm><imagedata fileref="figures/define-generic.png" />BBFILES</glossterm> + <info> + BBFILES[doc] = "List of recipe files used by BitBake to build software." + </info> <glossdef> <para>List of recipe files used by BitBake to build software.</para> </glossdef> </glossentry> - <glossentry id='var-BBINCLUDELOGS'><glossterm>BBINCLUDELOGS</glossterm> + <glossentry id='var-BBINCLUDELOGS'><glossterm><imagedata fileref="figures/define-generic.png" />BBINCLUDELOGS</glossterm> + <info> + BBINCLUDELOGS[doc] = "Variable that controls how BitBake displays logs on build failure." + </info> <glossdef> <para>Variable that controls how BitBake displays logs on build failure.</para> </glossdef> </glossentry> - <glossentry id='var-BBLAYERS'><glossterm>BBLAYERS</glossterm> + <glossentry id='var-BBLAYERS'><glossterm><imagedata fileref="figures/define-generic.png" />BBLAYERS</glossterm> + <info> + BBLAYERS[doc] = "Lists the layers to enable during the build. This variable is defined in the bblayers.conf configuration file." + </info> <glossdef> <para>Lists the layers to enable during the build. This variable is defined in the <filename>bblayers.conf</filename> configuration @@ -747,7 +848,10 @@ </glossdef> </glossentry> - <glossentry id='var-BBLAYERS_NON_REMOVABLE'><glossterm>BBLAYERS_NON_REMOVABLE</glossterm> + <glossentry id='var-BBLAYERS_NON_REMOVABLE'><glossterm><imagedata fileref="figures/define-generic.png" />BBLAYERS_NON_REMOVABLE</glossterm> + <info> + BBLAYERS_NON_REMOVABLE[doc] = "Lists core layers that cannot be removed from the bblayers.conf file." + </info> <glossdef> <para>Lists core layers that cannot be removed from the <filename>bblayers.conf</filename> file during a build @@ -780,8 +884,11 @@ </glossdef> </glossentry> - <glossentry id='var-BBMASK'><glossterm>BBMASK</glossterm> + <glossentry id='var-BBMASK'><glossterm><imagedata fileref="figures/define-generic.png" />BBMASK</glossterm> <glossdef> + <info> + BBMASK[doc] = "Prevents BitBake from processing specific recipes or recipe append files. Use the BBMASK variable from within conf/local.conf." + </info> <para> Prevents BitBake from processing recipes and recipe append files. @@ -840,7 +947,10 @@ </glossdef> </glossentry> - <glossentry id='var-BBPATH'><glossterm>BBPATH</glossterm> + <glossentry id='var-BBPATH'><glossterm><imagedata fileref="figures/define-generic.png" />BBPATH</glossterm> + <info> + BBPATH[doc] = "Used by BitBake to locate .bbclass and configuration files. This variable is analogous to the PATH variable." + </info> <glossdef> <para> Used by BitBake to locate @@ -856,16 +966,19 @@ Set the variable as you would any environment variable and then run BitBake: <literallayout class='monospaced'> - $ BBPATH = "<build_directory>" + $ BBPATH = "<replaceable>build_directory</replaceable>" $ export BBPATH - $ bitbake <target> + $ bitbake <replaceable>target</replaceable> </literallayout> </note> </para> </glossdef> </glossentry> - <glossentry id='var-BBSERVER'><glossterm>BBSERVER</glossterm> + <glossentry id='var-BBSERVER'><glossterm><imagedata fileref="figures/define-generic.png" />BBSERVER</glossterm> + <info> + BBSERVER[doc] = "Points to the server that runs memory-resident BitBake." + </info> <glossdef> <para> Points to the server that runs memory-resident BitBake. @@ -887,11 +1000,42 @@ </glossdef> </glossentry> - <glossentry id='var-BINCONFIG_GLOB'><glossterm>BINCONFIG_GLOB</glossterm> + <glossentry id='var-BINCONFIG'><glossterm><imagedata fileref="figures/define-generic.png" />BINCONFIG</glossterm> + <info> + BINCONFIG[doc] = "When inheriting the binconfig-disabled class, this variable specifies binary configuration scripts to disable in favor of using pkg-config to query the information." + </info> <glossdef> <para> - When inheriting <filename>binconfig.bbclass</filename> - from a recipe, this variable specifies a wildcard for + When inheriting the + <link linkend='ref-classes-binconfig-disabled'><filename>binconfig-disabled</filename></link> + class, this variable specifies binary configuration + scripts to disable in favor of using + <filename>pkg-config</filename> to query the information. + The <filename>binconfig-disabled</filename> class will + modify the specified scripts to return an error so that + calls to them can be easily found and replaced. + </para> + + <para> + To add multiple scripts, separate them by spaces. + Here is an example from the <filename>libpng</filename> + recipe: + <literallayout class='monospaced'> + BINCONFIG = "${bindir}/libpng-config ${bindir}/libpng16-config" + </literallayout> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BINCONFIG_GLOB'><glossterm><imagedata fileref="figures/define-generic.png" />BINCONFIG_GLOB</glossterm> + <info> + BINCONFIG_GLOB[doc] = "When inheriting binconfig.bbclass from a recipe, this variable specifies a wildcard for configuration scripts that need editing." + </info> + <glossdef> + <para> + When inheriting the + <link linkend='ref-classes-binconfig'><filename>binconfig</filename></link> + class, this variable specifies a wildcard for configuration scripts that need editing. The scripts are edited to correct any paths that have been set up during compilation so that they are correct for @@ -910,7 +1054,10 @@ </glossdef> </glossentry> - <glossentry id='var-BP'><glossterm>BP</glossterm> + <glossentry id='var-BP'><glossterm><imagedata fileref="figures/define-generic.png" />BP</glossterm> + <info> + BP[doc] = "The base recipe name and version but without any special recipe name suffix (i.e. -native, lib64-, and so forth). BP is comprised of ${BPN}-${PV}" + </info> <glossdef> <para>The base recipe name and version but without any special recipe name suffix (i.e. <filename>-native</filename>, <filename>lib64-</filename>, @@ -922,7 +1069,10 @@ </glossdef> </glossentry> - <glossentry id='var-BPN'><glossterm>BPN</glossterm> + <glossentry id='var-BPN'><glossterm><imagedata fileref="figures/define-generic.png" />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." + </info> <glossdef> <para>The bare name of the recipe. This variable is a version of the <link linkend='var-PN'><filename>PN</filename></link> variable @@ -937,7 +1087,10 @@ </glossdef> </glossentry> - <glossentry id='var-BUGTRACKER'><glossterm>BUGTRACKER</glossterm> + <glossentry id='var-BUGTRACKER'><glossterm><imagedata fileref="figures/define-generic.png" />BUGTRACKER</glossterm> + <info> + BUGTRACKER[doc] = "Specifies a URL for an upstream bug tracking website for a recipe." + </info> <glossdef> <para> Specifies a URL for an upstream bug tracking website for @@ -949,7 +1102,10 @@ </glossdef> </glossentry> - <glossentry id='var-BUILD_CFLAGS'><glossterm>BUILD_CFLAGS</glossterm> + <glossentry id='var-BUILD_CFLAGS'><glossterm><imagedata fileref="figures/define-generic.png" />BUILD_CFLAGS</glossterm> + <info> + BUILD_CFLAGS[doc] = "Specifies the flags to pass to the C compiler when building for the build host." + </info> <glossdef> <para> Specifies the flags to pass to the C compiler when building @@ -961,7 +1117,10 @@ </glossdef> </glossentry> - <glossentry id='var-BUILD_CPPFLAGS'><glossterm>BUILD_CPPFLAGS</glossterm> + <glossentry id='var-BUILD_CPPFLAGS'><glossterm><imagedata fileref="figures/define-generic.png" />BUILD_CPPFLAGS</glossterm> + <info> + BUILD_CPPFLAGS[doc] = "Specifies the flags to pass to the C pre-processor (i.e. to both the C and the C++ compilers) when building for the build host." + </info> <glossdef> <para> Specifies the flags to pass to the C pre-processor @@ -974,7 +1133,10 @@ </glossdef> </glossentry> - <glossentry id='var-BUILD_CXXFLAGS'><glossterm>BUILD_CXXFLAGS</glossterm> + <glossentry id='var-BUILD_CXXFLAGS'><glossterm><imagedata fileref="figures/define-generic.png" />BUILD_CXXFLAGS</glossterm> + <info> + BUILD_CXXFLAGS[doc] = "Specifies the flags to pass to the C++ compiler when building for the build host." + </info> <glossdef> <para> Specifies the flags to pass to the C++ compiler when @@ -986,7 +1148,10 @@ </glossdef> </glossentry> - <glossentry id='var-BUILD_LDFLAGS'><glossterm>BUILD_LDFLAGS</glossterm> + <glossentry id='var-BUILD_LDFLAGS'><glossterm><imagedata fileref="figures/define-generic.png" />BUILD_LDFLAGS</glossterm> + <info> + BUILD_LDFLAGS[doc] = "Specifies the flags to pass to the linker when building for the build host." + </info> <glossdef> <para> Specifies the flags to pass to the linker when building @@ -998,7 +1163,10 @@ </glossdef> </glossentry> - <glossentry id='var-BUILD_OPTIMIZATION'><glossterm>BUILD_OPTIMIZATION</glossterm> + <glossentry id='var-BUILD_OPTIMIZATION'><glossterm><imagedata fileref="figures/define-generic.png" />BUILD_OPTIMIZATION</glossterm> + <info> + BUILD_OPTIMIZATION[doc] = "Specifies the optimization flags passed to the C compiler when building for the build host or the SDK." + </info> <glossdef> <para> Specifies the optimization flags passed to the C compiler @@ -1018,7 +1186,10 @@ </glossdef> </glossentry> - <glossentry id='var-BUILDDIR'><glossterm>BUILDDIR</glossterm> + <glossentry id='var-BUILDDIR'><glossterm><imagedata fileref="figures/define-generic.png" />BUILDDIR</glossterm> + <info> + BUILDDIR[doc] = "Points to the location of the Build Directory." + </info> <glossdef> <para> Points to the location of the @@ -1036,13 +1207,16 @@ </glossdef> </glossentry> - <glossentry id='var-BUILDHISTORY_COMMIT'><glossterm>BUILDHISTORY_COMMIT</glossterm> + <glossentry id='var-BUILDHISTORY_COMMIT'><glossterm><imagedata fileref="figures/define-generic.png" />BUILDHISTORY_COMMIT</glossterm> + <info> + BUILDHISTORY_COMMIT[doc] = "When inheriting the buildhistory class, this variable specifies whether or not to commit the build history output in a local Git repository." + </info> <glossdef> <para> When inheriting the <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link> - class, specifies whether or not to commit the build - history output in a local Git repository. + class, this variable specifies whether or not to commit the + build history output in a local Git repository. If set to "1", this local repository will be maintained automatically by the <filename>buildhistory</filename> @@ -1064,12 +1238,16 @@ </glossdef> </glossentry> - <glossentry id='var-BUILDHISTORY_COMMIT_AUTHOR'><glossterm>BUILDHISTORY_COMMIT_AUTHOR</glossterm> + <glossentry id='var-BUILDHISTORY_COMMIT_AUTHOR'><glossterm><imagedata fileref="figures/define-generic.png" />BUILDHISTORY_COMMIT_AUTHOR</glossterm> + <info> + BUILDHISTORY_COMMIT_AUTHOR[doc] = "When inheriting the buildhistory class, this variable specifies the author to use for each Git commit." + </info> <glossdef> <para> When inheriting the <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link> - class, specifies the author to use for each Git commit. + class, this variable specifies the author to use for each + Git commit. In order for the <filename>BUILDHISTORY_COMMIT_AUTHOR</filename> variable to work, the <link linkend='var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT</filename></link> @@ -1094,13 +1272,16 @@ </glossdef> </glossentry> - <glossentry id='var-BUILDHISTORY_DIR'><glossterm>BUILDHISTORY_DIR</glossterm> + <glossentry id='var-BUILDHISTORY_DIR'><glossterm><imagedata fileref="figures/define-generic.png" />BUILDHISTORY_DIR</glossterm> + <info> + BUILDHISTORY_DIR[doc] = "When inheriting the buildhistory class, this variable specifies the directory in which build history information is kept." + </info> <glossdef> <para> When inheriting the <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link> - class, specifies the directory in which build history - information is kept. + class, this variable specifies the directory in which + build history information is kept. For more information on how the variable works, see the <filename>buildhistory.class</filename>. </para> @@ -1115,12 +1296,16 @@ </glossdef> </glossentry> - <glossentry id='var-BUILDHISTORY_FEATURES'><glossterm>BUILDHISTORY_FEATURES</glossterm> + <glossentry id='var-BUILDHISTORY_FEATURES'><glossterm><imagedata fileref="figures/define-generic.png" />BUILDHISTORY_FEATURES</glossterm> + <info> + BUILDHISTORY_FEATURES[doc] = "When inheriting the buildhistory class, this variable specifies the build history features to be enabled." + </info> <glossdef> <para> When inheriting the <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link> - class, specifies the build history features to be enabled. + class, this variable specifies the build history features + to be enabled. For more information on how build history works, see the "<link linkend='maintaining-build-output-quality'>Maintaining Build Output Quality</link>" section. @@ -1155,12 +1340,16 @@ </glossdef> </glossentry> - <glossentry id='var-BUILDHISTORY_IMAGE_FILES'><glossterm>BUILDHISTORY_IMAGE_FILES</glossterm> + <glossentry id='var-BUILDHISTORY_IMAGE_FILES'><glossterm><imagedata fileref="figures/define-generic.png" />BUILDHISTORY_IMAGE_FILES</glossterm> + <info> + BUILDHISTORY_IMAGE_FILES[doc] = "When inheriting the buildhistory class, this variable specifies a list of paths to files copied from the image contents into the build history directory under an "image-files" directory in the directory for the image, so that you can track the contents of each file." + </info> <glossdef> <para> When inheriting the <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link> - class, specifies a list of paths to files copied from the + class, this variable specifies a list of paths to files + copied from the image contents into the build history directory under an "image-files" directory in the directory for the image, so that you can track the contents of each file. @@ -1183,13 +1372,16 @@ </glossdef> </glossentry> - <glossentry id='var-BUILDHISTORY_PUSH_REPO'><glossterm>BUILDHISTORY_PUSH_REPO</glossterm> + <glossentry id='var-BUILDHISTORY_PUSH_REPO'><glossterm><imagedata fileref="figures/define-generic.png" />BUILDHISTORY_PUSH_REPO</glossterm> + <info> + BUILDHISTORY_PUSH_REPO[doc] = "When inheriting the buildhistory class, this variable optionally specifies a remote repository to which build history pushes Git changes." + </info> <glossdef> <para> When inheriting the <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link> - class, optionally specifies a remote repository - to which build history pushes Git changes. + class, this variable optionally specifies a remote + repository to which build history pushes Git changes. In order for <filename>BUILDHISTORY_PUSH_REPO</filename> to work, <link linkend='var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT</filename></link> @@ -1214,7 +1406,10 @@ </glossdef> </glossentry> - <glossentry id='var-BUILDSDK_CFLAGS'><glossterm>BUILDSDK_CFLAGS</glossterm> + <glossentry id='var-BUILDSDK_CFLAGS'><glossterm><imagedata fileref="figures/define-generic.png" />BUILDSDK_CFLAGS</glossterm> + <info> + BUILDSDK_CFLAGS[doc] = "Specifies the flags to pass to the C compiler when building for the SDK." + </info> <glossdef> <para> Specifies the flags to pass to the C compiler when building @@ -1227,7 +1422,10 @@ </glossdef> </glossentry> - <glossentry id='var-BUILDSDK_CPPFLAGS'><glossterm>BUILDSDK_CPPFLAGS</glossterm> + <glossentry id='var-BUILDSDK_CPPFLAGS'><glossterm><imagedata fileref="figures/define-generic.png" />BUILDSDK_CPPFLAGS</glossterm> + <info> + BUILDSDK_CPPFLAGS[doc] = "Specifies the flags to pass to the C pre-processor (i.e. to both the C and the C++ compilers) when building for the SDK." + </info> <glossdef> <para> Specifies the flags to pass to the C pre-processor @@ -1241,7 +1439,10 @@ </glossdef> </glossentry> - <glossentry id='var-BUILDSDK_CXXFLAGS'><glossterm>BUILDSDK_CXXFLAGS</glossterm> + <glossentry id='var-BUILDSDK_CXXFLAGS'><glossterm><imagedata fileref="figures/define-generic.png" />BUILDSDK_CXXFLAGS</glossterm> + <info> + BUILDSDK_CXXFLAGS[doc] = "Specifies the flags to pass to the C++ compiler when building for the SDK." + </info> <glossdef> <para> Specifies the flags to pass to the C++ compiler when @@ -1254,7 +1455,10 @@ </glossdef> </glossentry> - <glossentry id='var-BUILDSDK_LDFLAGS'><glossterm>BUILDSDK_LDFLAGS</glossterm> + <glossentry id='var-BUILDSDK_LDFLAGS'><glossterm><imagedata fileref="figures/define-generic.png" />BUILDSDK_LDFLAGS</glossterm> + <info> + BUILDSDK_LDFLAGS[doc] = "Specifies the flags to pass to the linker when building for the SDK." + </info> <glossdef> <para> Specifies the flags to pass to the linker when building @@ -1267,7 +1471,10 @@ </glossdef> </glossentry> - <glossentry id='var-BUILDSTATS_BASE'><glossterm>BUILDSTATS_BASE</glossterm> + <glossentry id='var-BUILDSTATS_BASE'><glossterm><imagedata fileref="figures/define-generic.png" />BUILDSTATS_BASE</glossterm> + <info> + BUILDSTATS_BASE[doc] = "Points to the location of the directory that holds build statistics when you use and enable the buildstats class." + </info> <glossdef> <para> Points to the location of the directory that holds build @@ -1281,7 +1488,10 @@ </glossdef> </glossentry> - <glossentry id='var-BUSYBOX_SPLIT_SUID'><glossterm>BUSYBOX_SPLIT_SUID</glossterm> + <glossentry id='var-BUSYBOX_SPLIT_SUID'><glossterm><imagedata fileref="figures/define-generic.png" />BUSYBOX_SPLIT_SUID</glossterm> + <info> + BUSYBOX_SPLIT_SUID[doc] = "For the BusyBox recipe, specifies whether to split the output executable file into two parts: one for features that require setuid root, and one for the remaining features." + </info> <glossdef> <para> For the BusyBox recipe, specifies whether to split the @@ -1304,7 +1514,10 @@ <glossdiv id='var-glossary-c'><title>C</title> - <glossentry id='var-CFLAGS'><glossterm>CFLAGS</glossterm> + <glossentry id='var-CFLAGS'><glossterm><imagedata fileref="figures/define-generic.png" />CFLAGS</glossterm> + <info> + CFLAGS[doc] = "Flags passed to the C compiler for the target system. This variable evaluates to the same as TARGET_CFLAGS." + </info> <glossdef> <para> Specifies the flags to pass to the C compiler. @@ -1336,7 +1549,10 @@ </glossdef> </glossentry> - <glossentry id='var-CLASSOVERRIDE'><glossterm>CLASSOVERRIDE</glossterm> + <glossentry id='var-CLASSOVERRIDE'><glossterm><imagedata fileref="figures/define-generic.png" />CLASSOVERRIDE</glossterm> + <info> + CLASSOVERRIDE[doc] = "An internal variable specifying the special class override that should currently apply (e.g. "class-target", "class-native", and so forth)." + </info> <glossdef> <para> An internal variable specifying the special class override @@ -1362,7 +1578,10 @@ </glossdef> </glossentry> - <glossentry id='var-COMBINED_FEATURES'><glossterm>COMBINED_FEATURES</glossterm> + <glossentry id='var-COMBINED_FEATURES'><glossterm><imagedata fileref="figures/define-generic.png" />COMBINED_FEATURES</glossterm> + <info> + COMBINED_FEATURES[doc] = "A set of features common between MACHINE_FEATURES and DISTRO_FEATURES." + </info> <glossdef> <para> Provides a list of hardware features that are enabled in @@ -1388,7 +1607,10 @@ </glossdef> </glossentry> - <glossentry id='var-COMMON_LICENSE_DIR'><glossterm>COMMON_LICENSE_DIR</glossterm> + <glossentry id='var-COMMON_LICENSE_DIR'><glossterm><imagedata fileref="figures/define-generic.png" />COMMON_LICENSE_DIR</glossterm> + <info> + COMMON_LICENSE_DIR[doc] = "Points to meta/files/common-licenses in the Source Directory, which is where generic license files reside." + </info> <glossdef> <para> Points to <filename>meta/files/common-licenses</filename> @@ -1399,7 +1621,10 @@ </glossdef> </glossentry> - <glossentry id='var-COMPATIBLE_HOST'><glossterm>COMPATIBLE_HOST</glossterm> + <glossentry id='var-COMPATIBLE_HOST'><glossterm><imagedata fileref="figures/define-generic.png" />COMPATIBLE_HOST</glossterm> + <info> + COMPATIBLE_HOST[doc] = "A regular expression that resolves to one or more hosts (when the recipe is native) or one or more targets (when the recipe is non-native) with which a recipe is compatible." + </info> <glossdef> <para>A regular expression that resolves to one or more hosts (when the recipe is native) or one or more targets (when @@ -1416,7 +1641,10 @@ </glossdef> </glossentry> - <glossentry id='var-COMPATIBLE_MACHINE'><glossterm>COMPATIBLE_MACHINE</glossterm> + <glossentry id='var-COMPATIBLE_MACHINE'><glossterm><imagedata fileref="figures/define-generic.png" />COMPATIBLE_MACHINE</glossterm> + <info> + COMPATIBLE_MACHINE[doc] = "A regular expression that resolves to one or more target machines with which a recipe is compatible." + </info> <glossdef> <para>A regular expression that resolves to one or more target machines with which a recipe is compatible. @@ -1431,7 +1659,10 @@ </glossdef> </glossentry> - <glossentry id='var-COMPLEMENTARY_GLOB'><glossterm>COMPLEMENTARY_GLOB</glossterm> + <glossentry id='var-COMPLEMENTARY_GLOB'><glossterm><imagedata fileref="figures/define-generic.png" />COMPLEMENTARY_GLOB</glossterm> + <info> + COMPLEMENTARY_GLOB[doc] = "Defines wildcards to match when installing a list of complementary packages for all the packages installed in an image." + </info> <glossdef> <para> Defines wildcards to match when installing a list of @@ -1458,7 +1689,10 @@ </glossdef> </glossentry> - <glossentry id='var-CONFFILES'><glossterm>CONFFILES</glossterm> + <glossentry id='var-CONFFILES'><glossterm><imagedata fileref="figures/define-generic.png" />CONFFILES</glossterm> + <info> + CONFFILES[doc] = "Identifies editable or configurable files that are part of a package." + </info> <glossdef> <para> Identifies editable or configurable files that are part of a package. @@ -1508,7 +1742,10 @@ </glossdef> </glossentry> - <glossentry id='var-CONFIG_INITRAMFS_SOURCE'><glossterm>CONFIG_INITRAMFS_SOURCE</glossterm> + <glossentry id='var-CONFIG_INITRAMFS_SOURCE'><glossterm><imagedata fileref="figures/define-generic.png" />CONFIG_INITRAMFS_SOURCE</glossterm> + <info> + CONFIG_INITRAMFS_SOURCE[doc] = "Identifies the initial RAM disk (initramfs) source files. The OpenEmbedded build system receives and uses this kernel Kconfig variable as an environment variable." + </info> <glossdef> <para> Identifies the initial RAM disk (initramfs) source files. @@ -1540,7 +1777,10 @@ </glossdef> </glossentry> - <glossentry id='var-CONFIG_SITE'><glossterm>CONFIG_SITE</glossterm> + <glossentry id='var-CONFIG_SITE'><glossterm><imagedata fileref="figures/define-generic.png" />CONFIG_SITE</glossterm> + <info> + CONFIG_SITE[doc] = "A list of files that contains autoconf test results relevant to the current build. This variable is used by the Autotools utilities when running configure." + </info> <glossdef> <para> A list of files that contains <filename>autoconf</filename> test results relevant @@ -1551,11 +1791,15 @@ </glossdef> </glossentry> - <glossentry id='var-CONFLICT_DISTRO_FEATURES'><glossterm>CONFLICT_DISTRO_FEATURES</glossterm> + <glossentry id='var-CONFLICT_DISTRO_FEATURES'><glossterm><imagedata fileref="figures/define-generic.png" />CONFLICT_DISTRO_FEATURES</glossterm> + <info> + CONFLICT_DISTRO_FEATURES[doc] = "When a recipe inherits the distro_features_check class, this variable identifies distribution features that would be in conflict should the recipe be built." + </info> <glossdef> <para> - When a recipe inherits the - <filename>distro_features_check</filename> class, this + When inheriting the + <link linkend='ref-classes-distro_features_check'><filename>distro_features_check</filename></link> + class, this variable identifies distribution features that would be in conflict should the recipe be built. @@ -1569,7 +1813,10 @@ </glossdef> </glossentry> - <glossentry id='var-COPY_LIC_DIRS'><glossterm>COPY_LIC_DIRS</glossterm> + <glossentry id='var-COPY_LIC_DIRS'><glossterm><imagedata fileref="figures/define-generic.png" />COPY_LIC_DIRS</glossterm> + <info> + COPY_LIC_DIRS[doc] = "If set to "1" along with the COPY_LIC_MANIFEST variable, the OpenEmbedded build system copies into the image the license files, which are located in /usr/share/common-licenses, for each package." + </info> <glossdef> <para> If set to "1" along with the @@ -1584,7 +1831,10 @@ </glossdef> </glossentry> - <glossentry id='var-COPY_LIC_MANIFEST'><glossterm>COPY_LIC_MANIFEST</glossterm> + <glossentry id='var-COPY_LIC_MANIFEST'><glossterm><imagedata fileref="figures/define-generic.png" />COPY_LIC_MANIFEST</glossterm> + <info> + COPY_LIC_MANIFEST[doc] = "If set to "1", the OpenEmbedded build system copies the license manifest for the image to /usr/share/common-licenses/license.manifest within the image itself." + </info> <glossdef> <para> If set to "1", the OpenEmbedded build system copies @@ -1595,7 +1845,10 @@ </glossdef> </glossentry> - <glossentry id='var-CORE_IMAGE_EXTRA_INSTALL'><glossterm>CORE_IMAGE_EXTRA_INSTALL</glossterm> + <glossentry id='var-CORE_IMAGE_EXTRA_INSTALL'><glossterm><imagedata fileref="figures/define-generic.png" />CORE_IMAGE_EXTRA_INSTALL</glossterm> + <info> + CORE_IMAGE_EXTRA_INSTALL[doc] = "Specifies the list of packages to be added to the image. You should only set this variable in the conf/local.conf file in the Build Directory." + </info> <glossdef> <para> Specifies the list of packages to be added to the image. @@ -1611,7 +1864,10 @@ </glossdef> </glossentry> - <glossentry id='var-COREBASE'><glossterm>COREBASE</glossterm> + <glossentry id='var-COREBASE'><glossterm><imagedata fileref="figures/define-generic.png" />COREBASE</glossterm> + <info> + COREBASE[doc] = "Specifies the parent directory of the OpenEmbedded Core Metadata layer (i.e. meta)." + </info> <glossdef> <para> Specifies the parent directory of the OpenEmbedded @@ -1633,7 +1889,10 @@ </glossdef> </glossentry> - <glossentry id='var-CPPFLAGS'><glossterm>CPPFLAGS</glossterm> + <glossentry id='var-CPPFLAGS'><glossterm><imagedata fileref="figures/define-generic.png" />CPPFLAGS</glossterm> + <info> + CPPFLAGS[doc] = "Specifies the flags to pass to the C pre-processor (i.e. to both the C and the C++ compilers)." + </info> <glossdef> <para> Specifies the flags to pass to the C pre-processor @@ -1666,7 +1925,10 @@ </glossdef> </glossentry> - <glossentry id='var-CXXFLAGS'><glossterm>CXXFLAGS</glossterm> + <glossentry id='var-CXXFLAGS'><glossterm><imagedata fileref="figures/define-generic.png" />CXXFLAGS</glossterm> + <info> + CXXFLAGS[doc] = "Specifies the flags to pass to the C++ compiler." + </info> <glossdef> <para> Specifies the flags to pass to the C++ compiler. @@ -1702,7 +1964,10 @@ <glossdiv id='var-glossary-d'><title>D</title> - <glossentry id='var-D'><glossterm>D</glossterm> + <glossentry id='var-D'><glossterm><imagedata fileref="figures/define-generic.png" />D</glossterm> + <info> + D[doc] = "The destination directory." + </info> <glossdef> <para> The destination directory. @@ -1718,7 +1983,10 @@ </glossdef> </glossentry> - <glossentry id='var-DATETIME'><glossterm>DATETIME</glossterm> + <glossentry id='var-DATETIME'><glossterm><imagedata fileref="figures/define-generic.png" />DATETIME</glossterm> + <info> + DATETIME[doc] = "The date and time the build was started." + </info> <glossdef> <para> The date and time on which the current build started. @@ -1727,7 +1995,10 @@ </glossdef> </glossentry> - <glossentry id='var-DEBUG_BUILD'><glossterm>DEBUG_BUILD</glossterm> + <glossentry id='var-DEBUG_BUILD'><glossterm><imagedata fileref="figures/define-generic.png" />DEBUG_BUILD</glossterm> + <info> + DEBUG_BUILD[doc] = "Specifies to build packages with debugging information. This influences the value of the SELECTED_OPTIMIZATION variable." + </info> <glossdef> <para> Specifies to build packages with debugging information. @@ -1738,7 +2009,10 @@ </glossdef> </glossentry> - <glossentry id='var-DEBUG_OPTIMIZATION'><glossterm>DEBUG_OPTIMIZATION</glossterm> + <glossentry id='var-DEBUG_OPTIMIZATION'><glossterm><imagedata fileref="figures/define-generic.png" />DEBUG_OPTIMIZATION</glossterm> + <info> + DEBUG_OPTIMIZATION[doc] = "The options to pass in TARGET_CFLAGS and CFLAGS when compiling a system for debugging. This variable defaults to '-O -fno-omit-frame-pointer -g'." + </info> <glossdef> <para> The options to pass in @@ -1750,7 +2024,10 @@ </glossdef> </glossentry> - <glossentry id='var-DEFAULT_PREFERENCE'><glossterm>DEFAULT_PREFERENCE</glossterm> + <glossentry id='var-DEFAULT_PREFERENCE'><glossterm><imagedata fileref="figures/define-generic.png" />DEFAULT_PREFERENCE</glossterm> + <info> + DEFAULT_PREFERENCE[doc] = "Specifies a weak bias for recipe selection priority." + </info> <glossdef> <para> Specifies a weak bias for recipe selection priority. @@ -1774,7 +2051,10 @@ </glossdef> </glossentry> - <glossentry id='var-DEFAULTTUNE'><glossterm>DEFAULTTUNE</glossterm> + <glossentry id='var-DEFAULTTUNE'><glossterm><imagedata fileref="figures/define-generic.png" />DEFAULTTUNE</glossterm> + <info> + DEFAULTTUNE[doc] = "The default CPU and Application Binary Interface (ABI) tunings (i.e. the "tune") used by the OpenEmbedded build system." + </info> <glossdef> <para> The default CPU and Application Binary Interface (ABI) @@ -1795,7 +2075,10 @@ </glossdef> </glossentry> - <glossentry id='var-DEPENDS'><glossterm>DEPENDS</glossterm> + <glossentry id='var-DEPENDS'><glossterm><imagedata fileref="figures/define-generic.png" />DEPENDS</glossterm> + <info> + DEPENDS[doc] = "Lists a recipe's build-time dependencies (i.e. other recipe files)." + </info> <glossdef> <para> Lists a recipe's build-time dependencies @@ -1830,7 +2113,10 @@ </glossdef> </glossentry> - <glossentry id='var-DEPLOY_DIR'><glossterm>DEPLOY_DIR</glossterm> + <glossentry id='var-DEPLOY_DIR'><glossterm><imagedata fileref="figures/define-generic.png" />DEPLOY_DIR</glossterm> + <info> + DEPLOY_DIR[doc] = "Points to the general area that the OpenEmbedded build system uses to place images, packages, SDKs and other output files that are ready to be used outside of the build system." + </info> <glossdef> <para> Points to the general area that the OpenEmbedded build @@ -1855,7 +2141,10 @@ </glossdef> </glossentry> - <glossentry id='var-DEPLOY_DIR_IMAGE'><glossterm>DEPLOY_DIR_IMAGE</glossterm> + <glossentry id='var-DEPLOY_DIR_IMAGE'><glossterm><imagedata fileref="figures/define-generic.png" />DEPLOY_DIR_IMAGE</glossterm> + <info> + DEPLOY_DIR_IMAGE[doc] = "Points to the area that the OpenEmbedded build system uses to place images and other associated output files that are ready to be deployed onto the target machine." + </info> <glossdef> <para> Points to the area that the OpenEmbedded build system uses @@ -1882,10 +2171,13 @@ </glossdef> </glossentry> - <glossentry id='var-DEPLOYDIR'><glossterm>DEPLOYDIR</glossterm> + <glossentry id='var-DEPLOYDIR'><glossterm><imagedata fileref="figures/define-generic.png" />DEPLOYDIR</glossterm> + <info> + DEPLOYDIR[doc] = "For recipes that inherit the deploy class, the DEPLOYDIR points to a temporary work area for deployed files." + </info> <glossdef> <para> - For recipes that inherit the + When inheriting the <link linkend='ref-classes-deploy'><filename>deploy</filename></link> class, the <filename>DEPLOYDIR</filename> points to a temporary work area for deployed files that is set in the @@ -1903,7 +2195,10 @@ </glossdef> </glossentry> - <glossentry id='var-DESCRIPTION'><glossterm>DESCRIPTION</glossterm> + <glossentry id='var-DESCRIPTION'><glossterm><imagedata fileref="figures/define-generic.png" />DESCRIPTION</glossterm> + <info> + DESCRIPTION[doc] = "The package description used by package managers. If not set, DESCRIPTION takes the value of the SUMMARY variable." + </info> <glossdef> <para>The package description used by package managers. If not set, <filename>DESCRIPTION</filename> takes @@ -1914,7 +2209,10 @@ </glossdef> </glossentry> - <glossentry id='var-DISK_SIGNATURE'><glossterm>DISK_SIGNATURE</glossterm> + <glossentry id='var-DISK_SIGNATURE'><glossterm><imagedata fileref="figures/define-generic.png" />DISK_SIGNATURE</glossterm> + <info> + DISK_SIGNATURE[doc] = "A 32-bit MBR disk signature used by directdisk images." + </info> <glossdef> <para> A 32-bit MBR disk signature used by @@ -1964,7 +2262,10 @@ </glossdef> </glossentry> - <glossentry id='var-DISTRO'><glossterm>DISTRO</glossterm> + <glossentry id='var-DISTRO'><glossterm><imagedata fileref="figures/define-generic.png" />DISTRO</glossterm> + <info> + DISTRO[doc] = "The short name of the distribution. If the variable is blank, meta/conf/distro/defaultsetup.conf will be used." + </info> <glossdef> <para> The short name of the distribution. @@ -2006,7 +2307,10 @@ </glossdef> </glossentry> - <glossentry id='var-DISTRO_EXTRA_RDEPENDS'><glossterm>DISTRO_EXTRA_RDEPENDS</glossterm> + <glossentry id='var-DISTRO_EXTRA_RDEPENDS'><glossterm><imagedata fileref="figures/define-generic.png" />DISTRO_EXTRA_RDEPENDS</glossterm> + <info> + DISTRO_EXTRA_RDEPENDS[doc] = "Specifies a list of distro-specific packages to add to all images. The variable only applies to the images that include packagegroup-base." + </info> <glossdef> <para> Specifies a list of distro-specific packages to add to all images. @@ -2022,7 +2326,10 @@ </glossdef> </glossentry> - <glossentry id='var-DISTRO_EXTRA_RRECOMMENDS'><glossterm>DISTRO_EXTRA_RRECOMMENDS</glossterm> + <glossentry id='var-DISTRO_EXTRA_RRECOMMENDS'><glossterm><imagedata fileref="figures/define-generic.png" />DISTRO_EXTRA_RRECOMMENDS</glossterm> + <info> + DISTRO_EXTRA_RRECOMMENDS[doc] = "Specifies a list of distro-specific packages to add to all images if the packages exist. The list of packages are automatically installed but you can remove them." + </info> <glossdef> <para> Specifies a list of distro-specific packages to add to all images @@ -2034,7 +2341,10 @@ </glossdef> </glossentry> - <glossentry id='var-DISTRO_FEATURES'><glossterm>DISTRO_FEATURES</glossterm> + <glossentry id='var-DISTRO_FEATURES'><glossterm><imagedata fileref="figures/define-generic.png" />DISTRO_FEATURES</glossterm> + <info> + DISTRO_FEATURES[doc] = "The features enabled for the distribution." + </info> <glossdef> <para> The software support you want in your distribution for @@ -2067,7 +2377,10 @@ </glossdef> </glossentry> - <glossentry id='var-DISTRO_FEATURES_BACKFILL'><glossterm>DISTRO_FEATURES_BACKFILL</glossterm> + <glossentry id='var-DISTRO_FEATURES_BACKFILL'><glossterm><imagedata fileref="figures/define-generic.png" />DISTRO_FEATURES_BACKFILL</glossterm> + <info> + DISTRO_FEATURES_BACKFILL[doc] = "Features to be added to DISTRO_FEATURES if not also present in DISTRO_FEATURES_BACKFILL_CONSIDERED. This variable is set in the meta/conf/bitbake.conf file and it is not intended to be user-configurable." + </info> <glossdef> <para>Features to be added to <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename> @@ -2086,7 +2399,10 @@ </glossdef> </glossentry> - <glossentry id='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><glossterm>DISTRO_FEATURES_BACKFILL_CONSIDERED</glossterm> + <glossentry id='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><glossterm><imagedata fileref="figures/define-generic.png" />DISTRO_FEATURES_BACKFILL_CONSIDERED</glossterm> + <info> + DISTRO_FEATURES_BACKFILL_CONSIDERED[doc] = "Features from DISTRO_FEATURES_BACKFILL that should not be backfilled (i.e. added to DISTRO_FEATURES) during the build." + </info> <glossdef> <para>Features from <filename><link linkend='var-DISTRO_FEATURES_BACKFILL'>DISTRO_FEATURES_BACKFILL</link></filename> @@ -2099,13 +2415,19 @@ </glossdef> </glossentry> - <glossentry id='var-DISTRO_NAME'><glossterm>DISTRO_NAME</glossterm> + <glossentry id='var-DISTRO_NAME'><glossterm><imagedata fileref="figures/define-generic.png" />DISTRO_NAME</glossterm> + <info> + DISTRO_NAME[doc] = "The long name of the distribution." + </info> <glossdef> <para>The long name of the distribution.</para> </glossdef> </glossentry> - <glossentry id='var-DISTRO_PN_ALIAS'><glossterm>DISTRO_PN_ALIAS</glossterm> + <glossentry id='var-DISTRO_PN_ALIAS'><glossterm><imagedata fileref="figures/define-generic.png" />DISTRO_PN_ALIAS</glossterm> + <info> + DISTRO_PN_ALIAS[doc] = "Alias names used for the recipe in various Linux distributions." + </info> <glossdef> <para>Alias names used for the recipe in various Linux distributions.</para> <para>See the @@ -2115,13 +2437,19 @@ </glossdef> </glossentry> - <glossentry id='var-DISTRO_VERSION'><glossterm>DISTRO_VERSION</glossterm> + <glossentry id='var-DISTRO_VERSION'><glossterm><imagedata fileref="figures/define-generic.png" />DISTRO_VERSION</glossterm> + <info> + DISTRO_VERSION[doc] = "The version of the distribution." + </info> <glossdef> <para>The version of the distribution.</para> </glossdef> </glossentry> - <glossentry id='var-DISTROOVERRIDES'><glossterm>DISTROOVERRIDES</glossterm> + <glossentry id='var-DISTROOVERRIDES'><glossterm><imagedata fileref="figures/define-generic.png" />DISTROOVERRIDES</glossterm> + <info> + DISTROOVERRIDES[doc] = "Lists overrides specific to the current distribution. By default, the variable list includes the value of the DISTRO variable." + </info> <glossdef> <para> This variable lists overrides specific to the current @@ -2137,7 +2465,10 @@ </glossdef> </glossentry> - <glossentry id='var-DL_DIR'><glossterm>DL_DIR</glossterm> + <glossentry id='var-DL_DIR'><glossterm><imagedata fileref="figures/define-generic.png" />DL_DIR</glossterm> + <info> + DL_DIR[doc] = "The central download directory used by the build process to store downloads. By default, the directory is 'downloads' in the Build Directory." + </info> <glossdef> <para> The central download directory used by the build process to @@ -2191,38 +2522,75 @@ chapter. </para> </glossdef> + </glossentry> + + <glossentry id='var-DOC_COMPRESS'><glossterm><imagedata fileref="figures/define-generic.png" />DOC_COMPRESS</glossterm> + <info> + DOC_COMPRESS[doc] = "When inheriting the compress_doc class, this variable sets the compression policy used when the OpenEmbedded build system compresses man pages and info pages." + </info> + <glossdef> + <para> + When inheriting the + <link linkend='ref-classes-compress_doc'><filename>compress_doc</filename></link> + class, this variable sets the compression policy used when + the OpenEmbedded build system compresses man pages and info + pages. + By default, the compression method used is gz (gzip). + Other policies available are xz and bz2. + </para> + <para> + For information on policies and on how to use this + variable, see the comments in the + <filename>meta/classes/compress_doc.bbclass</filename> file. + </para> + </glossdef> </glossentry> + </glossdiv> <glossdiv id='var-glossary-e'><title>E</title> - <glossentry id='var-ENABLE_BINARY_LOCALE_GENERATION'><glossterm>ENABLE_BINARY_LOCALE_GENERATION</glossterm> + <glossentry id='var-EFI_PROVIDER'><glossterm><imagedata fileref="figures/define-generic.png" />EFI_PROVIDER</glossterm> + <info> + EFI_PROVIDER[doc] = "When building bootable images (i.e. where hddimg or vmdk is in IMAGE_FSTYPES), the EFI_PROVIDER variable specifies the EFI bootloader to use." + </info> <glossdef> - <para></para> - <para>Variable that controls which locales for - <filename>eglibc</filename> are generated during the - build (useful if the target device has 64Mbytes - of RAM or less).</para> + <para> + When building bootable images (i.e. where + <filename>hddimg</filename> or <filename>vmdk</filename> + is in + <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 + instead. + </para> + + <para> + See the + <link linkend='ref-classes-gummiboot'><filename>gummiboot</filename></link> + class for more information. + </para> </glossdef> </glossentry> - <glossentry id='var-ERROR_QA'><glossterm>ERROR_QA</glossterm> + <glossentry id='var-ENABLE_BINARY_LOCALE_GENERATION'><glossterm><imagedata fileref="figures/define-generic.png" />ENABLE_BINARY_LOCALE_GENERATION</glossterm> + <info> + ENABLE_BINARY_LOCALE_GENERATION[doc] = "Controls which locales for glibc are generated during the build. The variable is useful if the target device has 64Mbytes of RAM or less." + </info> <glossdef> - <para> - Specifies the quality assurance checks whose failures are - reported as errors by the OpenEmbedded build system. - You set this variable in your distribution configuration - file. - For a list of the checks you can control with this variable, - see the - "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>" - section. - </para> + <para>Variable that controls which locales for + <filename>eglibc</filename> are generated during the + build (useful if the target device has 64Mbytes + of RAM or less).</para> </glossdef> </glossentry> - <glossentry id='var-ERR_REPORT_DIR'><glossterm>ERR_REPORT_DIR</glossterm> + <glossentry id='var-ERR_REPORT_DIR'><glossterm><imagedata fileref="figures/define-generic.png" />ERR_REPORT_DIR</glossterm> + <info> + ERR_REPORT_DIR[doc] = "When used with the report-error class, specifies the path used for storing the debug files created by the error reporting tool, which allows you to submit build errors you encounter to a central database." + </info> <glossdef> <para> When used with the @@ -2241,13 +2609,34 @@ you want the error reporting tool to store the debug files as follows in your <filename>local.conf</filename> file: <literallayout class='monospaced'> - ERR_REPORT_DIR = "path" + ERR_REPORT_DIR = "<replaceable>path</replaceable>" </literallayout> </para> </glossdef> </glossentry> - <glossentry id='var-EXCLUDE_FROM_WORLD'><glossterm>EXCLUDE_FROM_WORLD</glossterm> + <glossentry id='var-ERROR_QA'><glossterm><imagedata fileref="figures/define-generic.png" />ERROR_QA</glossterm> + <info> + ERROR_QA[doc] = "Specifies the quality assurance checks whose failures are reported as errors by the OpenEmbedded build system." + </info> + <glossdef> + <para> + Specifies the quality assurance checks whose failures are + reported as errors by the OpenEmbedded build system. + You set this variable in your distribution configuration + file. + For a list of the checks you can control with this variable, + see the + "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>" + section. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-EXCLUDE_FROM_WORLD'><glossterm><imagedata fileref="figures/define-generic.png" />EXCLUDE_FROM_WORLD</glossterm> + <info> + EXCLUDE_FROM_WORLD[doc] = "Directs BitBake to exclude a recipe from world builds (i.e. bitbake world)." + </info> <glossdef> <para> Directs BitBake to exclude a recipe from world builds (i.e. @@ -2273,7 +2662,10 @@ </glossdef> </glossentry> - <glossentry id='var-EXTENDPE'><glossterm>EXTENDPE</glossterm> + <glossentry id='var-EXTENDPE'><glossterm><imagedata fileref="figures/define-generic.png" />EXTENDPE</glossterm> + <info> + EXTENDPE[doc] = "Used with file and pathnames to create a prefix for a recipe's version based on the recipe's PE value. If PE is set and greater than zero for a recipe, EXTENDPE becomes that value." + </info> <glossdef> <para> Used with file and pathnames to create a prefix for a recipe's @@ -2291,7 +2683,10 @@ </glossdef> </glossentry> - <glossentry id='var-EXTENDPKGV'><glossterm>EXTENDPKGV</glossterm> + <glossentry id='var-EXTENDPKGV'><glossterm><imagedata fileref="figures/define-generic.png" />EXTENDPKGV</glossterm> + <info> + EXTENDPKGV[doc] = "The full package version specification as it appears on the final packages produced by a recipe." + </info> <glossdef> <para> The full package version specification as it appears on the @@ -2312,11 +2707,15 @@ </glossdef> </glossentry> - <glossentry id='var-EXTERNALSRC'><glossterm>EXTERNALSRC</glossterm> + <glossentry id='var-EXTERNALSRC'><glossterm><imagedata fileref="figures/define-generic.png" />EXTERNALSRC</glossterm> + <info> + EXTERNALSRC[doc] = "If externalsrc.bbclass is inherited, this variable points to the source tree, which is outside of the OpenEmbedded build system." + </info> <glossdef> <para> - If <filename>externalsrc.bbclass</filename> is inherited, - this variable points to the source tree, which is + When inheriting the + <link linkend='ref-classes-externalsrc'><filename>externalsrc</filename></link> + class, this variable points to the source tree, which is outside of the OpenEmbedded build system. When set, this variable sets the <link linkend='var-S'><filename>S</filename></link> @@ -2337,13 +2736,17 @@ </glossdef> </glossentry> - <glossentry id='var-EXTERNALSRC_BUILD'><glossterm>EXTERNALSRC_BUILD</glossterm> + <glossentry id='var-EXTERNALSRC_BUILD'><glossterm><imagedata fileref="figures/define-generic.png" />EXTERNALSRC_BUILD</glossterm> + <info> + EXTERNALSRC_BUILD[doc] = "If externalsrc.bbclass is inherited, this variable points to the directory in which the recipe's source code is built, which is outside of the OpenEmbedded build system." + </info> <glossdef> <para> - If <filename>externalsrc.bbclass</filename> is inherited, - this variable points to the directory in which the recipe's - source code is built, - which is outside of the OpenEmbedded build system. + When inheriting the + <link linkend='ref-classes-externalsrc'><filename>externalsrc</filename></link> + class, this variable points to the directory in which the + recipe's source code is built, which is outside of the + OpenEmbedded build system. When set, this variable sets the <link linkend='var-B'><filename>B</filename></link> variable, which is what the OpenEmbedded build system uses @@ -2363,7 +2766,10 @@ </glossdef> </glossentry> - <glossentry id='var-EXTRA_IMAGE_FEATURES'><glossterm>EXTRA_IMAGE_FEATURES</glossterm> + <glossentry id='var-EXTRA_IMAGE_FEATURES'><glossterm><imagedata fileref="figures/define-generic.png" />EXTRA_IMAGE_FEATURES</glossterm> + <info> + EXTRA_IMAGE_FEATURES[doc] = "The list of additional features to include in an image. Configure this variable in the conf/local.conf file in the Build Directory." + </info> <glossdef> <para> The list of additional features to include in an image. @@ -2435,7 +2841,10 @@ </glossdef> </glossentry> - <glossentry id='var-EXTRA_IMAGECMD'><glossterm>EXTRA_IMAGECMD</glossterm> + <glossentry id='var-EXTRA_IMAGECMD'><glossterm><imagedata fileref="figures/define-generic.png" />EXTRA_IMAGECMD</glossterm> + <info> + EXTRA_IMAGECMD[doc] = "Specifies additional options for the image creation command that has been specified in IMAGE_CMD. When setting this variable, you should use an override for the associated type." + </info> <glossdef> <para> Specifies additional options for the image @@ -2451,7 +2860,10 @@ </glossdef> </glossentry> - <glossentry id='var-EXTRA_IMAGEDEPENDS'><glossterm>EXTRA_IMAGEDEPENDS</glossterm> + <glossentry id='var-EXTRA_IMAGEDEPENDS'><glossterm><imagedata fileref="figures/define-generic.png" />EXTRA_IMAGEDEPENDS</glossterm> + <info> + EXTRA_IMAGEDEPENDS[doc] = "A list of recipes to build that do not provide packages for installing into the root filesystem. Use this variable to list recipes that are required to build the final image, but not needed in the root filesystem." + </info> <glossdef> <para>A list of recipes to build that do not provide packages for installing into the root filesystem. @@ -2471,28 +2883,40 @@ </glossdef> </glossentry> - <glossentry id='var-EXTRA_OECMAKE'><glossterm>EXTRA_OECMAKE</glossterm> + <glossentry id='var-EXTRA_OECMAKE'><glossterm><imagedata fileref="figures/define-generic.png" />EXTRA_OECMAKE</glossterm> + <info> + EXTRA_OECMAKE[doc] = "Additional cmake options." + </info> <glossdef> <para>Additional <filename>cmake</filename> options.</para> </glossdef> </glossentry> - <glossentry id='var-EXTRA_OECONF'><glossterm>EXTRA_OECONF</glossterm> + <glossentry id='var-EXTRA_OECONF'><glossterm><imagedata fileref="figures/define-generic.png" />EXTRA_OECONF</glossterm> + <info> + EXTRA_OECONF[doc] = "Additional configure script options." + </info> <glossdef> <para>Additional <filename>configure</filename> script options.</para> </glossdef> </glossentry> - <glossentry id='var-EXTRA_OEMAKE'><glossterm>EXTRA_OEMAKE</glossterm> + <glossentry id='var-EXTRA_OEMAKE'><glossterm><imagedata fileref="figures/define-generic.png" />EXTRA_OEMAKE</glossterm> + <info> + EXTRA_OEMAKE[doc] = "Additional GNU make options." + </info> <glossdef> <para>Additional GNU <filename>make</filename> options.</para> </glossdef> </glossentry> - <glossentry id='var-EXTRA_OESCONS'><glossterm>EXTRA_OESCONS</glossterm> + <glossentry id='var-EXTRA_OESCONS'><glossterm><imagedata fileref="figures/define-generic.png" />EXTRA_OESCONS</glossterm> + <info> + EXTRA_OESCONS[doc] = "When a recipe inherits the scons class, this variable specifies additional configuration options you want to pass to the scons command line." + </info> <glossdef> <para> - When a recipe inherits the + When inheriting the <link linkend='ref-classes-scons'><filename>scons</filename></link> class, this variable specifies additional configuration options you want to pass to the @@ -2501,7 +2925,10 @@ </glossdef> </glossentry> - <glossentry id='var-EXTRA_QMAKEVARS_POST'><glossterm>EXTRA_QMAKEVARS_POST</glossterm> + <glossentry id='var-EXTRA_QMAKEVARS_POST'><glossterm><imagedata fileref="figures/define-generic.png" />EXTRA_QMAKEVARS_POST</glossterm> + <info> + EXTRA_QMAKEVARS_POST[doc] = "Configuration variables or options you want to pass to qmake when the arguments need to be after the .pro file list on the command line." + </info> <glossdef> <para> Configuration variables or options you want to pass to @@ -2519,7 +2946,10 @@ </glossdef> </glossentry> - <glossentry id='var-EXTRA_QMAKEVARS_PRE'><glossterm>EXTRA_QMAKEVARS_PRE</glossterm> + <glossentry id='var-EXTRA_QMAKEVARS_PRE'><glossterm><imagedata fileref="figures/define-generic.png" />EXTRA_QMAKEVARS_PRE</glossterm> + <info> + EXTRA_QMAKEVARS_PRE[doc] = "Configuration variables or options you want to pass to qmake when the arguments need to be before the .pro file list on the command line." + </info> <glossdef> <para> Configuration variables or options you want to pass to @@ -2537,10 +2967,13 @@ </glossdef> </glossentry> - <glossentry id='var-EXTRA_USERS_PARAMS'><glossterm>EXTRA_USERS_PARAMS</glossterm> + <glossentry id='var-EXTRA_USERS_PARAMS'><glossterm><imagedata fileref="figures/define-generic.png" />EXTRA_USERS_PARAMS</glossterm> + <info> + EXTRA_USERS_PARAMS[doc] = "When a recipe inherits the extrausers class, this variable provides image level user and group operations." + </info> <glossdef> <para> - When a recipe inherits the + When inheriting the <link linkend='ref-classes-extrausers'><filename>extrausers</filename></link> class, this variable provides image level user and group operations. @@ -2575,7 +3008,10 @@ <glossdiv id='var-glossary-f'><title>F</title> - <glossentry id='var-FEATURE_PACKAGES'><glossterm>FEATURE_PACKAGES</glossterm> + <glossentry id='var-FEATURE_PACKAGES'><glossterm><imagedata fileref="figures/define-generic.png" />FEATURE_PACKAGES</glossterm> + <info> + FEATURE_PACKAGES[doc] = "Defines one or more packages to include in an image when a specific item is included in IMAGE_FEATURES. When setting the value, FEATURE_PACKAGES should have the name of the feature item as an override." + </info> <glossdef> <para> Defines one or more packages to include in an image when @@ -2585,11 +3021,11 @@ should have the name of the feature item as an override. Here is an example: <literallayout class='monospaced'> - FEATURE_PACKAGES_widget = "package1 package2" + FEATURE_PACKAGES_widget = "<replaceable>package1</replaceable> <replaceable>package2</replaceable>" </literallayout> In this example, if "widget" were added to - <filename>IMAGE_FEATURES</filename>, "package1" and - "package2" would be included in the image. + <filename>IMAGE_FEATURES</filename>, <replaceable>package1</replaceable> and + <replaceable>package2</replaceable> would be included in the image. <note> Packages installed by features defined through <filename>FEATURE_PACKAGES</filename> are often package @@ -2603,7 +3039,10 @@ </glossdef> </glossentry> - <glossentry id='var-FEED_DEPLOYDIR_BASE_URI'><glossterm>FEED_DEPLOYDIR_BASE_URI</glossterm> + <glossentry id='var-FEED_DEPLOYDIR_BASE_URI'><glossterm><imagedata fileref="figures/define-generic.png" />FEED_DEPLOYDIR_BASE_URI</glossterm> + <info> + FEED_DEPLOYDIR_BASE_URI[doc] = "Allow to serve ipk deploy directory as an ad hoc feed (bogofeed). Set to base URL of the directory as exported by HTTP. Set of ad hoc feed configs will be generated in the image." + </info> <glossdef> <para> Points to the base URL of the server and location within @@ -2630,17 +3069,21 @@ </glossdef> </glossentry> - <glossentry id='var-FILES'><glossterm>FILES</glossterm> + <glossentry id='var-FILES'><glossterm><imagedata fileref="figures/define-generic.png" />FILES</glossterm> + <info> + FILES[doc] = "The list of directories or files that are placed in packages." + </info> <glossdef> <para> The list of directories or files that are placed in packages. </para> <para> - To use the <filename>FILES</filename> variable, provide a package name - override that identifies the resulting package. - Then, provide a space-separated list of files or paths that identifies the - files you want included as part of the resulting package. + To use the <filename>FILES</filename> variable, provide a + package name override that identifies the resulting package. + Then, provide a space-separated list of files or paths + that identify the files you want included as part of the + resulting package. Here is an example: <literallayout class='monospaced'> FILES_${PN} += "${bindir}/mydir1/ ${bindir}/mydir2/myfile" @@ -2648,30 +3091,38 @@ </para> <note> - When specifying paths as part of the <filename>FILES</filename> variable, - it is good practice to use appropriate path variables. - For example, use <filename>${sysconfdir}</filename> rather than - <filename>/etc</filename>, or <filename>${bindir}</filename> rather - than <filename>/usr/bin</filename>. + When specifying paths as part of the + <filename>FILES</filename> variable, it is good practice + to use appropriate path variables. + For example, use <filename>${sysconfdir}</filename> rather + than <filename>/etc</filename>, or + <filename>${bindir}</filename> rather than + <filename>/usr/bin</filename>. 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>. </note> <para> - If some of the files you provide with the <filename>FILES</filename> variable - are editable and you know they should not be - overwritten during the package update process by the Package Management - System (PMS), you can identify these files so that the PMS will not + If some of the files you provide with the + <filename>FILES</filename> variable are editable and you + know they should not be overwritten during the package + update process by the Package Management System (PMS), you + can identify these files so that the PMS will not overwrite them. - See the <filename><link linkend='var-CONFFILES'>CONFFILES</link></filename> - variable for information on how to identify these files to the PMS. + See the + <link linkend='var-CONFFILES'><filename>CONFFILES</filename></link> + variable for information on how to identify these files to + the PMS. </para> </glossdef> </glossentry> - <glossentry id='var-FILESEXTRAPATHS'><glossterm>FILESEXTRAPATHS</glossterm> + <glossentry id='var-FILESEXTRAPATHS'><glossterm><imagedata fileref="figures/define-generic.png" />FILESEXTRAPATHS</glossterm> + <info> + FILESEXTRAPATHS[doc] = "Extends the search path the OpenEmbedded build system uses when looking for files and patches as it processes recipes and append files." + </info> <glossdef> <para> Extends the search path the OpenEmbedded build system uses @@ -2738,16 +3189,18 @@ </glossdef> </glossentry> - <glossentry id='var-FILESOVERRIDES'><glossterm>FILESOVERRIDES</glossterm> + <glossentry id='var-FILESOVERRIDES'><glossterm><imagedata fileref="figures/define-generic.png" />FILESOVERRIDES</glossterm> + <info> + FILESOVERRIDES[doc] = "A subset of OVERRIDES used by the OpenEmbedded build system for creating FILESPATH." + </info> <glossdef> <para> A subset of <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link> used by the OpenEmbedded build system for creating <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>. You can find more information on how overrides are handled - in the BitBake Manual that is located at - <filename>bitbake/doc/manual</filename> in the - <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. + in the + <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake Manual</ulink>. </para> <para> @@ -2767,7 +3220,10 @@ </glossdef> </glossentry> - <glossentry id='var-FILESPATH'><glossterm>FILESPATH</glossterm> + <glossentry id='var-FILESPATH'><glossterm><imagedata fileref="figures/define-generic.png" />FILESPATH</glossterm> + <info> + FILESPATH[doc] = "The default set of directories the OpenEmbedded build system uses when searching for patches and files. It is defined in the base.bbclass class found in meta/classes in the Source Directory. Do not hand-edit the FILESPATH variable." + </info> <glossdef> <para> The default set of directories the OpenEmbedded build system @@ -2810,7 +3266,10 @@ </glossdef> </glossentry> - <glossentry id='var-FILESYSTEM_PERMS_TABLES'><glossterm>FILESYSTEM_PERMS_TABLES</glossterm> + <glossentry id='var-FILESYSTEM_PERMS_TABLES'><glossterm><imagedata fileref="figures/define-generic.png" />FILESYSTEM_PERMS_TABLES</glossterm> + <info> + FILESYSTEM_PERMS_TABLES[doc] = "Allows you to define your own file permissions settings table as part of your configuration for the packaging process." + </info> <glossdef> <para>Allows you to define your own file permissions settings table as part of your configuration for the packaging process. @@ -2842,10 +3301,13 @@ </glossdef> </glossentry> - <glossentry id='var-FONT_PACKAGES'><glossterm>FONT_PACKAGES</glossterm> + <glossentry id='var-FONT_PACKAGES'><glossterm><imagedata fileref="figures/define-generic.png" />FONT_PACKAGES</glossterm> + <info> + FONT_PACKAGES[doc] = "When a recipe inherits the fontcache class, this variable identifies packages containing font files that need to be cached by Fontconfig." + </info> <glossdef> <para> - When a recipe inherits the + When inheriting the <link linkend='ref-classes-fontcache'><filename>fontcache</filename></link> class, this variable identifies packages containing font files that need to be cached by Fontconfig. @@ -2858,7 +3320,10 @@ </glossdef> </glossentry> - <glossentry id='var-FULL_OPTIMIZATION'><glossterm>FULL_OPTIMIZATION</glossterm> + <glossentry id='var-FULL_OPTIMIZATION'><glossterm><imagedata fileref="figures/define-generic.png" />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'." + </info> <glossdef> <para> The options to pass in @@ -2874,11 +3339,40 @@ <glossdiv id='var-glossary-g'><title>G</title> - <glossentry id='var-GROUPADD_PARAM'><glossterm>GROUPADD_PARAM</glossterm> + <glossentry id='var-GLIBC_GENERATE_LOCALES'><glossterm><imagedata fileref="figures/define-generic.png" />GLIBC_GENERATE_LOCALES</glossterm> + <info> + GLIBC_GENERATE_LOCALES[doc]= "Specifies the list of GLIBC locales to generate should you not wish generate all LIBC locals, which can be time consuming." + </info> + <glossdef> + <para> + Specifies the list of GLIBC locales to generate should you + not wish generate all LIBC locals, which can be time + consuming. + <note> + If you specifically remove the locale + <filename>en_US.UTF-8</filename>, you must set + <link linkend='var-IMAGE_LINGUAS'><filename>IMAGE_LINGUAS</filename></link> + appropriately. + </note> + You can set <filename>GLIBC_GENERATE_LOCALES</filename> + in your <filename>local.conf</filename> file. + By default, all locales are generated. + <literallayout class='monospaced'> + GLIBC_GENERATE_LOCALES = "en_GB.UTF-8 en_US.UTF-8" + </literallayout> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-GROUPADD_PARAM'><glossterm><imagedata fileref="figures/define-generic.png" />GROUPADD_PARAM</glossterm> + <info> + GROUPADD_PARAM[doc] = "When a recipe inherits the useradd class, this variable specifies for a package what parameters should be passed to the groupadd command if you wish to add a group to the system when the package is installed." + </info> <glossdef> <para> - When a recipe inherits the - <filename>useradd</filename> class, this variable + When inheriting the + <link linkend='ref-classes-useradd'><filename>useradd</filename></link> + class, this variable specifies for a package what parameters should be passed to the <filename>groupadd</filename> command if you wish to add a group to the system when the package @@ -2898,11 +3392,15 @@ </glossdef> </glossentry> - <glossentry id='var-GROUPMEMS_PARAM'><glossterm>GROUPMEMS_PARAM</glossterm> + <glossentry id='var-GROUPMEMS_PARAM'><glossterm><imagedata fileref="figures/define-generic.png" />GROUPMEMS_PARAM</glossterm> + <info> + GROUPMEMS_PARAM[doc] = "When a recipe inherits the useradd class, this variable specifies for a package what parameters should be passed to the groupmems command if you wish to modify the members of a group when the package is installed." + </info> <glossdef> <para> - When a recipe inherits the - <filename>useradd</filename> class, this variable + When inheriting the + <link linkend='ref-classes-useradd'><filename>useradd</filename></link> + class, this variable specifies for a package what parameters should be passed to the <filename>groupmems</filename> command if you wish to modify the members of a group when the @@ -2917,7 +3415,10 @@ </glossdef> </glossentry> - <glossentry id='var-GRUB_GFXSERIAL'><glossterm>GRUB_GFXSERIAL</glossterm> + <glossentry id='var-GRUB_GFXSERIAL'><glossterm><imagedata fileref="figures/define-generic.png" />GRUB_GFXSERIAL</glossterm> + <info> + GRUB_GFXSERIAL[doc] = "Configures the GNU GRand Unified Bootloader (GRUB) to have graphics and serial in the boot menu." + </info> <glossdef> <para> Configures the GNU GRand Unified Bootloader (GRUB) to have @@ -2936,7 +3437,10 @@ </glossdef> </glossentry> - <glossentry id='var-GRUB_OPTS'><glossterm>GRUB_OPTS</glossterm> + <glossentry id='var-GRUB_OPTS'><glossterm><imagedata fileref="figures/define-generic.png" />GRUB_OPTS</glossterm> + <info> + GRUB_OPTS[doc] = "Additional options to add to the GNU GRand Unified Bootloader (GRUB) configuration." + </info> <glossdef> <para> Additional options to add to the GNU GRand Unified @@ -2954,7 +3458,10 @@ </glossdef> </glossentry> - <glossentry id='var-GRUB_TIMEOUT'><glossterm>GRUB_TIMEOUT</glossterm> + <glossentry id='var-GRUB_TIMEOUT'><glossterm><imagedata fileref="figures/define-generic.png" />GRUB_TIMEOUT</glossterm> + <info> + GRUB_TIMEOUT[doc] = "Specifies the timeout before executing the default LABEL in the GNU GRand Unified Bootloader (GRUB)." + </info> <glossdef> <para> Specifies the timeout before executing the default @@ -2971,10 +3478,13 @@ </glossdef> </glossentry> - <glossentry id='var-GTKIMMODULES_PACKAGES'><glossterm>GTKIMMODULES_PACKAGES</glossterm> + <glossentry id='var-GTKIMMODULES_PACKAGES'><glossterm><imagedata fileref="figures/define-generic.png" />GTKIMMODULES_PACKAGES</glossterm> + <info> + GTKIMMODULES_PACKAGES[doc] = "For recipes that inherit the gtk-immodules-cache class, this variable specifies the packages that contain the GTK+ input method modules being installed when the modules are in packages other than the main package." + </info> <glossdef> <para> - For recipes that inherit the + When inheriting the <link linkend='ref-classes-gtk-immodules-cache'><filename>gtk-immodules-cache</filename></link> class, this variable specifies the packages that contain the GTK+ input method modules being installed when the modules @@ -2983,18 +3493,107 @@ </glossdef> </glossentry> + <glossentry id='var-GUMMIBOOT_CFG'><glossterm><imagedata fileref="figures/define-generic.png" />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> + 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><imagedata fileref="figures/define-generic.png" />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> + 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><imagedata fileref="figures/define-generic.png" />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> + 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> - <glossentry id='var-HOMEPAGE'><glossterm>HOMEPAGE</glossterm> + <glossentry id='var-HOMEPAGE'><glossterm><imagedata fileref="figures/define-generic.png" />HOMEPAGE</glossterm> + <info> + HOMEPAGE[doc] = "Website where more information about the software the recipe is building can be found." + </info> <glossdef> <para>Website where more information about the software the recipe is building can be found.</para> </glossdef> </glossentry> - <glossentry id='var-HOST_CC_ARCH'><glossterm>HOST_CC_ARCH</glossterm> + <glossentry id='var-HOST_CC_ARCH'><glossterm><imagedata fileref="figures/define-generic.png" />HOST_CC_ARCH</glossterm> + <info> + HOST_CC_ARCH[doc] = "The name of the host architecture. Normally same as the TARGET_CC_ARCH." + </info> <glossdef> <para> Specifies architecture-specific compiler flags that are @@ -3024,7 +3623,10 @@ </glossdef> </glossentry> - <glossentry id='var-HOST_SYS'><glossterm>HOST_SYS</glossterm> + <glossentry id='var-HOST_SYS'><glossterm><imagedata fileref="figures/define-generic.png" />HOST_SYS</glossterm> + <info> + HOST_SYS[doc] = "Specifies the system, including the architecture and the operating system, for with the build is occurring in the context of the current recipe." + </info> <glossdef> <para> Specifies the system, including the architecture and the @@ -3056,7 +3658,10 @@ <glossdiv id='var-glossary-i'><title>I</title> - <glossentry id='var-ICECC_DISABLED'><glossterm>ICECC_DISABLED</glossterm> + <glossentry id='var-ICECC_DISABLED'><glossterm><imagedata fileref="figures/define-generic.png" />ICECC_DISABLED</glossterm> + <info> + ICECC_DISABLED[doc] = "Disables or enables the icecc (Icecream) function." + </info> <glossdef> <para> Disables or enables the <filename>icecc</filename> @@ -3081,7 +3686,10 @@ </glossdef> </glossentry> - <glossentry id='var-ICECC_ENV_EXEC'><glossterm>ICECC_ENV_EXEC</glossterm> + <glossentry id='var-ICECC_ENV_EXEC'><glossterm><imagedata fileref="figures/define-generic.png" />ICECC_ENV_EXEC</glossterm> + <info> + ICECC_ENV_EXEC[doc] = "Points to the icecc-create-env script that you provide." + </info> <glossdef> <para> Points to the <filename>icecc-create-env</filename> script @@ -3103,7 +3711,10 @@ </glossdef> </glossentry> - <glossentry id='var-ICECC_PARALLEL_MAKE'><glossterm>ICECC_PARALLEL_MAKE</glossterm> + <glossentry id='var-ICECC_PARALLEL_MAKE'><glossterm><imagedata fileref="figures/define-generic.png" />ICECC_PARALLEL_MAKE</glossterm> + <info> + ICECC_PARALLEL_MAKE[doc] = "Extra options passed to the make command during the do_compile task that specify parallel compilation." + </info> <glossdef> <para> Extra options passed to the <filename>make</filename> @@ -3144,7 +3755,10 @@ </glossdef> </glossentry> - <glossentry id='var-ICECC_PATH'><glossterm>ICECC_PATH</glossterm> + <glossentry id='var-ICECC_PATH'><glossterm><imagedata fileref="figures/define-generic.png" />ICECC_PATH</glossterm> + <info> + ICECC_PATH[doc] = "The location of the icecc binary." + </info> <glossdef> <para> The location of the <filename>icecc</filename> binary. @@ -3159,7 +3773,10 @@ </glossdef> </glossentry> - <glossentry id='var-ICECC_USER_CLASS_BL'><glossterm>ICECC_USER_CLASS_BL</glossterm> + <glossentry id='var-ICECC_USER_CLASS_BL'><glossterm><imagedata fileref="figures/define-generic.png" />ICECC_USER_CLASS_BL</glossterm> + <info> + ICECC_USER_CLASS_BL[doc] = "Identifies user classes that you do not want the Icecream distributed compile support to consider." + </info> <glossdef> <para> Identifies user classes that you do not want the @@ -3181,7 +3798,10 @@ </glossdef> </glossentry> - <glossentry id='var-ICECC_USER_PACKAGE_BL'><glossterm>ICECC_USER_PACKAGE_BL</glossterm> + <glossentry id='var-ICECC_USER_PACKAGE_BL'><glossterm><imagedata fileref="figures/define-generic.png" />ICECC_USER_PACKAGE_BL</glossterm> + <info> + ICECC_USER_PACKAGE_BL[doc] = "Identifies user recipes that you do not want the Icecream distributed compile support to consider." + </info> <glossdef> <para> Identifies user recipes that you do not want the @@ -3203,7 +3823,10 @@ </glossdef> </glossentry> - <glossentry id='var-ICECC_USER_PACKAGE_WL'><glossterm>ICECC_USER_PACKAGE_WL</glossterm> + <glossentry id='var-ICECC_USER_PACKAGE_WL'><glossterm><imagedata fileref="figures/define-generic.png" />ICECC_USER_PACKAGE_WL</glossterm> + <info> + ICECC_USER_PACKAGE_WL[doc] = "Identifies user recipes that use an empty PARALLEL_MAKE variable that you want to force remote distributed compilation on using the Icecream distributed compile support." + </info> <glossdef> <para> Identifies user recipes that use an empty @@ -3220,7 +3843,10 @@ </glossdef> </glossentry> - <glossentry id='var-IMAGE_BASENAME'><glossterm>IMAGE_BASENAME</glossterm> + <glossentry id='var-IMAGE_BASENAME'><glossterm><imagedata fileref="figures/define-generic.png" />IMAGE_BASENAME</glossterm> + <info> + IMAGE_BASENAME[doc] = "The base name of image output files." + </info> <glossdef> <para> The base name of image output files. @@ -3230,7 +3856,56 @@ </glossdef> </glossentry> - <glossentry id='var-IMAGE_CLASSES'><glossterm>IMAGE_CLASSES</glossterm> + <glossentry id='var-IMAGE_BOOT_FILES'><glossterm><imagedata fileref="figures/define-generic.png" />IMAGE_BOOT_FILES</glossterm> + <info> + IMAGE_BOOT_FILES[doc] = "Whitespace separated list of files from ${DEPLOY_DIR_IMAGE} to place in boot partition. Entries will be installed under a same name as the source file. To change the destination file name, pass a desired name after a semicolon (eg. u-boot.img;uboot)." + </info> + <glossdef> + <para> + A space-separated list of files installed into the + boot partition when preparing an image using the + <filename>wic</filename> tool with the + <filename>bootimg-partition</filename> source + plugin. + By default, the files are installed under + the same name as the source files. + To change the installed name, separate it from the + original name with a semi-colon (;). + Source files need to be located in + <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>. + Here are two examples: + + <literallayout class="monospaced"> + IMAGE_BOOT_FILES = "u-boot.img uImage;kernel" + IMAGE_BOOT_FILES = "u-boot.${UBOOT_SUFFIX} ${KERNEL_IMAGETYPE}" + </literallayout> + Alternatively, source files can be picked up using + a glob pattern. + In this case, the destination file + will have the same name as the base name of the source file + path. + To install files into a directory within the + target location, pass its name after a semi-colon + (;). + Here are two examples: + <literallayout class="monospaced"> + IMAGE_BOOT_FILES = "bcm2835-bootfiles/*" + IMAGE_BOOT_FILES = "bcm2835-bootfiles/*;boot/" + </literallayout> + The first example installs all files from + <filename>${DEPLOY_DIR_IMAGE}/bcm2835-bootfiles</filename> + into the root of the target partition. + The second example installs the same files into a + <filename>boot</filename> directory within the + target partition. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-IMAGE_CLASSES'><glossterm><imagedata fileref="figures/define-generic.png" />IMAGE_CLASSES</glossterm> + <info> + IMAGE_CLASSES[doc] = "A list of classes that all images should inherit." + </info> <glossdef> <para> A list of classes that all images should inherit. @@ -3255,7 +3930,10 @@ </glossdef> </glossentry> - <glossentry id='var-IMAGE_CMD'><glossterm>IMAGE_CMD</glossterm> + <glossentry id='var-IMAGE_CMD'><glossterm><imagedata fileref="figures/define-generic.png" />IMAGE_CMD</glossterm> + <info> + IMAGE_CMD[doc] = "Specifies the command to create the image file for a specific image type, which corresponds to the value set set in IMAGE_FSTYPES, (e.g. ext3, btrfs, and so forth)." + </info> <glossdef> <para> Specifies the command to create the image file for a @@ -3282,7 +3960,10 @@ </glossdef> </glossentry> - <glossentry id='var-IMAGE_DEVICE_TABLES'><glossterm>IMAGE_DEVICE_TABLES</glossterm> + <glossentry id='var-IMAGE_DEVICE_TABLES'><glossterm><imagedata fileref="figures/define-generic.png" />IMAGE_DEVICE_TABLES</glossterm> + <info> + IMAGE_DEVICE_TABLES[doc] = "Specifies one or more files that contain custom device tables that are passed to the makedevs command as part of creating an image." + </info> <glossdef> <para> Specifies one or more files that contain custom device @@ -3302,7 +3983,10 @@ </glossdef> </glossentry> - <glossentry id='var-IMAGE_FEATURES'><glossterm>IMAGE_FEATURES</glossterm> + <glossentry id='var-IMAGE_FEATURES'><glossterm><imagedata fileref="figures/define-generic.png" />IMAGE_FEATURES</glossterm> + <info> + IMAGE_FEATURES[doc] = "The primary list of features to include in an image. Configure this variable in an image recipe." + </info> <glossdef> <para> The primary list of features to include in an image. @@ -3331,7 +4015,10 @@ </glossdef> </glossentry> - <glossentry id='var-IMAGE_FSTYPES'><glossterm>IMAGE_FSTYPES</glossterm> + <glossentry id='var-IMAGE_FSTYPES'><glossterm><imagedata fileref="figures/define-generic.png" />IMAGE_FSTYPES</glossterm> + <info> + IMAGE_FSTYPES[doc] = "Formats of root filesystem images that you want to have created." + </info> <glossdef> <para> Specifies the formats the OpenEmbedded build system uses @@ -3366,7 +4053,10 @@ </glossdef> </glossentry> - <glossentry id='var-IMAGE_INSTALL'><glossterm>IMAGE_INSTALL</glossterm> + <glossentry id='var-IMAGE_INSTALL'><glossterm><imagedata fileref="figures/define-generic.png" />IMAGE_INSTALL</glossterm> + <info> + IMAGE_INSTALL[doc] = "Specifies the packages to install into an image. Image recipes set IMAGE_INSTALL to specify the packages to install into an image through image.bbclass." + </info> <glossdef> <para> Specifies the packages to install into an image. @@ -3421,7 +4111,7 @@ <para> When you use this variable, it is best to use it as follows: <literallayout class='monospaced'> - IMAGE_INSTALL_append = " package-name" + IMAGE_INSTALL_append = " <replaceable>package-name</replaceable>" </literallayout> Be sure to include the space between the quotation character and the start of the package name or names. @@ -3429,7 +4119,10 @@ </glossdef> </glossentry> - <glossentry id='var-IMAGE_LINGUAS'><glossterm>IMAGE_LINGUAS</glossterm> + <glossentry id='var-IMAGE_LINGUAS'><glossterm><imagedata fileref="figures/define-generic.png" />IMAGE_LINGUAS</glossterm> + <info> + IMAGE_LINGUAS[doc] = "Specifies the list of locales to install into the image during the root filesystem construction process." + </info> <glossdef> <para> Specifies the list of locales to install into the image @@ -3455,10 +4148,19 @@ packages only provide locale files by language and not by country-specific language). </para> + + <para> + See the + <link linkend='var-GLIBC_GENERATE_LOCALES'><filename>GLIBC_GENERATE_LOCALES</filename></link> + variable for information on generating GLIBC locales. + </para> </glossdef> </glossentry> - <glossentry id='var-IMAGE_MANIFEST'><glossterm>IMAGE_MANIFEST</glossterm> + <glossentry id='var-IMAGE_MANIFEST'><glossterm><imagedata fileref="figures/define-generic.png" />IMAGE_MANIFEST</glossterm> + <info> + IMAGE_MANIFEST[doc] = "The manifest file for the image. This file lists all the installed packages that make up the image." + </info> <glossdef> <para> The manifest file for the image. @@ -3467,7 +4169,7 @@ The file contains package information on a line-per-package basis as follows: <literallayout class='monospaced'> - <packagename> <packagearch> <version> + <replaceable>packagename</replaceable> <replaceable>packagearch</replaceable> <replaceable>version</replaceable> </literallayout> </para> @@ -3491,7 +4193,10 @@ </glossdef> </glossentry> - <glossentry id='var-IMAGE_NAME'><glossterm>IMAGE_NAME</glossterm> + <glossentry id='var-IMAGE_NAME'><glossterm><imagedata fileref="figures/define-generic.png" />IMAGE_NAME</glossterm> + <info> + IMAGE_NAME[doc] = "The name of the output image files minus the extension." + </info> <glossdef> <para> The name of the output image files minus the extension. @@ -3508,7 +4213,10 @@ </glossdef> </glossentry> - <glossentry id='var-IMAGE_OVERHEAD_FACTOR'><glossterm>IMAGE_OVERHEAD_FACTOR</glossterm> + <glossentry id='var-IMAGE_OVERHEAD_FACTOR'><glossterm><imagedata fileref="figures/define-generic.png" />IMAGE_OVERHEAD_FACTOR</glossterm> + <info> + IMAGE_OVERHEAD_FACTOR[doc] = "Defines a multiplier that the build system applies to the initial image size for cases when the multiplier times the returned disk usage value for the image is greater than the sum of IMAGE_ROOTFS_SIZE and IMAGE_ROOTFS_EXTRA_SPACE." + </info> <glossdef> <para> Defines a multiplier that the build system applies to the initial image @@ -3550,7 +4258,10 @@ </glossdef> </glossentry> - <glossentry id='var-IMAGE_PKGTYPE'><glossterm>IMAGE_PKGTYPE</glossterm> + <glossentry id='var-IMAGE_PKGTYPE'><glossterm><imagedata fileref="figures/define-generic.png" />IMAGE_PKGTYPE</glossterm> + <info> + IMAGE_PKGTYPE[doc] = "Defines the package type (DEB, RPM, IPK, or TAR) used by the OpenEmbedded build system." + </info> <glossdef> <para> Defines the package type (DEB, RPM, IPK, or TAR) used @@ -3593,14 +4304,17 @@ </glossdef> </glossentry> - <glossentry id='var-IMAGE_POSTPROCESS_COMMAND'><glossterm>IMAGE_POSTPROCESS_COMMAND</glossterm> + <glossentry id='var-IMAGE_POSTPROCESS_COMMAND'><glossterm><imagedata fileref="figures/define-generic.png" />IMAGE_POSTPROCESS_COMMAND</glossterm> + <info> + IMAGE_POSTPROCESS_COMMAND[doc] = "Added by classes to run post processing commands once the OpenEmbedded build system has created the image." + </info> <glossdef> <para> Added by classes to run post processing commands once the OpenEmbedded build system has created the image. You can specify shell commands separated by semicolons: <literallayout class='monospaced'> - IMAGE_POSTPROCESS_COMMAND += "<shell_command>; ... " + IMAGE_POSTPROCESS_COMMAND += "<replaceable>shell_command</replaceable>; ... " </literallayout> If you need to pass the path to the root filesystem within the command, you can use @@ -3610,7 +4324,10 @@ </glossdef> </glossentry> - <glossentry id='var-IMAGE_ROOTFS'><glossterm>IMAGE_ROOTFS</glossterm> + <glossentry id='var-IMAGE_ROOTFS'><glossterm><imagedata fileref="figures/define-generic.png" />IMAGE_ROOTFS</glossterm> + <info> + IMAGE_ROOTFS[doc] = "The location of the root filesystem while it is under construction (i.e. during do_rootfs)." + </info> <glossdef> <para> The location of the root filesystem while it is under @@ -3623,7 +4340,10 @@ </glossdef> </glossentry> - <glossentry id='var-IMAGE_ROOTFS_ALIGNMENT'><glossterm>IMAGE_ROOTFS_ALIGNMENT</glossterm> + <glossentry id='var-IMAGE_ROOTFS_ALIGNMENT'><glossterm><imagedata fileref="figures/define-generic.png" />IMAGE_ROOTFS_ALIGNMENT</glossterm> + <info> + IMAGE_ROOTFS_ALIGNMENT[doc] = "Specifies the alignment for the output image file in Kbytes." + </info> <glossdef> <para> Specifies the alignment for the output image file in @@ -3639,7 +4359,10 @@ </glossdef> </glossentry> - <glossentry id='var-IMAGE_ROOTFS_EXTRA_SPACE'><glossterm>IMAGE_ROOTFS_EXTRA_SPACE</glossterm> + <glossentry id='var-IMAGE_ROOTFS_EXTRA_SPACE'><glossterm><imagedata fileref="figures/define-generic.png" />IMAGE_ROOTFS_EXTRA_SPACE</glossterm> + <info> + IMAGE_ROOTFS_EXTRA_SPACE[doc] = "Defines additional free disk space created in the image in Kbytes. By default, this variable is set to '0'." + </info> <glossdef> <para> Defines additional free disk space created in the image in Kbytes. @@ -3670,7 +4393,10 @@ </glossdef> </glossentry> - <glossentry id='var-IMAGE_ROOTFS_SIZE'><glossterm>IMAGE_ROOTFS_SIZE</glossterm> + <glossentry id='var-IMAGE_ROOTFS_SIZE'><glossterm><imagedata fileref="figures/define-generic.png" />IMAGE_ROOTFS_SIZE</glossterm> + <info> + IMAGE_ROOTFS_SIZE[doc] = "Defines the size in Kbytes for the generated image." + </info> <glossdef> <para> Defines the size in Kbytes for the generated image. @@ -3713,7 +4439,10 @@ </glossdef> </glossentry> - <glossentry id='var-IMAGE_TYPEDEP'><glossterm>IMAGE_TYPEDEP</glossterm> + <glossentry id='var-IMAGE_TYPEDEP'><glossterm><imagedata fileref="figures/define-generic.png" />IMAGE_TYPEDEP</glossterm> + <info> + IMAGE_TYPEDEP[doc] = "Specifies a dependency from one image type on another." + </info> <glossdef> <para> Specifies a dependency from one image type on another. @@ -3736,7 +4465,10 @@ </glossdef> </glossentry> - <glossentry id='var-IMAGE_TYPES'><glossterm>IMAGE_TYPES</glossterm> + <glossentry id='var-IMAGE_TYPES'><glossterm><imagedata fileref="figures/define-generic.png" />IMAGE_TYPES</glossterm> + <info> + IMAGE_TYPES[doc] = "Specifies the complete list of supported image types by default." + </info> <glossdef> <para> Specifies the complete list of supported image types @@ -3776,7 +4508,10 @@ </glossdef> </glossentry> - <glossentry id='var-INC_PR'><glossterm>INC_PR</glossterm> + <glossentry id='var-INC_PR'><glossterm><imagedata fileref="figures/define-generic.png" />INC_PR</glossterm> + <info> + INC_PR[doc] = "Helps define the recipe revision for recipes that share a common include file." + </info> <glossdef> <para>Helps define the recipe revision for recipes that share a common <filename>include</filename> file. @@ -3829,7 +4564,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-INCOMPATIBLE_LICENSE'><glossterm>INCOMPATIBLE_LICENSE</glossterm> + <glossentry id='var-INCOMPATIBLE_LICENSE'><glossterm><imagedata fileref="figures/define-generic.png" />INCOMPATIBLE_LICENSE</glossterm> + <info> + INCOMPATIBLE_LICENSE[doc] = "Specifies a space-separated list of license names (as they would appear in LICENSE) that should be excluded from the build." + </info> <glossdef> <para> Specifies a space-separated list of license names @@ -3846,7 +4584,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" This functionality is only regularly tested using the following setting: <literallayout class='monospaced'> - INCOMPATIBLE_LICENSE = "GPLv3" + INCOMPATIBLE_LICENSE = "GPL-3.0 LGPL-3.0 AGPL-3.0" </literallayout> Although you can use other settings, you might be required to remove dependencies on or provide alternatives to @@ -3856,7 +4594,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-INHIBIT_DEFAULT_DEPS'><glossterm>INHIBIT_DEFAULT_DEPS</glossterm> + <glossentry id='var-INHIBIT_DEFAULT_DEPS'><glossterm><imagedata fileref="figures/define-generic.png" />INHIBIT_DEFAULT_DEPS</glossterm> + <info> + INHIBIT_DEFAULT_DEPS[doc] = "Prevents the default dependencies, namely the C compiler and standard C library (libc), from being added to DEPENDS." + </info> <glossdef> <para> Prevents the default dependencies, namely the C compiler @@ -3873,7 +4614,41 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-INHIBIT_PACKAGE_STRIP'><glossterm>INHIBIT_PACKAGE_STRIP</glossterm> + <glossentry id='var-INHIBIT_PACKAGE_DEBUG_SPLIT'><glossterm><imagedata fileref="figures/define-generic.png" />INHIBIT_PACKAGE_DEBUG_SPLIT</glossterm> + <info> + INHIBIT_PACKAGE_STRIP[doc] = "If set to "1", causes the build to not strip binaries in resulting packages." + </info> + <glossdef> + + <para> + Prevents the OpenEmbedded build system from splitting + out debug information during packaging. + By default, the build system splits out debugging + information during the + <link linkend='ref-tasks-package'><filename>do_package</filename></link> + task. + For more information on how debug information is split out, + see the + <link linkend='var-PACKAGE_DEBUG_SPLIT_STYLE'><filename>PACKAGE_DEBUG_SPLIT_STYLE</filename></link> + variable. + </para> + + <para> + To prevent the build system from splitting out + debug information during packaging, set the + <filename>INHIBIT_PACKAGE_DEBUG_SPLIT</filename> variable + as follows: + <literallayout class='monospaced'> + INHIBIT_PACKAGE_DEBUG_SPLIT = "1" + </literallayout> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-INHIBIT_PACKAGE_STRIP'><glossterm><imagedata fileref="figures/define-generic.png" />INHIBIT_PACKAGE_STRIP</glossterm> + <info> + INHIBIT_PACKAGE_STRIP[doc] = "If set to "1", causes the build to not strip binaries in resulting packages." + </info> <glossdef> <para> If set to "1", causes the build to not strip binaries in resulting packages. @@ -3881,7 +4656,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-INHERIT'><glossterm>INHERIT</glossterm> + <glossentry id='var-INHERIT'><glossterm><imagedata fileref="figures/define-generic.png" />INHERIT</glossterm> + <info> + INHERIT[doc] = "Causes the named class to be inherited at this point during parsing. The variable is only valid in configuration files." + </info> <glossdef> <para> Causes the named class to be inherited at @@ -3891,7 +4669,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-INHERIT_DISTRO'><glossterm>INHERIT_DISTRO</glossterm> + <glossentry id='var-INHERIT_DISTRO'><glossterm><imagedata fileref="figures/define-generic.png" />INHERIT_DISTRO</glossterm> + <info> + INHERIT_DISTRO[doc] = "Lists classes that will be inherited at the distribution level. It is unlikely that you want to edit this variable." + </info> <glossdef> <para> Lists classes that will be inherited at the @@ -3910,7 +4691,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-INITRAMFS_FSTYPES'><glossterm>INITRAMFS_FSTYPES</glossterm> + <glossentry id='var-INITRAMFS_FSTYPES'><glossterm><imagedata fileref="figures/define-generic.png" />INITRAMFS_FSTYPES</glossterm> + <info> + INITRAMFS_FSTYPES[doc] = "Defines the format for the output image of an initial RAM disk (initramfs), which is used during boot." + </info> <glossdef> <para> Defines the format for the output image of an initial @@ -3922,7 +4706,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-INITRAMFS_IMAGE'><glossterm>INITRAMFS_IMAGE</glossterm> + <glossentry id='var-INITRAMFS_IMAGE'><glossterm><imagedata fileref="figures/define-generic.png" />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)." + </info> <glossdef> <para> Causes the OpenEmbedded build system to build an additional @@ -3965,7 +4752,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-INITRAMFS_IMAGE_BUNDLE'><glossterm>INITRAMFS_IMAGE_BUNDLE</glossterm> + <glossentry id='var-INITRAMFS_IMAGE_BUNDLE'><glossterm><imagedata fileref="figures/define-generic.png" />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)." + </info> <glossdef> <para> Controls whether or not the image recipe specified by @@ -4012,11 +4802,14 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-INITRD'><glossterm>INITRD</glossterm> + <glossentry id='var-INITRD'><glossterm><imagedata fileref="figures/define-generic.png" />INITRD</glossterm> + <info> + INITRD[doc] = "Indicates a list of filesystem images to concatenate and use as an initial RAM disk (initrd)." + </info> <glossdef> <para> - Indicates a filesystem image to use as an initial RAM - disk (<filename>initrd</filename>). + Indicates list of filesystem images to concatenate and use + as an initial RAM disk (<filename>initrd</filename>). </para> <para> @@ -4028,7 +4821,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-INITRD_IMAGE'><glossterm>INITRD_IMAGE</glossterm> + <glossentry id='var-INITRD_IMAGE'><glossterm><imagedata fileref="figures/define-generic.png" />INITRD_IMAGE</glossterm> + <info> + INITRD_IMAGE[doc] = "When building a "live" bootable image (i.e. when IMAGE_FSTYPES contains "live"), INITRD_IMAGE specifies the image recipe that should be built to provide the initial RAM disk image." + </info> <glossdef> <para> When building a "live" bootable image (i.e. when @@ -4038,10 +4834,19 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" to provide the initial RAM disk image. The default value is "core-image-minimal-initramfs". </para> + + <para> + See the + <link linkend='ref-classes-image-live'><filename>image-live</filename></link> + class for more information. + </para> </glossdef> </glossentry> - <glossentry id='var-INITSCRIPT_NAME'><glossterm>INITSCRIPT_NAME</glossterm> + <glossentry id='var-INITSCRIPT_NAME'><glossterm><imagedata fileref="figures/define-generic.png" />INITSCRIPT_NAME</glossterm> + <info> + INITSCRIPT_NAME[doc] = "The filename of the initialization script as installed to ${sysconfdir}/init.d." + </info> <glossdef> <para> The filename of the initialization script as installed to @@ -4054,7 +4859,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-INITSCRIPT_PACKAGES'><glossterm>INITSCRIPT_PACKAGES</glossterm> + <glossentry id='var-INITSCRIPT_PACKAGES'><glossterm><imagedata fileref="figures/define-generic.png" />INITSCRIPT_PACKAGES</glossterm> + <info> + INITSCRIPT_PACKAGES[doc] = "A list of the packages that contain initscripts. This variable is used in recipes when using update-rc.d.bbclass. The variable is optional and defaults to the PN variable." + </info> <glossdef> <para> A list of the packages that contain initscripts. @@ -4068,7 +4876,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-INITSCRIPT_PARAMS'><glossterm>INITSCRIPT_PARAMS</glossterm> + <glossentry id='var-INITSCRIPT_PARAMS'><glossterm><imagedata fileref="figures/define-generic.png" />INITSCRIPT_PARAMS</glossterm> + <info> + INITSCRIPT_PARAMS[doc] = "Specifies the options to pass to update-rc.d. The variable is mandatory and is used in recipes when using update-rc.d.bbclass." + </info> <glossdef> <para> Specifies the options to pass to <filename>update-rc.d</filename>. @@ -4081,8 +4892,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" stops the script in levels 0, 1 and 6. </para> <para> - The variable is mandatory and is used in recipes when using - <filename>update-rc.d.bbclass</filename>. + The variable's default value is "defaults", which is + set in the + <link linkend='ref-classes-update-rc.d'><filename>update-rc.d</filename></link> + class. + </para> + <para> The value in <filename>INITSCRIPT_PARAMS</filename> is passed through to the <filename>update-rc.d</filename> command. @@ -4093,7 +4908,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-INSANE_SKIP'><glossterm>INSANE_SKIP</glossterm> + <glossentry id='var-INSANE_SKIP'><glossterm><imagedata fileref="figures/define-generic.png" />INSANE_SKIP</glossterm> + <info> + INSANE_SKIP[doc] = "Specifies the QA checks to skip for a specific package within a recipe." + </info> <glossdef> <para> Specifies the QA checks to skip for a specific package @@ -4115,7 +4933,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-IPK_FEED_URIS'><glossterm>IPK_FEED_URIS</glossterm> + <glossentry id='var-IPK_FEED_URIS'><glossterm><imagedata fileref="figures/define-generic.png" />IPK_FEED_URIS</glossterm> + <info> + IPK_FEED_URIS[doc] = "List of ipkg feed records to put into generated image." + </info> <glossdef> <para> When the IPK backend is in use and package management @@ -4171,7 +4992,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossdiv id='var-glossary-k'><title>K</title> - <glossentry id='var-KARCH'><glossterm>KARCH</glossterm> + <glossentry id='var-KARCH'><glossterm><imagedata fileref="figures/define-generic.png" />KARCH</glossterm> + <info> + KARCH[doc] = "Defines the kernel architecture used when assembling the configuration. You define the KARCH variable in the BSP Descriptions." + </info> <glossdef> <para> Defines the kernel architecture used when assembling @@ -4194,7 +5018,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-KBRANCH'><glossterm>KBRANCH</glossterm> + <glossentry id='var-KBRANCH'><glossterm><imagedata fileref="figures/define-generic.png" />KBRANCH</glossterm> + <info> + KBRANCH[doc] = "A regular expression used by the build process to explicitly identify the kernel branch that is validated, patched and configured during a build." + </info> <glossdef> <para> A regular expression used by the build process to explicitly @@ -4255,7 +5082,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-KBRANCH_DEFAULT'><glossterm>KBRANCH_DEFAULT</glossterm> + <glossentry id='var-KBRANCH_DEFAULT'><glossterm><imagedata fileref="figures/define-generic.png" />KBRANCH_DEFAULT</glossterm> + <info> + KBRANCH_DEFAULT[doc] = "Defines the Linux kernel source repository's default branch used to build the Linux kernel. Unless you specify otherwise, the variable initializes to 'master'." + </info> <glossdef> <para> Defines the Linux kernel source repository's default @@ -4270,7 +5100,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-KERNEL_EXTRA_ARGS'><glossterm>KERNEL_EXTRA_ARGS</glossterm> + <glossentry id='var-KERNEL_EXTRA_ARGS'><glossterm><imagedata fileref="figures/define-generic.png" />KERNEL_EXTRA_ARGS</glossterm> + <info> + KERNEL_EXTRA_ARGS[doc] = "Specifies additional make command-line arguments the OpenEmbedded build system passes on when compiling the kernel." + </info> <glossdef> <para> Specifies additional <filename>make</filename> @@ -4280,7 +5113,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-KERNEL_FEATURES'><glossterm>KERNEL_FEATURES</glossterm> + <glossentry id='var-KERNEL_FEATURES'><glossterm><imagedata fileref="figures/define-generic.png" />KERNEL_FEATURES</glossterm> + <info> + KERNEL_FEATURES[doc] = "Includes additional metadata from the Yocto Project kernel Git repository. The metadata you add through this variable includes config fragments and features descriptions." + </info> <glossdef> <para>Includes additional metadata from the Yocto Project kernel Git repository. In the OpenEmbedded build system, the default Board Support Packages (BSPs) @@ -4310,7 +5146,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-KERNEL_IMAGE_BASE_NAME'><glossterm>KERNEL_IMAGE_BASE_NAME</glossterm> + <glossentry id='var-KERNEL_IMAGE_BASE_NAME'><glossterm><imagedata fileref="figures/define-generic.png" />KERNEL_IMAGE_BASE_NAME</glossterm> + <info> + KERNEL_IMAGE_BASE_NAME[doc] = "The base name of the kernel image." + </info> <glossdef> <para> The base name of the kernel image. @@ -4333,7 +5172,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-KERNEL_IMAGETYPE'><glossterm>KERNEL_IMAGETYPE</glossterm> + <glossentry id='var-KERNEL_IMAGETYPE'><glossterm><imagedata fileref="figures/define-generic.png" />KERNEL_IMAGETYPE</glossterm> + <info> + KERNEL_IMAGETYPE[doc] = "The type of kernel to build for a device, usually set by the machine configuration files and defaults to 'zImage'." + </info> <glossdef> <para>The type of kernel to build for a device, usually set by the machine configuration files and defaults to "zImage". @@ -4343,13 +5185,89 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-KERNEL_PATH'><glossterm>KERNEL_PATH</glossterm> + <glossentry id='var-KERNEL_MODULE_AUTOLOAD'><glossterm><imagedata fileref="figures/define-generic.png" />KERNEL_MODULE_AUTOLOAD</glossterm> + <info> + KERNEL_MODULE_AUTOLOAD[doc] = "Lists kernel modules that need to be auto-loaded during boot" + </info> + <glossdef> + <para> + Lists kernel modules that need to be auto-loaded during + boot. + <note> + This variable replaces the deprecated + <link linkend='var-module_autoload'><filename>module_autoload</filename></link> + variable. + </note> + </para> + + <para> + You can use the <filename>KERNEL_MODULE_AUTOLOAD</filename> + variable anywhere that it can be + recognized by the kernel recipe or by an out-of-tree kernel + module recipe (e.g. a machine configuration file, a + distribution configuration file, an append file for the + recipe, or the recipe itself). + </para> + + <para> + Specify it as follows: + <literallayout class='monospaced'> + KERNEL_MODULE_AUTOLOAD += "<replaceable>module_name1</replaceable> <replaceable>module_name2</replaceable> <replaceable>module_name3</replaceable>" + </literallayout> + </para> + + <para> + Including <filename>KERNEL_MODULE_AUTOLOAD</filename> causes + the OpenEmbedded build system to populate the + <filename>/etc/modules-load.d/modname.conf</filename> + file with the list of modules to be auto-loaded on boot. + The modules appear one-per-line in the file. + Here is an example of the most common use case: + <literallayout class='monospaced'> + KERNEL_MODULE_AUTOLOAD += "<replaceable>module_name</replaceable>" + </literallayout> + </para> + + <para> + For information on how to populate the + <filename>modname.conf</filename> file with + <filename>modprobe.d</filename> syntax lines, see the + <link linkend='var-KERNEL_MODULE_PROBECONF'><filename>KERNEL_MODULE_PROBECONF</filename></link> + variable. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-KERNEL_MODULE_PROBECONF'><glossterm><imagedata fileref="figures/define-generic.png" />KERNEL_MODULE_PROBECONF</glossterm> + <info> + KERNEL_MODULE_PROBECONF[doc] = "Lists kernel modules for which the build system expects to find module_conf_* values that specify configuration for each of the modules." + </info> + <glossdef> + <para> + Provides a list of modules for which the OpenEmbedded + build system expects to find + <filename>module_conf_</filename><replaceable>modname</replaceable> + values that specify configuration for each of the modules. + For information on how to provide those module + configurations, see the + <link linkend='var-module_conf'><filename>module_conf_*</filename></link> + variable. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-KERNEL_PATH'><glossterm><imagedata fileref="figures/define-generic.png" />KERNEL_PATH</glossterm> + <info> + KERNEL_PATH[doc] = "The location of the kernel sources. This variable is set to the value of the STAGING_KERNEL_DIR within the module class (module.bbclass)." + </info> <glossdef> <para> The location of the kernel sources. This variable is set to the value of the <link linkend='var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></link> - within the <filename>module.bbclass</filename> class. + within the + <link linkend='ref-classes-module'><filename>module</filename></link> + class. For information on how this variable is used, see the "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</ulink>" section. @@ -4368,13 +5286,18 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-KERNEL_SRC'><glossterm>KERNEL_SRC</glossterm> + <glossentry id='var-KERNEL_SRC'><glossterm><imagedata fileref="figures/define-generic.png" />KERNEL_SRC</glossterm> + <info> + KERNEL_SRC[doc] = "The location of the kernel sources. This variable is set to the value of the STAGING_KERNEL_DIR within the module class (module.bbclass)." + </info> <glossdef> <para> The location of the kernel sources. This variable is set to the value of the <link linkend='var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></link> - within the <filename>module.bbclass</filename> class. + within the + <link linkend='ref-classes-module'><filename>module</filename></link> + class. For information on how this variable is used, see the "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</ulink>" section. @@ -4393,7 +5316,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-KFEATURE_DESCRIPTION'><glossterm>KFEATURE_DESCRIPTION</glossterm> + <glossentry id='var-KFEATURE_DESCRIPTION'><glossterm><imagedata fileref="figures/define-generic.png" />KFEATURE_DESCRIPTION</glossterm> + <info> + KFEATURE_DESCRIPTION[doc] = "Provides a short description of a configuration fragment. You use this variable in the .scc file that describes a configuration fragment file." + </info> <glossdef> <para> Provides a short description of a configuration fragment. @@ -4409,7 +5335,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-KMACHINE'><glossterm>KMACHINE</glossterm> + <glossentry id='var-KMACHINE'><glossterm><imagedata fileref="figures/define-generic.png" />KMACHINE</glossterm> + <info> + KMACHINE[doc] = "The machine as known by the kernel." + </info> <glossdef> <para> The machine as known by the kernel. @@ -4502,7 +5431,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-KTYPE'><glossterm>KTYPE</glossterm> + <glossentry id='var-KTYPE'><glossterm><imagedata fileref="figures/define-generic.png" />KTYPE</glossterm> + <info> + KTYPE[doc] = "Defines the kernel type to be used in assembling the configuration." + </info> <glossdef> <para> Defines the kernel type to be used in assembling the @@ -4528,7 +5460,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossdiv id='var-glossary-l'><title>L</title> - <glossentry id='var-LABELS'><glossterm>LABELS</glossterm> + <glossentry id='var-LABELS'><glossterm><imagedata fileref="figures/define-generic.png" />LABELS</glossterm> + <info> + LABELS[doc] = "Provides a list of targets for automatic configuration." + </info> <glossdef> <para> Provides a list of targets for automatic configuration. @@ -4542,7 +5477,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-LAYERDEPENDS'><glossterm>LAYERDEPENDS</glossterm> + <glossentry id='var-LAYERDEPENDS'><glossterm><imagedata fileref="figures/define-generic.png" />LAYERDEPENDS</glossterm> + <info> + LAYERDEPENDS[doc] = "Lists the layers, separated by spaces, upon which this recipe depends. This variable is used in the conf/layer.conf file and must be suffixed with the name of the specific layer." + </info> <glossdef> <para>Lists the layers that this recipe depends upon, separated by spaces. Optionally, you can specify a specific layer version for a dependency @@ -4558,7 +5496,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-LAYERDIR'><glossterm>LAYERDIR</glossterm> + <glossentry id='var-LAYERDIR'><glossterm><imagedata fileref="figures/define-generic.png" />LAYERDIR</glossterm> + <info> + LAYERDIR[doc] = "When used inside the layer.conf configuration file, this variable provides the path of the current layer." + </info> <glossdef> <para>When used inside the <filename>layer.conf</filename> configuration file, this variable provides the path of the current layer. @@ -4567,7 +5508,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-LAYERVERSION'><glossterm>LAYERVERSION</glossterm> + <glossentry id='var-LAYERVERSION'><glossterm><imagedata fileref="figures/define-generic.png" />LAYERVERSION</glossterm> + <info> + LAYERVERSION[doc] = "Optionally specifies the version of a layer as a single number. This variable is used in the conf/layer.conf file and must be suffixed with the name of the specific layer." + </info> <glossdef> <para>Optionally specifies the version of a layer as a single number. You can use this within @@ -4580,7 +5524,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-LDFLAGS'><glossterm>LDFLAGS</glossterm> + <glossentry id='var-LDFLAGS'><glossterm><imagedata fileref="figures/define-generic.png" />LDFLAGS</glossterm> + <info> + LDFLAGS[doc] = "Specifies the flags to pass to the linker." + </info> <glossdef> <para> Specifies the flags to pass to the linker. @@ -4612,7 +5559,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-LEAD_SONAME'><glossterm>LEAD_SONAME</glossterm> + <glossentry id='var-LEAD_SONAME'><glossterm><imagedata fileref="figures/define-generic.png" />LEAD_SONAME</glossterm> + <info> + LEAD_SONAME[doc] = "Specifies the lead (or primary) compiled library file (.so) that the debian class applies its naming policy to given a recipe that packages multiple libraries." + </info> <glossdef> <para> Specifies the lead (or primary) compiled library file @@ -4629,7 +5579,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-LIC_FILES_CHKSUM'><glossterm>LIC_FILES_CHKSUM</glossterm> + <glossentry id='var-LIC_FILES_CHKSUM'><glossterm><imagedata fileref="figures/define-generic.png" />LIC_FILES_CHKSUM</glossterm> + <info> + LIC_FILES_CHKSUM[doc] = "Checksums of the license text in the recipe source code." + </info> <glossdef> <para>Checksums of the license text in the recipe source code.</para> <para>This variable tracks changes in license text of the source @@ -4640,14 +5593,17 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <para> This variable must be defined for all recipes (unless <link linkend='var-LICENSE'><filename>LICENSE</filename></link> - is set to "CLOSED")</para> + is set to "CLOSED").</para> <para>For more information, see the - <link linkend='usingpoky-configuring-LIC_FILES_CHKSUM'> - Tracking License Changes</link> section</para> + "<link linkend='usingpoky-configuring-LIC_FILES_CHKSUM'> + Tracking License Changes</link>" section.</para> </glossdef> </glossentry> - <glossentry id='var-LICENSE'><glossterm>LICENSE</glossterm> + <glossentry id='var-LICENSE'><glossterm><imagedata fileref="figures/define-generic.png" />LICENSE</glossterm> + <info> + LICENSE[doc] = "The list of source licenses for the recipe. The logical operators ampersand or '|' and parentheses can be used." + </info> <glossdef> <para> The list of source licenses for the recipe. @@ -4708,7 +5664,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-LICENSE_FLAGS'><glossterm>LICENSE_FLAGS</glossterm> + <glossentry id='var-LICENSE_FLAGS'><glossterm><imagedata fileref="figures/define-generic.png" />LICENSE_FLAGS</glossterm> + <info> + LICENSE_FLAGS[doc] = "Specifies additional flags for a recipe you must whitelist through LICENSE_FLAGS_WHITELIST in order to allow the recipe to be built." + </info> <glossdef> <para> Specifies additional flags for a recipe you must @@ -4732,7 +5691,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-LICENSE_FLAGS_WHITELIST'><glossterm>LICENSE_FLAGS_WHITELIST</glossterm> + <glossentry id='var-LICENSE_FLAGS_WHITELIST'><glossterm><imagedata fileref="figures/define-generic.png" />LICENSE_FLAGS_WHITELIST</glossterm> + <info> + LICENSE_FLAGS_WHITELIST[doc] = "Lists license flags that when specified in LICENSE_FLAGS within a recipe should not prevent that recipe from being built." + </info> <glossdef> <para> Lists license flags that when specified in @@ -4748,7 +5710,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-LICENSE_PATH'><glossterm>LICENSE_PATH</glossterm> + <glossentry id='var-LICENSE_PATH'><glossterm><imagedata fileref="figures/define-generic.png" />LICENSE_PATH</glossterm> + <info> + LICENSE_PATH[doc] = "Path to additional licenses used during the build." + </info> <glossdef> <para>Path to additional licenses used during the build. By default, the OpenEmbedded build system uses <filename>COMMON_LICENSE_DIR</filename> @@ -4756,12 +5721,15 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" The <filename>LICENSE_PATH</filename> variable allows you to extend that location to other areas that have additional licenses: <literallayout class='monospaced'> - LICENSE_PATH += "/path/to/additional/common/licenses" + LICENSE_PATH += "<replaceable>path-to-additional-common-licenses</replaceable>" </literallayout></para> </glossdef> </glossentry> - <glossentry id='var-LINUX_KERNEL_TYPE'><glossterm>LINUX_KERNEL_TYPE</glossterm> + <glossentry id='var-LINUX_KERNEL_TYPE'><glossterm><imagedata fileref="figures/define-generic.png" />LINUX_KERNEL_TYPE</glossterm> + <info> + LINUX_KERNEL_TYPE[doc] = "Defines the kernel type to be used in assembling the configuration." + </info> <glossdef> <para> Defines the kernel type to be used in assembling the @@ -4790,7 +5758,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-LINUX_VERSION'><glossterm>LINUX_VERSION</glossterm> + <glossentry id='var-LINUX_VERSION'><glossterm><imagedata fileref="figures/define-generic.png" />LINUX_VERSION</glossterm> + <info> + LINUX_VERSION[doc] = "The Linux version from kernel.org on which the Linux kernel image being built using the OpenEmbedded build system is based. You define this variable in the kernel recipe." + </info> <glossdef> <para>The Linux version from <filename>kernel.org</filename> on which the Linux kernel image being built using the @@ -4812,7 +5783,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-LINUX_VERSION_EXTENSION'><glossterm>LINUX_VERSION_EXTENSION</glossterm> + <glossentry id='var-LINUX_VERSION_EXTENSION'><glossterm><imagedata fileref="figures/define-generic.png" />LINUX_VERSION_EXTENSION</glossterm> + <info> + LINUX_VERSION_EXTENSION[doc] = "A string extension compiled into the version string of the Linux kernel built with the OpenEmbedded build system. You define this variable in the kernel recipe." + </info> <glossdef> <para>A string extension compiled into the version string of the Linux kernel built with the OpenEmbedded @@ -4837,7 +5811,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-LOG_DIR'><glossterm>LOG_DIR</glossterm> + <glossentry id='var-LOG_DIR'><glossterm><imagedata fileref="figures/define-generic.png" />LOG_DIR</glossterm> + <info> + LOG_DIR[doc] = "Specifies the directory to which the OpenEmbedded build system writes overall log files. The default directory is ${TMPDIR}/log" + </info> <glossdef> <para> Specifies the directory to which the OpenEmbedded build @@ -4856,7 +5833,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossdiv id='var-glossary-m'><title>M</title> - <glossentry id='var-MACHINE'><glossterm>MACHINE</glossterm> + <glossentry id='var-MACHINE'><glossterm><imagedata fileref="figures/define-generic.png" />MACHINE</glossterm> + <info> + MACHINE[doc] = "Specifies the target device for which the image is built. You define MACHINE in the conf/local.conf file in the Build Directory." + </info> <glossdef> <para> Specifies the target device for which the image is built. @@ -4903,7 +5883,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-MACHINE_ARCH'><glossterm>MACHINE_ARCH</glossterm> + <glossentry id='var-MACHINE_ARCH'><glossterm><imagedata fileref="figures/define-generic.png" />MACHINE_ARCH</glossterm> + <info> + MACHINE_ARCH[doc] = "Specifies the name of the machine-specific architecture. This variable is set automatically from MACHINE or TUNE_PKGARCH." + </info> <glossdef> <para> Specifies the name of the machine-specific architecture. @@ -4917,9 +5900,11 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</glossterm> + <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><glossterm><imagedata fileref="figures/define-generic.png" />MACHINE_ESSENTIAL_EXTRA_RDEPENDS</glossterm> + <info> + MACHINE_ESSENTIAL_EXTRA_RDEPENDS[doc] = "A list of required machine-specific packages to install as part of the image being built. Because this is a 'machine essential' variable, the list of packages are essential for the machine to boot." + </info> <glossdef> - <para></para> <para> A list of required machine-specific packages to install as part of the image being built. @@ -4949,9 +5934,11 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</glossterm> + <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><glossterm><imagedata fileref="figures/define-generic.png" />MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</glossterm> + <info> + MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS[doc] = "A list of recommended machine-specific packages to install as part of the image being built. Because this is a 'machine essential' variable, the list of packages are essential for the machine to boot." + </info> <glossdef> - <para></para> <para> A list of recommended machine-specific packages to install as part of the image being built. @@ -4997,7 +5984,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-MACHINE_EXTRA_RDEPENDS'><glossterm>MACHINE_EXTRA_RDEPENDS</glossterm> + <glossentry id='var-MACHINE_EXTRA_RDEPENDS'><glossterm><imagedata fileref="figures/define-generic.png" />MACHINE_EXTRA_RDEPENDS</glossterm> + <info> + MACHINE_EXTRA_RDEPENDS[doc] = "A list of machine-specific packages to install as part of the image being built that are not essential for the machine to boot. However, the build process for more fully-featured images depends on the packages being present." + </info> <glossdef> <para> A list of machine-specific packages to install as part of the @@ -5036,9 +6026,11 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-MACHINE_EXTRA_RRECOMMENDS'><glossterm>MACHINE_EXTRA_RRECOMMENDS</glossterm> + <glossentry id='var-MACHINE_EXTRA_RRECOMMENDS'><glossterm><imagedata fileref="figures/define-generic.png" />MACHINE_EXTRA_RRECOMMENDS</glossterm> + <info> + MACHINE_EXTRA_RRECOMMENDS[doc] = "A list of machine-specific packages to install as part of the image being built that are not essential for booting the machine. The image being built has no build dependencies on the packages in this list." + </info> <glossdef> - <para></para> <para> A list of machine-specific packages to install as part of the image being built that are not essential for booting the machine. @@ -5075,7 +6067,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-MACHINE_FEATURES'><glossterm>MACHINE_FEATURES</glossterm> + <glossentry id='var-MACHINE_FEATURES'><glossterm><imagedata fileref="figures/define-generic.png" />MACHINE_FEATURES</glossterm> + <info> + MACHINE_FEATURES[doc] = "Specifies the list of hardware features the MACHINE supports." + </info> <glossdef> <para> Specifies the list of hardware features the @@ -5098,7 +6093,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-MACHINE_FEATURES_BACKFILL'><glossterm>MACHINE_FEATURES_BACKFILL</glossterm> + <glossentry id='var-MACHINE_FEATURES_BACKFILL'><glossterm><imagedata fileref="figures/define-generic.png" />MACHINE_FEATURES_BACKFILL</glossterm> + <info> + MACHINE_FEATURES_BACKFILL[doc] = "Features to be added to MACHINE_FEATURES if not also present in MACHINE_FEATURES_BACKFILL_CONSIDERED. This variable is set in the meta/conf/bitbake.conf file and is not intended to be user-configurable." + </info> <glossdef> <para>Features to be added to <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename> @@ -5117,7 +6115,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><glossterm>MACHINE_FEATURES_BACKFILL_CONSIDERED</glossterm> + <glossentry id='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><glossterm><imagedata fileref="figures/define-generic.png" />MACHINE_FEATURES_BACKFILL_CONSIDERED</glossterm> + <info> + MACHINE_FEATURES_BACKFILL_CONSIDERED[doc] = "Features from MACHINE_FEATURES_BACKFILL that should not be backfilled (i.e. added to MACHINE_FEATURES) during the build." + </info> <glossdef> <para>Features from <filename><link linkend='var-MACHINE_FEATURES_BACKFILL'>MACHINE_FEATURES_BACKFILL</link></filename> @@ -5130,7 +6131,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-MACHINEOVERRIDES'><glossterm>MACHINEOVERRIDES</glossterm> + <glossentry id='var-MACHINEOVERRIDES'><glossterm><imagedata fileref="figures/define-generic.png" />MACHINEOVERRIDES</glossterm> + <info> + MACHINEOVERRIDES[doc] = "Lists overrides specific to the current machine. By default, this list includes the value of MACHINE." + </info> <glossdef> <para> Lists overrides specific to the current machine. @@ -5159,13 +6163,19 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-MAINTAINER'><glossterm>MAINTAINER</glossterm> + <glossentry id='var-MAINTAINER'><glossterm><imagedata fileref="figures/define-generic.png" />MAINTAINER</glossterm> + <info> + MAINTAINER[doc] = "The email address of the distribution maintainer." + </info> <glossdef> <para>The email address of the distribution maintainer.</para> </glossdef> </glossentry> - <glossentry id='var-MIRRORS'><glossterm>MIRRORS</glossterm> + <glossentry id='var-MIRRORS'><glossterm><imagedata fileref="figures/define-generic.png" />MIRRORS</glossterm> + <info> + MIRRORS[doc] = "Specifies additional paths from which the OpenEmbedded build system gets source code." + </info> <glossdef> <para> Specifies additional paths from which the OpenEmbedded @@ -5190,7 +6200,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-MLPREFIX'><glossterm>MLPREFIX</glossterm> + <glossentry id='var-MLPREFIX'><glossterm><imagedata fileref="figures/define-generic.png" />MLPREFIX</glossterm> + <info> + MLPREFIX[doc] = "Specifies a prefix has been added to PN to create a special version of a recipe or package, such as a Multilib version." + </info> <glossdef> <para> Specifies a prefix has been added to @@ -5205,56 +6218,40 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-module_autoload'><glossterm>module_autoload</glossterm> + <glossentry id='var-module_autoload'><glossterm><imagedata fileref="figures/define-generic.png" />module_autoload</glossterm> + <info> + module_autoload[doc] = "This variable has been replaced by the KERNEL_MODULE_AUTOLOAD variable. You should replace all occurrences of module_autoload with additions to KERNEL_MODULE_AUTOLOAD." + </info> <glossdef> <para> - Lists kernel modules that need to be auto-loaded during - boot. - </para> - - <para> - You can use this variable anywhere that it can be - recognized by the kernel recipe or out-of-tree kernel - module recipe (e.g. a machine configuration file, a - distribution configuration file, an append file for the - recipe, or the recipe itself). - </para> - - <para> - Specify it as follows: + This variable has been replaced by the + <filename>KERNEL_MODULE_AUTOLOAD</filename> variable. + You should replace all occurrences of + <filename>module_autoload</filename> with additions to + <filename>KERNEL_MODULE_AUTOLOAD</filename>, for example: <literallayout class='monospaced'> - module_autoload_<modname> = "modname1 modname2 modname3" + module_autoload_rfcomm = "rfcomm" </literallayout> - You must use the kernel module name override. - </para> - - <para> - Including <filename>module_autoload</filename> causes the - OpenEmbedded build system to populate the - <filename>/etc/modules-load.d/modname.conf</filename> - file with the list of modules to be auto-loaded on boot. - The modules appear one-per-line in the file. - Here is an example of the most common use case: + should now be replaced with: <literallayout class='monospaced'> - module_autoload_modname = "modname" + KERNEL_MODULE_AUTOLOAD += "rfcomm" </literallayout> - </para> - - <para> - For information on how to populate the - <filename>modname.conf</filename> file with - <filename>modprobe.d</filename> syntax lines, see the - <link linkend='var-module_conf'><filename>module_conf</filename></link> - variable. + See the + <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link> + variable for more information. </para> </glossdef> </glossentry> - <glossentry id='var-module_conf'><glossterm>module_conf</glossterm> + <glossentry id='var-module_conf'><glossterm><imagedata fileref="figures/define-generic.png" />module_conf</glossterm> + <info> + module_conf[doc] = "Specifies modprobe.d syntax lines for inclusion in the /etc/modprobe.d/modname.conf file." + </info> <glossdef> <para> - Specifies <filename>modprobe.d</filename> syntax lines - for inclusion in the + Specifies + <ulink url='http://linux.die.net/man/5/modprobe.d'><filename>modprobe.d</filename></ulink> + syntax lines for inclusion in the <filename>/etc/modprobe.d/modname.conf</filename> file. </para> @@ -5264,19 +6261,23 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" module recipe (e.g. a machine configuration file, a distribution configuration file, an append file for the recipe, or the recipe itself). + If you use this variable, you must also be sure to list + the module name in the + <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link> + variable. </para> <para> Here is the general syntax: <literallayout class='monospaced'> - module_conf_<modname> = "modprobe.d-syntax" + module_conf_<replaceable>module_name</replaceable> = "<replaceable>modprobe.d-syntax</replaceable>" </literallayout> You must use the kernel module name override. </para> <para> Run <filename>man modprobe.d</filename> in the shell to - find out more information on the exact syntax for lines + find out more information on the exact syntax you want to provide with <filename>module_conf</filename>. </para> @@ -5285,22 +6286,27 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" OpenEmbedded build system to populate the <filename>/etc/modprobe.d/modname.conf</filename> file with <filename>modprobe.d</filename> syntax lines. - Here is an example: + Here is an example that adds the options + <filename>arg1</filename> and <filename>arg2</filename> + to a module named <filename>mymodule</filename>: <literallayout class='monospaced'> - module_conf_<modname> = "options modname arg1=val1 arg2=val2" + module_conf_mymodule = "options mymodule arg1=val1 arg2=val2" </literallayout> </para> <para> For information on how to specify kernel modules to auto-load on boot, see the - <link linkend='var-module_autoload'><filename>module_autoload</filename></link> + <link linkend='var-KERNEL_MODULE_AUTOLOAD'><filename>KERNEL_MODULE_AUTOLOAD</filename></link> variable. </para> </glossdef> </glossentry> - <glossentry id='var-MODULE_IMAGE_BASE_NAME'><glossterm>MODULE_IMAGE_BASE_NAME</glossterm> + <glossentry id='var-MODULE_IMAGE_BASE_NAME'><glossterm><imagedata fileref="figures/define-generic.png" />MODULE_IMAGE_BASE_NAME</glossterm> + <info> + MODULE_IMAGE_BASE_NAME[doc] = "The base name of the kernel modules tarball." + </info> <glossdef> <para> The base name of the kernel modules tarball. @@ -5322,7 +6328,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-MODULE_TARBALL_DEPLOY'><glossterm>MODULE_TARBALL_DEPLOY</glossterm> + <glossentry id='var-MODULE_TARBALL_DEPLOY'><glossterm><imagedata fileref="figures/define-generic.png" />MODULE_TARBALL_DEPLOY</glossterm> + <info> + MODULE_TARBALL_DEPLOY[doc] = "Controls creation of the modules-*.tgz file. Set this variable to "0" to disable creation of this file, which contains all of the kernel modules resulting from a kernel build." + </info> <glossdef> <para> Controls creation of the <filename>modules-*.tgz</filename> @@ -5334,7 +6343,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-MULTIMACH_TARGET_SYS'><glossterm>MULTIMACH_TARGET_SYS</glossterm> + <glossentry id='var-MULTIMACH_TARGET_SYS'><glossterm><imagedata fileref="figures/define-generic.png" />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." + </info> <glossdef> <para> Separates files for different machines such that you can build @@ -5349,7 +6361,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossdiv id='var-glossary-n'><title>N</title> - <glossentry id='var-NATIVELSBSTRING'><glossterm>NATIVELSBSTRING</glossterm> + <glossentry id='var-NATIVELSBSTRING'><glossterm><imagedata fileref="figures/define-generic.png" />NATIVELSBSTRING</glossterm> + <info> + NATIVELSBSTRING[doc] = "A string identifying the host distribution." + </info> <glossdef> <para> A string identifying the host distribution. @@ -5374,7 +6389,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-NO_RECOMMENDATIONS'><glossterm>NO_RECOMMENDATIONS</glossterm> + <glossentry id='var-NO_RECOMMENDATIONS'><glossterm><imagedata fileref="figures/define-generic.png" />NO_RECOMMENDATIONS</glossterm> + <info> + NO_RECOMMENDATIONS[doc] = "When set to '1', no recommended packages will be installed. Realize that some recommended packages might be required for certain system functionality, such as kernel-modules. It is up to the user to add packages to IMAGE_INSTALL as needed." + </info> <glossdef> <para> Prevents installation of all "recommended-only" packages. @@ -5391,7 +6409,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <filename>local.conf</filename> file or you can attach it to a specific image recipe by using the recipe name override: <literallayout class='monospaced'> - NO_RECOMMENDATIONS_pn-<target_image> = "<package_name>" + NO_RECOMMENDATIONS_pn-<replaceable>target_image</replaceable> = "<replaceable>package_name</replaceable>" </literallayout> </para> @@ -5428,7 +6446,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-NOHDD'><glossterm>NOHDD</glossterm> + <glossentry id='var-NOHDD'><glossterm><imagedata fileref="figures/define-generic.png" />NOHDD</glossterm> + <info> + NOHDD[doc] = "Causes the OpenEmbedded build system to skip building the .hddimg image." + </info> <glossdef> <para> Causes the OpenEmbedded build system to skip building the @@ -5442,7 +6463,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-NOISO'><glossterm>NOISO</glossterm> + <glossentry id='var-NOISO'><glossterm><imagedata fileref="figures/define-generic.png" />NOISO</glossterm> + <info> + NOISO[doc] = "Causes the OpenEmbedded build system to skip building the ISO image." + </info> <glossdef> <para> Causes the OpenEmbedded build system to skip building the @@ -5461,11 +6485,15 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossdiv id='var-glossary-o'><title>O</title> - <glossentry id='var-OE_BINCONFIG_EXTRA_MANGLE'><glossterm>OE_BINCONFIG_EXTRA_MANGLE</glossterm> + <glossentry id='var-OE_BINCONFIG_EXTRA_MANGLE'><glossterm><imagedata fileref="figures/define-generic.png" />OE_BINCONFIG_EXTRA_MANGLE</glossterm> + <info> + OE_BINCONFIG_EXTRA_MANGLE[doc] = "When a recipe inherits the binconfig.bbclass class, this variable specifies additional arguments passed to the "sed" command." + </info> <glossdef> <para> - When a recipe inherits the - <filename>binconfig.bbclass</filename> class, this variable + When inheriting the + <link linkend='ref-classes-binconfig'><filename>binconfig</filename></link> + class, this variable specifies additional arguments passed to the "sed" command. The sed command alters any paths in configuration scripts that have been set up during compilation. @@ -5490,7 +6518,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-OE_IMPORTS'><glossterm>OE_IMPORTS</glossterm> + <glossentry id='var-OE_IMPORTS'><glossterm><imagedata fileref="figures/define-generic.png" />OE_IMPORTS</glossterm> + <info> + OE_IMPORTS[doc] = "An internal variable used to tell the OpenEmbedded build system what Python modules to import for every Python function run by the system." + </info> <glossdef> <para> An internal variable used to tell the OpenEmbedded build @@ -5505,7 +6536,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-OE_TERMINAL'><glossterm>OE_TERMINAL</glossterm> + <glossentry id='var-OE_TERMINAL'><glossterm><imagedata fileref="figures/define-generic.png" />OE_TERMINAL</glossterm> + <info> + OE_TERMINAL[doc] = "Controls how the OpenEmbedded build system spawns interactive terminals on the host development system." + </info> <glossdef> <para> Controls how the OpenEmbedded build system spawns @@ -5536,7 +6570,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-OEROOT'><glossterm>OEROOT</glossterm> + <glossentry id='var-OEROOT'><glossterm><imagedata fileref="figures/define-generic.png" />OEROOT</glossterm> + <info> + OEROOT[doc] = "The directory from which the top-level build environment setup script is sourced." + </info> <glossdef> <para> The directory from which the top-level build environment @@ -5558,7 +6595,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-OLDEST_KERNEL'><glossterm>OLDEST_KERNEL</glossterm> + <glossentry id='var-OLDEST_KERNEL'><glossterm><imagedata fileref="figures/define-generic.png" />OLDEST_KERNEL</glossterm> + <info> + OLDEST_KERNEL[doc] = "Declares the oldest version of the Linux kernel that the produced binaries must support." + </info> <glossdef> <para> Declares the oldest version of the Linux kernel that the @@ -5577,7 +6617,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-OVERRIDES'><glossterm>OVERRIDES</glossterm> + <glossentry id='var-OVERRIDES'><glossterm><imagedata fileref="figures/define-generic.png" />OVERRIDES</glossterm> + <info> + OVERRIDES[doc] = "BitBake uses OVERRIDES to control what variables are overridden after BitBake parses recipes and configuration files." + </info> <glossdef> <para> BitBake uses <filename>OVERRIDES</filename> to control @@ -5594,7 +6637,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossdiv id='var-glossary-p'><title>P</title> - <glossentry id='var-P'><glossterm>P</glossterm> + <glossentry id='var-P'><glossterm><imagedata fileref="figures/define-generic.png" />P</glossterm> + <info> + P[doc] = "The recipe name and version. P is comprised of ${PN}-${PV}." + </info> <glossdef> <para>The recipe name and version. <filename>P</filename> is comprised of the following: @@ -5604,7 +6650,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-PACKAGE_ARCH'><glossterm>PACKAGE_ARCH</glossterm> + <glossentry id='var-PACKAGE_ARCH'><glossterm><imagedata fileref="figures/define-generic.png" />PACKAGE_ARCH</glossterm> + <info> + PACKAGE_ARCH[doc] = "The architecture of the resulting package or packages." + </info> <glossdef> <para> The architecture of the resulting package or packages. @@ -5630,7 +6679,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-PACKAGE_ARCHS'><glossterm>PACKAGE_ARCHS</glossterm> + <glossentry id='var-PACKAGE_ARCHS'><glossterm><imagedata fileref="figures/define-generic.png" />PACKAGE_ARCHS</glossterm> + <info> + PACKAGE_ARCHS[doc] = "A list of architectures compatible with the given target in order of priority." + </info> <glossdef> <para> Specifies a list of architectures compatible with @@ -5646,9 +6698,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - - - <glossentry id='var-PACKAGE_BEFORE_PN'><glossterm>PACKAGE_BEFORE_PN</glossterm> + <glossentry id='var-PACKAGE_BEFORE_PN'><glossterm><imagedata fileref="figures/define-generic.png" />PACKAGE_BEFORE_PN</glossterm> + <info> + PACKAGE_BEFORE_PN[doc] = "Enables easily adding packages to PACKAGES before ${PN} so that the packages can pick up files that would normally be included in the default package." + </info> <glossdef> <para>Enables easily adding packages to <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename> @@ -5658,7 +6711,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-PACKAGE_CLASSES'><glossterm>PACKAGE_CLASSES</glossterm> + <glossentry id='var-PACKAGE_CLASSES'><glossterm><imagedata fileref="figures/define-generic.png" />PACKAGE_CLASSES</glossterm> + <info> + PACKAGE_CLASSES[doc] = "This variable specifies the package manager to use when packaging data. It is set in the conf/local.conf file in the Build Directory." + </info> <glossdef> <para> This variable, which is set in the @@ -5707,19 +6763,80 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-PACKAGE_EXCLUDE'><glossterm>PACKAGE_EXCLUDE</glossterm> + <glossentry id='var-PACKAGE_DEBUG_SPLIT_STYLE'><glossterm><imagedata fileref="figures/define-generic.png" />PACKAGE_DEBUG_SPLIT_STYLE</glossterm> + <info> + PACKAGE_DEBUG_SPLIT_STYLE[doc] = "Determines how to split up the binary and debug information when creating *-dbg packages to be used with the GNU Project Debugger (GDB)." + </info> + <glossdef> + <para> + Determines how to split up the binary and debug information + when creating <filename>*-dbg</filename> packages to be + used with the GNU Project Debugger (GDB). + </para> + + <para> + With the + <filename>PACKAGE_DEBUG_SPLIT_STYLE</filename> variable, + you can control where debug information, which can include + or exclude source files, is stored: + <itemizedlist> + <listitem><para> + ".debug": Debug symbol files are placed next + to the binary in a <filename>.debug</filename> + directory on the target. + For example, if a binary is installed into + <filename>/bin</filename>, the corresponding debug + symbol files are installed in + <filename>/bin/.debug</filename>. + Source files are placed in + <filename>/usr/src/debug</filename>. + This is the default behavior. + </para></listitem> + <listitem><para> + "debug-file-directory": Debug symbol files are + placed under <filename>/usr/lib/debug</filename> + on the target, and separated by the path from where + the binary is installed. + For example, if a binary is installed in + <filename>/bin</filename>, the corresponding debug + symbols are installed in + <filename>/usr/lib/debug/bin</filename>. + Source files are placed in + <filename>/usr/src/debug</filename>. + </para></listitem> + <listitem><para> + "debug-without-src": The same behavior as + ".debug" previously described with the exception + that no source files are installed. + </para></listitem>. + </itemizedlist> + </para> + + <para> + You can find out more about debugging using GDB by reading + the + "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-gdb-remotedebug'>Debugging With the GNU Project Debugger (GDB) Remotely</ulink>" + section in the Yocto Project Development Manual. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-PACKAGE_EXCLUDE'><glossterm><imagedata fileref="figures/define-generic.png" />PACKAGE_EXCLUDE</glossterm> + <info> + PACKAGE_EXCLUDE[doc] = "Packages to exclude from the installation. If a listed package is required, an error is generated." + </info> <glossdef> <para> Lists packages that should not be installed into an image. For example: <literallayout class='monospaced'> - PACKAGE_EXCLUDE = "<package_name> <package_name> <package_name> ..." + PACKAGE_EXCLUDE = "<replaceable>package_name</replaceable> <replaceable>package_name</replaceable> <replaceable>package_name</replaceable> ..." </literallayout> You can set this variable globally in your <filename>local.conf</filename> file or you can attach it to a specific image recipe by using the recipe name override: <literallayout class='monospaced'> - PACKAGE_EXCLUDE_pn-<target_image> = "<package_name>" + PACKAGE_EXCLUDE_pn-<replaceable>target_image</replaceable> = "<replaceable>package_name</replaceable>" </literallayout> </para> @@ -5752,17 +6869,22 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-PACKAGE_EXTRA_ARCHS'><glossterm>PACKAGE_EXTRA_ARCHS</glossterm> + <glossentry id='var-PACKAGE_EXTRA_ARCHS'><glossterm><imagedata fileref="figures/define-generic.png" />PACKAGE_EXTRA_ARCHS</glossterm> + <info> + PACKAGE_EXTRA_ARCHS[doc] = "Specifies the list of architectures compatible with the device CPU. This variable is useful when you build for several different devices that use miscellaneous processors." + </info> <glossdef> <para>Specifies the list of architectures compatible with the device CPU. This variable is useful when you build for several different devices that use - miscellaneous processors such as XScale and ARM926-EJS).</para> + miscellaneous processors such as XScale and ARM926-EJS.</para> </glossdef> </glossentry> - <glossentry id='var-PACKAGE_GROUP'><glossterm>PACKAGE_GROUP</glossterm> + <glossentry id='var-PACKAGE_GROUP'><glossterm><imagedata fileref="figures/define-generic.png" />PACKAGE_GROUP</glossterm> + <info> + PACKAGE_GROUP[doc] = "Defines one or more packages to include in an image when a specific item is included in IMAGE_FEATURES." + </info> <glossdef> - <para> The <filename>PACKAGE_GROUP</filename> variable has been renamed to @@ -5779,7 +6901,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-PACKAGE_INSTALL'><glossterm>PACKAGE_INSTALL</glossterm> + <glossentry id='var-PACKAGE_INSTALL'><glossterm><imagedata fileref="figures/define-generic.png" />PACKAGE_INSTALL</glossterm> + <info> + PACKAGE_INSTALL[doc] = "List of the packages to be installed into the image. The variable is generally not user-defined and uses IMAGE_INSTALL as part of the list." + </info> <glossdef> <para> The final list of packages passed to the package manager @@ -5807,7 +6932,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-PACKAGE_PREPROCESS_FUNCS'><glossterm>PACKAGE_PREPROCESS_FUNCS</glossterm> + <glossentry id='var-PACKAGE_PREPROCESS_FUNCS'><glossterm><imagedata fileref="figures/define-generic.png" />PACKAGE_PREPROCESS_FUNCS</glossterm> + <info> + PACKAGE_PREPROCESS_FUNCS[doc] = "Specifies a list of functions run to pre-process the PKGD directory prior to splitting the files out to individual packages." + </info> <glossdef> <para> Specifies a list of functions run to pre-process the @@ -5818,7 +6946,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-PACKAGECONFIG'><glossterm>PACKAGECONFIG</glossterm> + <glossentry id='var-PACKAGECONFIG'><glossterm><imagedata fileref="figures/define-generic.png" />PACKAGECONFIG</glossterm> + <info> + PACKAGECONFIG[doc] = "This variable provides a means of enabling or disabling features of a recipe on a per-recipe basis." + </info> <glossdef> <para> This variable provides a means of enabling or disabling @@ -5903,8 +7034,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <itemizedlist> <listitem><para><emphasis>Append file:</emphasis> Create an append file named - <filename><recipename>.bbappend</filename> in your - layer and override the value of + <replaceable>recipename</replaceable><filename>.bbappend</filename> + in your layer and override the value of <filename>PACKAGECONFIG</filename>. You can either completely override the variable: <literallayout class='monospaced'> @@ -5918,22 +7049,25 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" This method is identical to changing the block through an append file except you edit your <filename>local.conf</filename> or - <filename><mydistro>.conf</filename> file. + <filename><replaceable>mydistro</replaceable>.conf</filename> file. As with append files previously described, you can either completely override the variable: <literallayout class='monospaced'> - PACKAGECONFIG_pn-<recipename>="f4 f5" + PACKAGECONFIG_pn-<replaceable>recipename</replaceable>="f4 f5" </literallayout> Or, you can just amend the variable: <literallayout class='monospaced'> - PACKAGECONFIG_append_pn-<recipename> = " f4" + PACKAGECONFIG_append_pn-<replaceable>recipename</replaceable> = " f4" </literallayout></para></listitem> </itemizedlist> </para> </glossdef> </glossentry> - <glossentry id='var-PACKAGES'><glossterm>PACKAGES</glossterm> + <glossentry id='var-PACKAGES'><glossterm><imagedata fileref="figures/define-generic.png" />PACKAGES</glossterm> + <info> + PACKAGES[doc] = "The list of packages to be created from the recipe." + </info> <glossdef> <para>The list of packages to be created from the recipe. The default value is the following: @@ -5943,25 +7077,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-PACKAGESPLITFUNCS'><glossterm>PACKAGESPLITFUNCS</glossterm> - <glossdef> - <para> - Specifies a list of functions run to perform additional - splitting of files into individual packages. - Recipes can either prepend to this variable or prepend - to the <filename>populate_packages</filename> function - in order to perform additional package splitting. - In either case, the function should set - <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>, - <link linkend='var-FILES'><filename>FILES</filename></link>, - <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> - and other packaging variables appropriately in order to - perform the desired splitting. - </para> - </glossdef> - </glossentry> - - <glossentry id='var-PACKAGES_DYNAMIC'><glossterm>PACKAGES_DYNAMIC</glossterm> + <glossentry id='var-PACKAGES_DYNAMIC'><glossterm><imagedata fileref="figures/define-generic.png" />PACKAGES_DYNAMIC</glossterm> + <info> + PACKAGES_DYNAMIC[doc] = "A promise that your recipe satisfies runtime dependencies for optional modules that are found in other recipes." + </info> <glossdef> <para> A promise that your recipe satisfies runtime dependencies @@ -5999,7 +7118,31 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-PARALLEL_MAKE'><glossterm>PARALLEL_MAKE</glossterm> + <glossentry id='var-PACKAGESPLITFUNCS'><glossterm><imagedata fileref="figures/define-generic.png" />PACKAGESPLITFUNCS</glossterm> + <info> + PACKAGESPLITFUNCS[doc] = "Specifies a list of functions run to perform additional splitting of files into individual packages." + </info> + <glossdef> + <para> + Specifies a list of functions run to perform additional + splitting of files into individual packages. + Recipes can either prepend to this variable or prepend + to the <filename>populate_packages</filename> function + in order to perform additional package splitting. + In either case, the function should set + <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>, + <link linkend='var-FILES'><filename>FILES</filename></link>, + <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> + and other packaging variables appropriately in order to + perform the desired splitting. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-PARALLEL_MAKE'><glossterm><imagedata fileref="figures/define-generic.png" />PARALLEL_MAKE</glossterm> + <info> + PARALLEL_MAKE[doc] = "Specifies extra options that are passed to the make command during the compile tasks. This variable is usually in the form -j 4, where the number represents the maximum number of parallel threads make can run." + </info> <glossdef> <para> Extra options passed to the <filename>make</filename> @@ -6027,7 +7170,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-PARALLEL_MAKEINST'><glossterm>PARALLEL_MAKEINST</glossterm> + <glossentry id='var-PARALLEL_MAKEINST'><glossterm><imagedata fileref="figures/define-generic.png" />PARALLEL_MAKEINST</glossterm> + <info> + PARALLEL_MAKEINST[doc] = "Extra options passed to the make install command during the do_install task in order to specify parallel installation." + </info> <glossdef> <para> Extra options passed to the @@ -6045,7 +7191,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-PATCHRESOLVE'><glossterm>PATCHRESOLVE</glossterm> + <glossentry id='var-PATCHRESOLVE'><glossterm><imagedata fileref="figures/define-generic.png" />PATCHRESOLVE</glossterm> + <info> + PATCHRESOLVE[doc] = "Enable or disable interactive patch resolution." + </info> <glossdef> <para> Determines the action to take when a patch fails. @@ -6069,7 +7218,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-PATCHTOOL'><glossterm>PATCHTOOL</glossterm> + <glossentry id='var-PATCHTOOL'><glossterm><imagedata fileref="figures/define-generic.png" />PATCHTOOL</glossterm> + <info> + PATCHTOOL[doc] = "Specifies the utility used to apply patches for a recipe during do_patch." + </info> <glossdef> <para> Specifies the utility used to apply patches for a recipe @@ -6096,7 +7248,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-PE'><glossterm>PE</glossterm> + <glossentry id='var-PE'><glossterm><imagedata fileref="figures/define-generic.png" />PE</glossterm> + <info> + PE[doc] = "The epoch of the recipe. The default value is '0'. The field is used to make upgrades possible when the versioning scheme changes in some backwards incompatible way." + </info> <glossdef> <para> The epoch of the recipe. @@ -6108,7 +7263,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-PF'><glossterm>PF</glossterm> + <glossentry id='var-PF'><glossterm><imagedata fileref="figures/define-generic.png" />PF</glossterm> + <info> + PF[doc] = "Specifies the recipe or package name and includes all version and revision numbers. This variable is comprised of ${PN}-${EXTENDPE}${PV}-${PR}." + </info> <glossdef> <para>Specifies the recipe or package name and includes all version and revision numbers (i.e. <filename>eglibc-2.13-r20+svnr15508/</filename> and @@ -6120,10 +7278,13 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-PIXBUF_PACKAGES'><glossterm>PIXBUF_PACKAGES</glossterm> + <glossentry id='var-PIXBUF_PACKAGES'><glossterm><imagedata fileref="figures/define-generic.png" />PIXBUF_PACKAGES</glossterm> + <info> + PIXBUF_PACKAGES[doc] = "When a recipe inherits the pixbufcache class, this variable identifies packages that contain the pixbuf loaders used with gdk-pixbuf." + </info> <glossdef> <para> - When a recipe inherits the + When inheriting the <link linkend='ref-classes-pixbufcache'><filename>pixbufcache</filename></link> class, this variable identifies packages that contain the pixbuf loaders used with @@ -6137,7 +7298,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-PKG'><glossterm>PKG</glossterm> + <glossentry id='var-PKG'><glossterm><imagedata fileref="figures/define-generic.png" />PKG</glossterm> + <info> + PKG[doc] = "The name of the resulting package created by the OpenEmbedded build system. When you use this variable, you must use a package name override." + </info> <glossdef> <para> The name of the resulting package created by the @@ -6149,12 +7313,15 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" For example, when the <link linkend='ref-classes-debian'><filename>debian</filename></link> class renames the output package, it does so by setting - <filename>PKG_<packagename></filename>. + <filename>PKG_<replaceable>packagename</replaceable></filename>. </para> </glossdef> </glossentry> - <glossentry id='var-PKGD'><glossterm>PKGD</glossterm> + <glossentry id='var-PKGD'><glossterm><imagedata fileref="figures/define-generic.png" />PKGD</glossterm> + <info> + PKGD[doc] = "Points to the destination directory for files to be packaged before they are split into individual packages." + </info> <glossdef> <para> Points to the destination directory for files to be @@ -6168,7 +7335,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-PKGDATA_DIR'><glossterm>PKGDATA_DIR</glossterm> + <glossentry id='var-PKGDATA_DIR'><glossterm><imagedata fileref="figures/define-generic.png" />PKGDATA_DIR</glossterm> + <info> + PKGDATA_DIR[doc] = "Points to a shared, global-state directory that holds data generated during the packaging process." + </info> <glossdef> <para> Points to a shared, global-state directory that holds data @@ -6186,7 +7356,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-PKGDEST'><glossterm>PKGDEST</glossterm> + <glossentry id='var-PKGDEST'><glossterm><imagedata fileref="figures/define-generic.png" />PKGDEST</glossterm> + <info> + PKGDEST[doc] = "Points to the parent directory for files to be packaged after they have been split into individual packages." + </info> <glossdef> <para> Points to the parent directory for files to be packaged @@ -6203,7 +7376,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-PKGDESTWORK'><glossterm>PKGDESTWORK</glossterm> + <glossentry id='var-PKGDESTWORK'><glossterm><imagedata fileref="figures/define-generic.png" />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." + </info> <glossdef> <para> Points to a temporary work area used by the @@ -6228,7 +7404,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-PKGE'><glossterm>PKGE</glossterm> + <glossentry id='var-PKGE'><glossterm><imagedata fileref="figures/define-generic.png" />PKGE</glossterm> + <info> + PKGE[doc] = "The epoch of the output package built by the OpenEmbedded build system." + </info> <glossdef> <para> The epoch of the output package built by the @@ -6239,7 +7418,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-PKGR'><glossterm>PKGR</glossterm> + <glossentry id='var-PKGR'><glossterm><imagedata fileref="figures/define-generic.png" />PKGR</glossterm> + <info> + PKGR[doc] = "The revision of the output package built by the OpenEmbedded build system." + </info> <glossdef> <para> The revision of the output package built by the @@ -6250,7 +7432,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-PKGV'><glossterm>PKGV</glossterm> + <glossentry id='var-PKGV'><glossterm><imagedata fileref="figures/define-generic.png" />PKGV</glossterm> + <info> + PKGV[doc] = "The version of the output package built by the OpenEmbedded build system." + </info> <glossdef> <para> The version of the output package built by the @@ -6261,7 +7446,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-PN'><glossterm>PN</glossterm> + <glossentry id='var-PN'><glossterm><imagedata fileref="figures/define-generic.png" />PN</glossterm> + <info> + PN[doc] = "PN refers to a recipe name in the context of a file used by the OpenEmbedded build system as input to create a package. It refers to a package name in the context of a file created or produced by the OpenEmbedded build system." + </info> <glossdef> <para>This variable can have two separate functions depending on the context: a recipe name or a resulting package name.</para> @@ -6285,7 +7473,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-PNBLACKLIST'><glossterm>PNBLACKLIST</glossterm> + <glossentry id='var-PNBLACKLIST'><glossterm><imagedata fileref="figures/define-generic.png" />PNBLACKLIST</glossterm> + <info> + PNBLACKLIST[doc] = "Lists recipes you do not want the OpenEmbedded build system to build." + </info> <glossdef> <para> Lists recipes you do not want the OpenEmbedded build system @@ -6309,7 +7500,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-PR'><glossterm>PR</glossterm> + <glossentry id='var-PR'><glossterm><imagedata fileref="figures/define-generic.png" />PR</glossterm> + <info> + PR[doc] = "The revision of the recipe. The default value for this variable is 'r0'." + </info> <glossdef> <para> The revision of the recipe. @@ -6318,7 +7512,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-PREFERRED_PROVIDER'><glossterm>PREFERRED_PROVIDER</glossterm> + <glossentry id='var-PREFERRED_PROVIDER'><glossterm><imagedata fileref="figures/define-generic.png" />PREFERRED_PROVIDER</glossterm> + <info> + PREFERRED_PROVIDER[doc] = "If multiple recipes provide an item, this variable determines which recipe should be given preference." + </info> <glossdef> <para> If multiple recipes provide an item, this variable @@ -6337,7 +7534,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-PREFERRED_VERSION'><glossterm>PREFERRED_VERSION</glossterm> + <glossentry id='var-PREFERRED_VERSION'><glossterm><imagedata fileref="figures/define-generic.png" />PREFERRED_VERSION</glossterm> + <info> + PREFERRED_VERSION[doc] = "If there are multiple versions of recipes available, this variable determines which recipe should be given preference." + </info> <glossdef> <para> If there are multiple versions of recipes available, this @@ -6360,7 +7560,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-PREMIRRORS'><glossterm>PREMIRRORS</glossterm> + <glossentry id='var-PREMIRRORS'><glossterm><imagedata fileref="figures/define-generic.png" />PREMIRRORS</glossterm> + <info> + PREMIRRORS[doc] = "Specifies additional paths from which the OpenEmbedded build system gets source code." + </info> <glossdef> <para> Specifies additional paths from which the OpenEmbedded @@ -6405,7 +7608,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-PRINC'><glossterm>PRINC</glossterm> + <glossentry id='var-PRINC'><glossterm><imagedata fileref="figures/define-generic.png" />PRINC</glossterm> + <info> + PRINC[doc] = "Causes the PR variable of .bbappend files to dynamically increment. This increment minimizes the impact of layer ordering. This variable defaults to '0'." + </info> <glossdef> <para> @@ -6451,7 +7657,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-PRIVATE_LIBS'><glossterm>PRIVATE_LIBS</glossterm> + <glossentry id='var-PRIVATE_LIBS'><glossterm><imagedata fileref="figures/define-generic.png" />PRIVATE_LIBS</glossterm> + <info> + PRIVATE_LIBS[doc] = "Specifies libraries installed within a recipe that should be ignored by the OpenEmbedded build system's shared library resolver." + </info> <glossdef> <para> Specifies libraries installed within a recipe that @@ -6483,7 +7692,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-PROVIDES'><glossterm>PROVIDES</glossterm> + <glossentry id='var-PROVIDES'><glossterm><imagedata fileref="figures/define-generic.png" />PROVIDES</glossterm> + <info> + PROVIDES[doc] = "A list of aliases that a recipe also provides. These aliases are useful for satisfying dependencies of other recipes during the build as specified by DEPENDS." + </info> <glossdef> <para> A list of aliases by which a particular recipe can be @@ -6512,7 +7724,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-PRSERV_HOST'><glossterm>PRSERV_HOST</glossterm> + <glossentry id='var-PRSERV_HOST'><glossterm><imagedata fileref="figures/define-generic.png" />PRSERV_HOST</glossterm> + <info> + PRSERV_HOST[doc] = "The network based PR service host and port." + </info> <glossdef> <para> The network based @@ -6538,7 +7753,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-PTEST_ENABLED'><glossterm>PTEST_ENABLED</glossterm> + <glossentry id='var-PTEST_ENABLED'><glossterm><imagedata fileref="figures/define-generic.png" />PTEST_ENABLED</glossterm> + <info> + PRSERV_HOST[doc] = "Specifies whether or not Package Test (ptest) functionality is enabled when building a recipe." + </info> <glossdef> <para> Specifies whether or not @@ -6553,7 +7771,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-PV'><glossterm>PV</glossterm> + <glossentry id='var-PV'><glossterm><imagedata fileref="figures/define-generic.png" />PV</glossterm> + <info> + PV[doc] = "The version of the recipe. The version is normally extracted from the recipe filename." + </info> <glossdef> <para> The version of the recipe. @@ -6568,7 +7789,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-PYTHON_ABI'><glossterm>PYTHON_ABI</glossterm> + <glossentry id='var-PYTHON_ABI'><glossterm><imagedata fileref="figures/define-generic.png" />PYTHON_ABI</glossterm> + <info> + PYTHON_ABI[doc] = "When used by recipes that inherit the distutils3, setuptools3, distutils, or setuptools classes, denotes the Application Binary Interface (ABI) currently in use for Python." + </info> <glossdef> <para> When used by recipes that inherit the @@ -6601,7 +7825,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-PYTHON_PN'><glossterm>PYTHON_PN</glossterm> + <glossentry id='var-PYTHON_PN'><glossterm><imagedata fileref="figures/define-generic.png" />PYTHON_PN</glossterm> + <info> + PYTHON_PN[doc] = "When used by recipes that inherit the distutils3, setuptools3, distutils, or setuptools classes, specifies the major Python version being built." + </info> <glossdef> <para> When used by recipes that inherit the @@ -6634,7 +7861,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossdiv id='var-glossary-q'><title>Q</title> - <glossentry id='var-QMAKE_PROFILES'><glossterm>QMAKE_PROFILES</glossterm> + <glossentry id='var-QMAKE_PROFILES'><glossterm><imagedata fileref="figures/define-generic.png" />QMAKE_PROFILES</glossterm> + <info> + QMAKE_PROFILES[doc] = "Specifies your own subset of .pro files to be built for use with qmake." + </info> <glossdef> <para> Specifies your own subset of <filename>.pro</filename> @@ -6659,7 +7889,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossdiv id='var-glossary-r'><title>R</title> - <glossentry id='var-RCONFLICTS'><glossterm>RCONFLICTS</glossterm> + <glossentry id='var-RCONFLICTS'><glossterm><imagedata fileref="figures/define-generic.png" />RCONFLICTS</glossterm> + <info> + RCONFLICTS[doc] = "The list of packages that conflict with another package. Note that the package will not be installed if the conflicting packages are not first removed." + </info> <glossdef> <para> The list of packages that conflict with packages. @@ -6672,7 +7905,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" them in conjunction with a package name override. Here is an example: <literallayout class='monospaced'> - RCONFLICTS_${PN} = "another-conflicting-package-name" + RCONFLICTS_${PN} = "<replaceable>another-conflicting-package-name</replaceable>" </literallayout> </para> @@ -6684,7 +7917,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" Here is the general syntax to specify versions with the <filename>RCONFLICTS</filename> variable: <literallayout class='monospaced'> - RCONFLICTS_${PN} = "<package> (<operator> <version>)" + RCONFLICTS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)" </literallayout> For <filename>operator</filename>, you can specify the following: @@ -6704,7 +7937,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm> + <glossentry id='var-RDEPENDS'><glossterm><imagedata fileref="figures/define-generic.png" />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)." + </info> <glossdef> <para> Lists a package's runtime dependencies (i.e. other packages) @@ -6776,7 +8012,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" 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.bbclass</filename></link>. + <link linkend='ref-classes-debian'><filename>debian</filename></link>. </para> <para> @@ -6810,7 +8046,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" Here is the general syntax to specify versions with the <filename>RDEPENDS</filename> variable: <literallayout class='monospaced'> - RDEPENDS_${PN} = "<package> (<operator> <version>)" + RDEPENDS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)" </literallayout> For <filename>operator</filename>, you can specify the following: @@ -6836,11 +8072,15 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-REQUIRED_DISTRO_FEATURES'><glossterm>REQUIRED_DISTRO_FEATURES</glossterm> + <glossentry id='var-REQUIRED_DISTRO_FEATURES'><glossterm><imagedata fileref="figures/define-generic.png" />REQUIRED_DISTRO_FEATURES</glossterm> + <info> + REQUIRED_DISTRO_FEATURES[doc] = "When a recipe inherits the distro_features_check class, this variable identifies distribution features that must exist in the current configuration in order for the OpenEmbedded build system to build the recipe." + </info> <glossdef> <para> - When a recipe inherits the - <filename>distro_features_check</filename> class, this + When inheriting the + <link linkend='ref-classes-distro_features_check'><filename>distro_features_check</filename></link> + class, this variable identifies distribution features that must exist in the current configuration in order for the OpenEmbedded build system to build the recipe. @@ -6854,7 +8094,10 @@ 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> + <glossentry id='var-RM_OLD_IMAGE'><glossterm><imagedata fileref="figures/define-generic.png" />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> Reclaims disk space by removing previously built @@ -6872,7 +8115,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-RM_WORK_EXCLUDE'><glossterm>RM_WORK_EXCLUDE</glossterm> + <glossentry id='var-RM_WORK_EXCLUDE'><glossterm><imagedata fileref="figures/define-generic.png" />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." + </info> <glossdef> <para> With <filename>rm_work</filename> enabled, this @@ -6884,7 +8130,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-ROOT_HOME'><glossterm>ROOT_HOME</glossterm> + <glossentry id='var-ROOT_HOME'><glossterm><imagedata fileref="figures/define-generic.png" />ROOT_HOME</glossterm> + <info> + ROOT_HOME[doc] = "Defines the root home directory." + </info> <glossdef> <para> Defines the root home directory. @@ -6917,7 +8166,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-ROOTFS'><glossterm>ROOTFS</glossterm> + <glossentry id='var-ROOTFS'><glossterm><imagedata fileref="figures/define-generic.png" />ROOTFS</glossterm> + <info> + ROOTFS[doc] = "Indicates a filesystem image to include as the root filesystem." + </info> <glossdef> <para> Indicates a filesystem image to include as the root @@ -6933,14 +8185,17 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-ROOTFS_POSTPROCESS_COMMAND'><glossterm>ROOTFS_POSTPROCESS_COMMAND</glossterm> + <glossentry id='var-ROOTFS_POSTPROCESS_COMMAND'><glossterm><imagedata fileref="figures/define-generic.png" />ROOTFS_POSTPROCESS_COMMAND</glossterm> + <info> + ROOTFS_POSTPROCESS_COMMAND[doc] = "Added by classes to run post processing commands once the OpenEmbedded build system has created the root filesystem." + </info> <glossdef> <para> Added by classes to run post processing commands once the OpenEmbedded build system has created the root filesystem. You can specify shell commands separated by semicolons: <literallayout class='monospaced'> - ROOTFS_POSTPROCESS_COMMAND += "<shell_command>; ... " + ROOTFS_POSTPROCESS_COMMAND += "<replaceable>shell_command</replaceable>; ... " </literallayout> If you need to pass the path to the root filesystem within the command, you can use @@ -6953,7 +8208,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-RPROVIDES'><glossterm>RPROVIDES</glossterm> + <glossentry id='var-RPROVIDES'><glossterm><imagedata fileref="figures/define-generic.png" />RPROVIDES</glossterm> + <info> + RPROVIDES[doc] = "A list of package name aliases that a package also provides. These aliases are useful for satisfying runtime dependencies of other packages both during the build and on the target." + </info> <glossdef> <para> A list of package name aliases that a package also provides. @@ -6977,37 +8235,49 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-RRECOMMENDS'><glossterm>RRECOMMENDS</glossterm> + <glossentry id='var-RRECOMMENDS'><glossterm><imagedata fileref="figures/define-generic.png" />RRECOMMENDS</glossterm> + <info> + RRECOMMENDS[doc] = "A list of packages that extends the usability of a package being built. The package being built does not depend on this list of packages in order to successfully build, but needs them for the extended usability." + </info> <glossdef> <para> A list of packages that extends the usability of a package being built. The package being built does not depend on this list of - packages in order to successfully build, but needs them for - the extended usability. + packages in order to successfully build, but rather + uses them for extended usability. To specify runtime dependencies for packages, see the <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename> variable. </para> <para> - The OpenEmbedded build process automatically installs the - list of packages as part of the built package. - However, you can remove these packages later if you want. - If, during the build, a package from the - <filename>RRECOMMENDS</filename> list cannot be - found, the build process continues without an error. - </para> - - <para> - You can also prevent packages in the list from being - installed by using several variables. - See the + The package manager will automatically install the + <filename>RRECOMMENDS</filename> list of packages when + installing the built package. + However, you can prevent listed packages from being + installed by using the <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>, <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>, and <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link> - variables for more information. + variables. + </para> + + <para> + Packages specified in + <filename>RRECOMMENDS</filename> need not actually be + produced. + However, a recipe must exist that provides each package, + either through the + <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link> + or + <link linkend='var-PACKAGES_DYNAMIC'><filename>PACKAGES_DYNAMIC</filename></link> + variables or the + <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link> + variable, or an error will occur during the build. + If such a recipe does exist and the package is not produced, + the build continues without error. </para> <para> @@ -7019,7 +8289,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" that is extended to support wireless functionality. In this case, you would use the following: <literallayout class='monospaced'> - RRECOMMENDS_${PN}-dev += "<wireless_package_name>" + RRECOMMENDS_${PN}-dev += "<replaceable>wireless_package_name</replaceable>" </literallayout> In the example, the package name (<filename>${<link linkend='var-PN'>PN</link>}-dev</filename>) @@ -7037,7 +8307,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" Here is the general syntax to specify versions with the <filename>RRECOMMENDS</filename> variable: <literallayout class='monospaced'> - RRECOMMENDS_${PN} = "<package> (<operator> <version>)" + RRECOMMENDS_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)" </literallayout> For <filename>operator</filename>, you can specify the following: @@ -7057,7 +8327,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-RREPLACES'><glossterm>RREPLACES</glossterm> + <glossentry id='var-RREPLACES'><glossterm><imagedata fileref="figures/define-generic.png" />RREPLACES</glossterm> + <info> + RREPLACES[doc] = "A list of packages replaced by a package. The package manager uses this variable to determine which package should be installed to replace other package(s) during an upgrade." + </info> <glossdef> <para> A list of packages replaced by a package. @@ -7075,7 +8348,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" override. Here is an example: <literallayout class='monospaced'> - RREPLACES_${PN} = "other-package-being-replaced" + RREPLACES_${PN} = "<replaceable>other-package-being-replaced</replaceable>" </literallayout> </para> @@ -7087,7 +8360,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" Here is the general syntax to specify versions with the <filename>RREPLACES</filename> variable: <literallayout class='monospaced'> - RREPLACES_${PN} = "<package> (<operator> <version>)" + RREPLACES_${PN} = "<replaceable>package</replaceable> (<replaceable>operator</replaceable> <replaceable>version</replaceable>)" </literallayout> For <filename>operator</filename>, you can specify the following: @@ -7108,7 +8381,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-RSUGGESTS'><glossterm>RSUGGESTS</glossterm> + <glossentry id='var-RSUGGESTS'><glossterm><imagedata fileref="figures/define-generic.png" />RSUGGESTS</glossterm> + <info> + RSUGGESTS[doc] = "A list of additional packages that you can suggest for installation by the package manager at the time a package is installed. Not all package managers support this functionality." + </info> <glossdef> <para> A list of additional packages that you can suggest for @@ -7122,7 +8398,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" override. Here is an example: <literallayout class='monospaced'> - RSUGGESTS_${PN} = "useful-package another-package" + RSUGGESTS_${PN} = "<replaceable>useful-package</replaceable> <replaceable>another-package</replaceable>" </literallayout> </para> </glossdef> @@ -7132,7 +8408,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossdiv id='var-glossary-s'><title>S</title> - <glossentry id='var-S'><glossterm>S</glossterm> + <glossentry id='var-S'><glossterm><imagedata fileref="figures/define-generic.png" />S</glossterm> + <info> + S[doc] = "The location in the Build Directory where unpacked package source code resides." + </info> <glossdef> <para> The location in the @@ -7163,7 +8442,25 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-SANITY_TESTED_DISTROS'><glossterm>SANITY_TESTED_DISTROS</glossterm> + <glossentry id='var-SANITY_REQUIRED_UTILITIES'><glossterm><imagedata fileref="figures/define-generic.png" />SANITY_REQUIRED_UTILITIES</glossterm> + <info> + SANITY_REQUIRED_UTILITIES[doc] = "Specifies a list of command-line utilities that should be checked for during the initial sanity checking process when running BitBake." + </info> + <glossdef> + <para> + Specifies a list of command-line utilities that should be + checked for during the initial sanity checking process when + running BitBake. + If any of the utilities are not installed on the build host, + then BitBake immediately exits with an error. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-SANITY_TESTED_DISTROS'><glossterm><imagedata fileref="figures/define-generic.png" />SANITY_TESTED_DISTROS</glossterm> + <info> + SANITY_TESTED_DISTROS[doc] = "A list of the host distribution identifiers that the build system has been tested against." + </info> <glossdef> <para> A list of the host distribution identifiers that the @@ -7184,7 +8481,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-SDK_ARCH'><glossterm>SDK_ARCH</glossterm> + <glossentry id='var-SDK_ARCH'><glossterm><imagedata fileref="figures/define-generic.png" />SDK_ARCH</glossterm> + <info> + SDK_ARCH[doc] = "The target architecture for the SDK." + </info> <glossdef> <para> The target architecture for the SDK. @@ -7195,7 +8495,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-SDK_DEPLOY'><glossterm>SDK_DEPLOY</glossterm> + <glossentry id='var-SDK_DEPLOY'><glossterm><imagedata fileref="figures/define-generic.png" />SDK_DEPLOY</glossterm> + <info> + SDK_DEPLOY[doc] = "The directory set up and used by the populate_sdk_base to which the SDK is deployed." + </info> <glossdef> <para> The directory set up and used by the @@ -7210,7 +8513,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-SDK_DIR'><glossterm>SDK_DIR</glossterm> + <glossentry id='var-SDK_DIR'><glossterm><imagedata fileref="figures/define-generic.png" />SDK_DIR</glossterm> + <info> + SDK_DIR[doc] = "The parent directory used by the OpenEmbedded build system when creating SDK output." + </info> <glossdef> <para> The parent directory used by the OpenEmbedded build system @@ -7232,7 +8538,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-SDK_NAME'><glossterm>SDK_NAME</glossterm> + <glossentry id='var-SDK_NAME'><glossterm><imagedata fileref="figures/define-generic.png" />SDK_NAME</glossterm> + <info> + SDK_NAME[doc] = "The base name for SDK output files." + </info> <glossdef> <para> The base name for SDK output files. @@ -7251,7 +8560,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-SDK_OUTPUT'><glossterm>SDK_OUTPUT</glossterm> + <glossentry id='var-SDK_OUTPUT'><glossterm><imagedata fileref="figures/define-generic.png" />SDK_OUTPUT</glossterm> + <info> + SDK_OUTPUT[doc] = "The location used by the OpenEmbedded build system when creating SDK output." + </info> <glossdef> <para> The location used by the OpenEmbedded build system when @@ -7275,7 +8587,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-SDK_PACKAGE_ARCHS'><glossterm>SDK_PACKAGE_ARCHS</glossterm> + <glossentry id='var-SDK_PACKAGE_ARCHS'><glossterm><imagedata fileref="figures/define-generic.png" />SDK_PACKAGE_ARCHS</glossterm> + <info> + SDK_PACKAGE_ARCHS[doc] = "Specifies a list of architectures compatible with the SDK machine. This variable is set automatically and should not normally be hand-edited." + </info> <glossdef> <para> Specifies a list of architectures compatible with @@ -7291,20 +8606,26 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-SDKIMAGE_FEATURES'><glossterm>SDKIMAGE_FEATURES</glossterm> + <glossentry id='var-SDKIMAGE_FEATURES'><glossterm><imagedata fileref="figures/define-generic.png" />SDKIMAGE_FEATURES</glossterm> + <info> + SDKIMAGE_FEATURES[doc] = "Equivalent to IMAGE_FEATURES. However, this variable applies to the SDK generated from an image using the command 'bitbake -c populate_sdk imagename'." + </info> <glossdef> <para>Equivalent to <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>. However, this variable applies to the SDK generated from an image using the following command: <literallayout class='monospaced'> - $ bitbake -c populate_sdk imagename + $ bitbake -c populate_sdk <replaceable>imagename</replaceable> </literallayout> </para> </glossdef> </glossentry> - <glossentry id='var-SDKMACHINE'><glossterm>SDKMACHINE</glossterm> + <glossentry id='var-SDKMACHINE'><glossterm><imagedata fileref="figures/define-generic.png" />SDKMACHINE</glossterm> + <info> + SDKMACHINE[doc] = "Specifies the architecture (i.e. i686 or x86_64) for which to build SDK and ADT items." + </info> <glossdef> <para> The machine for which the Application Development Toolkit @@ -7333,7 +8654,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-SDKPATH'><glossterm>SDKPATH</glossterm> + <glossentry id='var-SDKPATH'><glossterm><imagedata fileref="figures/define-generic.png" />SDKPATH</glossterm> + <info> + SDKPATH[doc] = "Defines the path offered to the user for installation of the SDK that is generated by the OpenEmbedded build system." + </info> <glossdef> <para> Defines the path offered to the user for installation @@ -7347,14 +8671,20 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-SECTION'><glossterm>SECTION</glossterm> + <glossentry id='var-SECTION'><glossterm><imagedata fileref="figures/define-generic.png" />SECTION</glossterm> + <info> + SECTION[doc] = "The section in which packages should be categorized. Package management utilities can make use of this variable." + </info> <glossdef> <para>The section in which packages should be categorized. Package management utilities can make use of this variable.</para> </glossdef> </glossentry> - <glossentry id='var-SELECTED_OPTIMIZATION'><glossterm>SELECTED_OPTIMIZATION</glossterm> + <glossentry id='var-SELECTED_OPTIMIZATION'><glossterm><imagedata fileref="figures/define-generic.png" />SELECTED_OPTIMIZATION</glossterm> + <info> + SELECTED_OPTIMIZATION[doc] = "The variable takes the value of FULL_OPTIMIZATION unless DEBUG_BUILD = '1'. In this case, the value of DEBUG_OPTIMIZATION is used." + </info> <glossdef> <para> Specifies the optimization flags passed to the C compiler @@ -7375,7 +8705,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-SERIAL_CONSOLE'><glossterm>SERIAL_CONSOLE</glossterm> + <glossentry id='var-SERIAL_CONSOLE'><glossterm><imagedata fileref="figures/define-generic.png" />SERIAL_CONSOLE</glossterm> + <info> + SERIAL_CONSOLE[doc] = "The speed and device for the serial port used to attach the serial console. This variable is given to the kernel as the 'console' parameter. After booting occurs, getty is started on that port so remote login is possible." + </info> <glossdef> <para> Defines a serial console (TTY) to enable using getty. @@ -7396,7 +8729,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-SERIAL_CONSOLES'><glossterm>SERIAL_CONSOLES</glossterm> + <glossentry id='var-SERIAL_CONSOLES'><glossterm><imagedata fileref="figures/define-generic.png" />SERIAL_CONSOLES</glossterm> + <info> + SERIAL_CONSOLES[doc] = "Defines the serial consoles (TTYs) to enable using getty." + </info> <glossdef> <para> Defines the serial consoles (TTYs) to enable using getty. @@ -7410,7 +8746,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-SERIAL_CONSOLES_CHECK'><glossterm>SERIAL_CONSOLES_CHECK</glossterm> + <glossentry id='var-SERIAL_CONSOLES_CHECK'><glossterm><imagedata fileref="figures/define-generic.png" />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." + </info> <glossdef> <para> Similar to @@ -7423,7 +8762,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS'><glossterm>SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS</glossterm> + <glossentry id='var-SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS'><glossterm><imagedata fileref="figures/define-generic.png" />SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS</glossterm> + <info> + SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS[doc] = "A list of recipe dependencies that should not be used to determine signatures of tasks from one recipe when they depend on tasks from another recipe." + </info> <glossdef> <para> A list of recipe dependencies that should not be used to @@ -7451,7 +8793,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-SIGGEN_EXCLUDERECIPES_ABISAFE'><glossterm>SIGGEN_EXCLUDERECIPES_ABISAFE</glossterm> + <glossentry id='var-SIGGEN_EXCLUDERECIPES_ABISAFE'><glossterm><imagedata fileref="figures/define-generic.png" />SIGGEN_EXCLUDERECIPES_ABISAFE</glossterm> + <info> + SIGGEN_EXCLUDERECIPES_ABISAFE[doc] = "A list of recipes that are completely stable and will never change." + </info> <glossdef> <para> A list of recipes that are completely stable and will @@ -7471,7 +8816,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-SITEINFO_BITS'><glossterm>SITEINFO_BITS</glossterm> + <glossentry id='var-SITEINFO_BITS'><glossterm><imagedata fileref="figures/define-generic.png" />SITEINFO_BITS</glossterm> + <info> + SITEINFO_BITS[doc] = "Specifies the number of bits for the target system CPU." + </info> <glossdef> <para> Specifies the number of bits for the target system CPU. @@ -7480,7 +8828,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-SITEINFO_ENDIANNESS'><glossterm>SITEINFO_ENDIANNESS</glossterm> + <glossentry id='var-SITEINFO_ENDIANNESS'><glossterm><imagedata fileref="figures/define-generic.png" />SITEINFO_ENDIANNESS</glossterm> + <info> + SITEINFO_ENDIANNESS[doc] = "Specifies the endian byte order of the target system. The value should be either 'le' for 'little-endian' or 'be' for 'big-endian'." + </info> <glossdef> <para> Specifies the endian byte order of the target system. @@ -7489,7 +8840,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-SOC_FAMILY'><glossterm>SOC_FAMILY</glossterm> + <glossentry id='var-SOC_FAMILY'><glossterm><imagedata fileref="figures/define-generic.png" />SOC_FAMILY</glossterm> + <info> + SOC_FAMILY[doc] = "Groups together machines based upon the same family of SOC (System On Chip). You typically set this variable in a common .inc file that you include in the configuration files of all the machines." + </info> <glossdef> <para> Groups together machines based upon the same family @@ -7507,7 +8861,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-SOLIBS'><glossterm>SOLIBS</glossterm> + <glossentry id='var-SOLIBS'><glossterm><imagedata fileref="figures/define-generic.png" />SOLIBS</glossterm> + <info> + SOLIBS[doc] = "Defines the suffix for shared libraries used on the target platform." + </info> <glossdef> <para> Defines the suffix for shared libraries used on the @@ -7525,7 +8882,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-SOLIBSDEV'><glossterm>SOLIBSDEV</glossterm> + <glossentry id='var-SOLIBSDEV'><glossterm><imagedata fileref="figures/define-generic.png" />SOLIBSDEV</glossterm> + <info> + SOLIBSDEV[doc] = "Defines the suffix for the development symbolic link (symlink) for shared libraries on the target platform." + </info> <glossdef> <para> Defines the suffix for the development symbolic link @@ -7543,7 +8903,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-SOURCE_MIRROR_URL'><glossterm>SOURCE_MIRROR_URL</glossterm> + <glossentry id='var-SOURCE_MIRROR_URL'><glossterm><imagedata fileref="figures/define-generic.png" />SOURCE_MIRROR_URL</glossterm> + <info> + SOURCE_MIRROR_URL[doc] = "URL to source mirror that will be used before fetching from original SRC_URI." + </info> <glossdef> <para> Defines your own @@ -7570,7 +8933,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-SPDXLICENSEMAP'><glossterm>SPDXLICENSEMAP</glossterm> + <glossentry id='var-SPDXLICENSEMAP'><glossterm><imagedata fileref="figures/define-generic.png" />SPDXLICENSEMAP</glossterm> + <info> + SPDXLICENSEMAP[doc] = "Maps commonly used license names to their SPDX counterparts found in meta/files/common-licenses/." + </info> <glossdef> <para> Maps commonly used license names to their SPDX counterparts @@ -7588,7 +8954,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-SPECIAL_PKGSUFFIX'><glossterm>SPECIAL_PKGSUFFIX</glossterm> + <glossentry id='var-SPECIAL_PKGSUFFIX'><glossterm><imagedata fileref="figures/define-generic.png" />SPECIAL_PKGSUFFIX</glossterm> + <info> + SPECIAL_PKGSUFFIX[doc] = "A list of prefixes for PN used by the OpenEmbedded build system to create variants of recipes or packages. The list specifies the prefixes to strip off during certain circumstances such as the generation of the BPN variable." + </info> <glossdef> <para> A list of prefixes for <link linkend='var-PN'><filename>PN</filename></link> used by the @@ -7599,7 +8968,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-SRC_URI'><glossterm>SRC_URI</glossterm> + <glossentry id='var-SRC_URI'><glossterm><imagedata fileref="figures/define-generic.png" />SRC_URI</glossterm> + <info> + SRC_URI[doc] = "The list of source files - local or remote. This variable tells the OpenEmbedded build system what bits to pull in for the build and how to pull them in." + </info> <glossdef> <para>The list of source files - local or remote. This variable tells the OpenEmbedded build system which bits @@ -7664,8 +9036,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" an OSC (OpenSUSE Build service) revision control repository.</para></listitem> <listitem><para><emphasis><filename>repo://</filename> -</emphasis> Fetches files from a repo (Git) repository.</para></listitem> - <listitem><para><emphasis><filename>svk://</filename> -</emphasis> Fetches files from - an SVK revision control repository.</para></listitem> + <listitem><para><emphasis><filename>ccrc://</filename> -</emphasis> + Fetches files from a ClearCase repository. + </para></listitem> <listitem><para><emphasis><filename>http://</filename> -</emphasis> Fetches files from the Internet using <filename>http</filename>.</para></listitem> <listitem><para><emphasis><filename>https://</filename> -</emphasis> Fetches files @@ -7750,9 +9123,11 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'><glossterm>SRC_URI_OVERRIDES_PACKAGE_ARCH</glossterm> + <glossentry id='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'><glossterm><imagedata fileref="figures/define-generic.png" />SRC_URI_OVERRIDES_PACKAGE_ARCH</glossterm> + <info> + SRC_URI_OVERRIDES_PACKAGE_ARCH[doc] = "By default, the OpenEmbedded build system automatically detects whether SRC_URI contains files that are machine-specific. If so, the build system automatically changes PACKAGE_ARCH. Setting this variable to '0' disables this behavior." + </info> <glossdef> - <para></para> <para> By default, the OpenEmbedded build system automatically detects whether <filename><link linkend='var-SRC_URI'>SRC_URI</link></filename> @@ -7764,7 +9139,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-SRCDATE'><glossterm>SRCDATE</glossterm> + <glossentry id='var-SRCDATE'><glossterm><imagedata fileref="figures/define-generic.png" />SRCDATE</glossterm> + <info> + SRCDATE[doc] = "The date of the source code used to build the package. This variable applies only if the source was fetched from a Source Code Manager (SCM)." + </info> <glossdef> <para> The date of the source code used to build the package. @@ -7773,7 +9151,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-SRCPV'><glossterm>SRCPV</glossterm> + <glossentry id='var-SRCPV'><glossterm><imagedata fileref="figures/define-generic.png" />SRCPV</glossterm> + <info> + SRCPV[doc] = "Returns the version string of the current package. This string is used to help define the value of PV." + </info> <glossdef> <para> Returns the version string of the current package. @@ -7807,7 +9188,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-SRCREV'><glossterm>SRCREV</glossterm> + <glossentry id='var-SRCREV'><glossterm><imagedata fileref="figures/define-generic.png" />SRCREV</glossterm> + <info> + SRCREV[doc] = "The revision of the source code used to build the package. This variable applies to Subversion, Git, Mercurial and Bazaar only." + </info> <glossdef> <para> The revision of the source code used to build the package. @@ -7821,13 +9205,19 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-SSTATE_DIR'><glossterm>SSTATE_DIR</glossterm> + <glossentry id='var-SSTATE_DIR'><glossterm><imagedata fileref="figures/define-generic.png" />SSTATE_DIR</glossterm> + <info> + SSTATE_DIR[doc] = "The directory for the shared state cache." + </info> <glossdef> <para>The directory for the shared state cache.</para> </glossdef> </glossentry> - <glossentry id='var-SSTATE_MIRROR_ALLOW_NETWORK'><glossterm>SSTATE_MIRROR_ALLOW_NETWORK</glossterm> + <glossentry id='var-SSTATE_MIRROR_ALLOW_NETWORK'><glossterm><imagedata fileref="figures/define-generic.png" />SSTATE_MIRROR_ALLOW_NETWORK</glossterm> + <info> + SSTATE_MIRROR_ALLOW_NETWORK[doc] = "If set to "1", allows fetches from mirrors that are specified in SSTATE_MIRRORS to work even when fetching from the network has been disabled by setting BB_NO_NETWORK to "1"." + </info> <glossdef> <para> If set to "1", allows fetches from @@ -7846,7 +9236,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-SSTATE_MIRRORS'><glossterm>SSTATE_MIRRORS</glossterm> + <glossentry id='var-SSTATE_MIRRORS'><glossterm><imagedata fileref="figures/define-generic.png" />SSTATE_MIRRORS</glossterm> + <info> + SSTATE_MIRRORS[doc] = "Configures the OpenEmbedded build system to search other mirror locations for prebuilt cache data objects before building out the data. You can specify a filesystem directory or a remote URL such as HTTP or FTP." + </info> <glossdef> <para> Configures the OpenEmbedded build system to search other @@ -7877,14 +9270,17 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" directory structure. <literallayout class='monospaced'> SSTATE_MIRRORS ?= "\ - file://.* http://someserver.tld/share/sstate/PATH \n \ - file://.* file:///some/local/dir/sstate/PATH" + file://.* http://<replaceable>someserver</replaceable>.tld/share/sstate/PATH \n \ + file://.* file:///<replaceable>some-local-dir</replaceable>/sstate/PATH" </literallayout> </para> </glossdef> </glossentry> - <glossentry id='var-STAGING_BASE_LIBDIR_NATIVE'><glossterm>STAGING_BASE_LIBDIR_NATIVE</glossterm> + <glossentry id='var-STAGING_BASE_LIBDIR_NATIVE'><glossterm><imagedata fileref="figures/define-generic.png" />STAGING_BASE_LIBDIR_NATIVE</glossterm> + <info> + STAGING_BASE_LIBDIR_NATIVE[doc] = "Specifies the path to the /lib subdirectory of the sysroot directory for the build host." + </info> <glossdef> <para> Specifies the path to the <filename>/lib</filename> @@ -7894,7 +9290,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-STAGING_BASELIBDIR'><glossterm>STAGING_BASELIBDIR</glossterm> + <glossentry id='var-STAGING_BASELIBDIR'><glossterm><imagedata fileref="figures/define-generic.png" />STAGING_BASELIBDIR</glossterm> + <info> + STAGING_BASELIBDIR[doc] = "Specifies the path to the /lib subdirectory of the sysroot directory for the target for which the current recipe is being built (STAGING_DIR_HOST)." + </info> <glossdef> <para> Specifies the path to the <filename>/lib</filename> @@ -7905,7 +9304,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-STAGING_BINDIR'><glossterm>STAGING_BINDIR</glossterm> + <glossentry id='var-STAGING_BINDIR'><glossterm><imagedata fileref="figures/define-generic.png" />STAGING_BINDIR</glossterm> + <info> + STAGING_BINDIR[doc] = "Specifies the path to the /usr/bin subdirectory of the sysroot directory for the target for which the current recipe is being built (STAGING_DIR_HOST)." + </info> <glossdef> <para> Specifies the path to the @@ -7917,7 +9319,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-STAGING_BINDIR_CROSS'><glossterm>STAGING_BINDIR_CROSS</glossterm> + <glossentry id='var-STAGING_BINDIR_CROSS'><glossterm><imagedata fileref="figures/define-generic.png" />STAGING_BINDIR_CROSS</glossterm> + <info> + STAGING_BINDIR_CROSS[doc] = "Specifies the path to the directory containing binary configuration scripts. These scripts provide configuration information for other software that wants to make use of libraries or include files provided by the software associated with the script." + </info> <glossdef> <para> Specifies the path to the directory containing binary @@ -7939,7 +9344,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-STAGING_BINDIR_NATIVE'><glossterm>STAGING_BINDIR_NATIVE</glossterm> + <glossentry id='var-STAGING_BINDIR_NATIVE'><glossterm><imagedata fileref="figures/define-generic.png" />STAGING_BINDIR_NATIVE</glossterm> + <info> + STAGING_BINDIR_NATIVE[doc] = "Specifies the path to the /usr/bin subdirectory of the sysroot directory for the build host." + </info> <glossdef> <para> Specifies the path to the @@ -7949,7 +9357,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-STAGING_DATADIR'><glossterm>STAGING_DATADIR</glossterm> + <glossentry id='var-STAGING_DATADIR'><glossterm><imagedata fileref="figures/define-generic.png" />STAGING_DATADIR</glossterm> + <info> + STAGING_DATADIR[doc] = "Specifies the path to the /usr/share subdirectory of the sysroot directory for the target for which the current recipe is being built (STAGING_DIR_HOST)." + </info> <glossdef> <para> Specifies the path to the <filename>/usr/share</filename> @@ -7960,7 +9371,22 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-STAGING_DIR'><glossterm>STAGING_DIR</glossterm> + <glossentry id='var-STAGING_DATADIR_NATIVE'><glossterm><imagedata fileref="figures/define-generic.png" />STAGING_DATADIR_NATIVE</glossterm> + <info> + STAGING_DATADIR_NATIVE[doc] = "Specifies the path to the /usr/share subdirectory of the sysroot directory for the build host." + </info> + <glossdef> + <para> + Specifies the path to the <filename>/usr/share</filename> + subdirectory of the sysroot directory for the build host. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-STAGING_DIR'><glossterm><imagedata fileref="figures/define-generic.png" />STAGING_DIR</glossterm> + <info> + STAGING_DIR[doc] = "Specifies the path to the top-level sysroots directory (i.e. ${TMPDIR}/sysroots)." + </info> <glossdef> <para> Specifies the path to the top-level sysroots directory @@ -7981,7 +9407,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-STAGING_DIR_HOST'><glossterm>STAGING_DIR_HOST</glossterm> + <glossentry id='var-STAGING_DIR_HOST'><glossterm><imagedata fileref="figures/define-generic.png" />STAGING_DIR_HOST</glossterm> + <info> + STAGING_DIR_HOST[doc] = "Specifies the path to the primary sysroot directory for which the target is being built." + </info> <glossdef> <para> Specifies the path to the primary sysroot directory for @@ -8007,18 +9436,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-STAGING_DATADIR_NATIVE'><glossterm>STAGING_DATADIR_NATIVE</glossterm> - <glossdef> - <para> - Specifies the path to the <filename>/usr/share</filename> - subdirectory of the sysroot directory for the build host. - </para> - </glossdef> - </glossentry> - - - - <glossentry id='var-STAGING_DIR_NATIVE'><glossterm>STAGING_DIR_NATIVE</glossterm> + <glossentry id='var-STAGING_DIR_NATIVE'><glossterm><imagedata fileref="figures/define-generic.png" />STAGING_DIR_NATIVE</glossterm> + <info> + STAGING_DIR_NATIVE[doc] = "Specifies the path to the sysroot directory for the build host." + </info> <glossdef> <para> Specifies the path to the sysroot directory for the @@ -8027,7 +9448,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-STAGING_DIR_TARGET'><glossterm>STAGING_DIR_TARGET</glossterm> + <glossentry id='var-STAGING_DIR_TARGET'><glossterm><imagedata fileref="figures/define-generic.png" />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." + </info> <glossdef> <para> Specifies the path to the sysroot directory for the @@ -8051,7 +9475,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-STAGING_ETCDIR_NATIVE'><glossterm>STAGING_ETCDIR_NATIVE</glossterm> + <glossentry id='var-STAGING_ETCDIR_NATIVE'><glossterm><imagedata fileref="figures/define-generic.png" />STAGING_ETCDIR_NATIVE</glossterm> + <info> + STAGING_ETCDIR_NATIVE[doc] = "Specifies the path to the /etc subdirectory of the sysroot directory for the build host." + </info> <glossdef> <para> Specifies the path to the <filename>/etc</filename> @@ -8061,7 +9488,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-STAGING_EXECPREFIXDIR'><glossterm>STAGING_EXECPREFIXDIR</glossterm> + <glossentry id='var-STAGING_EXECPREFIXDIR'><glossterm><imagedata fileref="figures/define-generic.png" />STAGING_EXECPREFIXDIR</glossterm> + <info> + STAGING_EXECPREFIXDIR[doc] = "Specifies the path to the /usr subdirectory of the sysroot directory for the target for which the current recipe is being built (STAGING_DIR_HOST)." + </info> <glossdef> <para> Specifies the path to the <filename>/usr</filename> @@ -8072,7 +9502,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-STAGING_INCDIR'><glossterm>STAGING_INCDIR</glossterm> + <glossentry id='var-STAGING_INCDIR'><glossterm><imagedata fileref="figures/define-generic.png" />STAGING_INCDIR</glossterm> + <info> + STAGING_INCDIR[doc] = "Specifies the path to the /usr/include subdirectory of the sysroot directory for the target for which the current recipe being built (STAGING_DIR_HOST)." + </info> <glossdef> <para> Specifies the path to the @@ -8084,7 +9517,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-STAGING_INCDIR_NATIVE'><glossterm>STAGING_INCDIR_NATIVE</glossterm> + <glossentry id='var-STAGING_INCDIR_NATIVE'><glossterm><imagedata fileref="figures/define-generic.png" />STAGING_INCDIR_NATIVE</glossterm> + <info> + STAGING_INCDIR_NATIVE[doc] = "Specifies the path to the /usr/include subdirectory of the sysroot directory for the build host." + </info> <glossdef> <para> Specifies the path to the <filename>/usr/include</filename> @@ -8093,36 +9529,48 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-STAGING_LIBDIR'><glossterm>STAGING_LIBDIR</glossterm> + <glossentry id='var-STAGING_KERNEL_DIR'><glossterm><imagedata fileref="figures/define-generic.png" />STAGING_KERNEL_DIR</glossterm> + <info> + STAGING_KERNEL_DIR[doc] = "The directory with kernel headers that are required to build out-of-tree modules." + </info> <glossdef> <para> - Specifies the path to the <filename>/usr/lib</filename> - subdirectory of the sysroot directory for the target for - which the current recipe is being built - (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>). + The directory with kernel headers that are required to build out-of-tree + modules. </para> </glossdef> </glossentry> - <glossentry id='var-STAGING_LIBDIR_NATIVE'><glossterm>STAGING_LIBDIR_NATIVE</glossterm> + <glossentry id='var-STAGING_LIBDIR'><glossterm><imagedata fileref="figures/define-generic.png" />STAGING_LIBDIR</glossterm> + <info> + STAGING_LIBDIR[doc] = "Specifies the path to the /usr/lib subdirectory of the sysroot directory for the target for which the current recipe is being built (STAGING_DIR_HOST)." + </info> <glossdef> <para> Specifies the path to the <filename>/usr/lib</filename> - subdirectory of the sysroot directory for the build host. + subdirectory of the sysroot directory for the target for + which the current recipe is being built + (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>). </para> </glossdef> </glossentry> - <glossentry id='var-STAGING_KERNEL_DIR'><glossterm>STAGING_KERNEL_DIR</glossterm> + <glossentry id='var-STAGING_LIBDIR_NATIVE'><glossterm><imagedata fileref="figures/define-generic.png" />STAGING_LIBDIR_NATIVE</glossterm> + <info> + STAGING_LIBDIR_NATIVE[doc] = "Specifies the path to the /usr/lib subdirectory of the sysroot directory for the build host." + </info> <glossdef> <para> - The directory with kernel headers that are required to build out-of-tree - modules. + Specifies the path to the <filename>/usr/lib</filename> + subdirectory of the sysroot directory for the build host. </para> </glossdef> </glossentry> - <glossentry id='var-STAMP'><glossterm>STAMP</glossterm> + <glossentry id='var-STAMP'><glossterm><imagedata fileref="figures/define-generic.png" />STAMP</glossterm> + <info> + STAMP[doc] = "Specifies the base path used to create recipe stamp files. The path to an actual stamp file is constructed by evaluating this string and then appending additional information." + </info> <glossdef> <para> Specifies the base path used to create recipe stamp files. @@ -8145,7 +9593,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-STAMPS_DIR'><glossterm>STAMPS_DIR</glossterm> + <glossentry id='var-STAMPS_DIR'><glossterm><imagedata fileref="figures/define-generic.png" />STAMPS_DIR</glossterm> + <info> + STAMPS_DIR[doc] = "Specifies the base directory in which the OpenEmbedded build system places stamps." + </info> <glossdef> <para> Specifies the base directory in which the OpenEmbedded @@ -8156,7 +9607,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-SUMMARY'><glossterm>SUMMARY</glossterm> + <glossentry id='var-SUMMARY'><glossterm><imagedata fileref="figures/define-generic.png" />SUMMARY</glossterm> + <info> + SUMMARY[doc] = "The short (80 characters or less) summary of the binary package for packaging systems such as opkg, rpm or dpkg. By default, SUMMARY is used to define the DESCRIPTION variable if DESCRIPTION is not set in the recipe." + </info> <glossdef> <para>The short (72 characters or less) summary of the binary package for packaging systems such as <filename>opkg</filename>, <filename>rpm</filename> or @@ -8169,7 +9623,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-SYSLINUX_DEFAULT_CONSOLE'><glossterm>SYSLINUX_DEFAULT_CONSOLE</glossterm> + <glossentry id='var-SYSLINUX_DEFAULT_CONSOLE'><glossterm><imagedata fileref="figures/define-generic.png" />SYSLINUX_DEFAULT_CONSOLE</glossterm> + <info> + SYSLINUX_DEFAULT_CONSOLE[doc] = "Specifies the kernel boot default console." + </info> <glossdef> <para> Specifies the kernel boot default console. @@ -8190,7 +9647,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-SYSLINUX_OPTS'><glossterm>SYSLINUX_OPTS</glossterm> + <glossentry id='var-SYSLINUX_OPTS'><glossterm><imagedata fileref="figures/define-generic.png" />SYSLINUX_OPTS</glossterm> + <info> + SYSLINUX_OPTS[doc] = "Lists additional options to add to the syslinux file." + </info> <glossdef> <para> Lists additional options to add to the syslinux file. @@ -8207,7 +9667,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-SYSLINUX_SERIAL'><glossterm>SYSLINUX_SERIAL</glossterm> + <glossentry id='var-SYSLINUX_SERIAL'><glossterm><imagedata fileref="figures/define-generic.png" />SYSLINUX_SERIAL</glossterm> + <info> + SYSLINUX_SERIAL[doc] = "Specifies the alternate serial port or turns it off." + </info> <glossdef> <para> Specifies the alternate serial port or turns it off. @@ -8223,7 +9686,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-SYSLINUX_SPLASH'><glossterm>SYSLINUX_SPLASH</glossterm> + <glossentry id='var-SYSLINUX_SPLASH'><glossterm><imagedata fileref="figures/define-generic.png" />SYSLINUX_SPLASH</glossterm> + <info> + SYSLINUX_SPLASH[doc] = "An .LSS file used as the background for the VGA boot menu when you are using the boot menu." + </info> <glossdef> <para> An <filename>.LSS</filename> file used as the background @@ -8240,7 +9706,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-SYSLINUX_SERIAL_TTY'><glossterm>SYSLINUX_SERIAL_TTY</glossterm> + <glossentry id='var-SYSLINUX_SERIAL_TTY'><glossterm><imagedata fileref="figures/define-generic.png" />SYSLINUX_SERIAL_TTY</glossterm> + <info> + SYSLINUX_SERIAL_TTY[doc] = "Specifies the alternate console=tty... kernel boot argument." + </info> <glossdef> <para> Specifies the alternate console=tty... kernel boot argument. @@ -8255,7 +9724,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-SYSROOT_PREPROCESS_FUNCS'><glossterm>SYSROOT_PREPROCESS_FUNCS</glossterm> + <glossentry id='var-SYSROOT_PREPROCESS_FUNCS'><glossterm><imagedata fileref="figures/define-generic.png" />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." + </info> <glossdef> <para> A list of functions to execute after files are staged into @@ -8267,10 +9739,13 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-SYSTEMD_AUTO_ENABLE'><glossterm>SYSTEMD_AUTO_ENABLE</glossterm> + <glossentry id='var-SYSTEMD_AUTO_ENABLE'><glossterm><imagedata fileref="figures/define-generic.png" />SYSTEMD_AUTO_ENABLE</glossterm> + <info> + SYSTEMD_AUTO_ENABLE[doc] = "For recipes that inherit the systemd class, this variable specifies whether the service you have specified in SYSTEMD_SERVICE should be started automatically or not." + </info> <glossdef> <para> - For recipes that inherit the + When inheriting the <link linkend='ref-classes-systemd'><filename>systemd</filename></link> class, this variable specifies whether the service you have specified in @@ -8290,10 +9765,13 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-SYSTEMD_PACKAGES'><glossterm>SYSTEMD_PACKAGES</glossterm> + <glossentry id='var-SYSTEMD_PACKAGES'><glossterm><imagedata fileref="figures/define-generic.png" />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." + </info> <glossdef> <para> - For recipes that inherit the + When inheriting the <link linkend='ref-classes-systemd'><filename>systemd</filename></link> class, this variable locates the systemd unit files when they are not found in the main recipe's package. @@ -8313,10 +9791,13 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-SYSTEMD_SERVICE'><glossterm>SYSTEMD_SERVICE</glossterm> + <glossentry id='var-SYSTEMD_SERVICE'><glossterm><imagedata fileref="figures/define-generic.png" />SYSTEMD_SERVICE</glossterm> + <info> + SYSTEMD_SERVICE[doc] = "For recipes that inherit the systemd class, this variable specifies the systemd service name for a package." + </info> <glossdef> <para> - For recipes that inherit the + When inheriting the <link linkend='ref-classes-systemd'><filename>systemd</filename></link> class, this variable specifies the systemd service name for a package. @@ -8334,7 +9815,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-SYSVINIT_ENABLED_GETTYS'><glossterm>SYSVINIT_ENABLED_GETTYS</glossterm> + <glossentry id='var-SYSVINIT_ENABLED_GETTYS'><glossterm><imagedata fileref="figures/define-generic.png" />SYSVINIT_ENABLED_GETTYS</glossterm> + <info> + SYSVINIT_ENABLED_GETTYS[doc] = "Specifies which virtual terminals should be running a getty, the default is '1'." + </info> <glossdef> <para> When using @@ -8359,7 +9843,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossdiv id='var-glossary-t'><title>T</title> - <glossentry id='var-T'><glossterm>T</glossterm> + <glossentry id='var-T'><glossterm><imagedata fileref="figures/define-generic.png" />T</glossterm> + <info> + T[doc] = "This variable points to a directory were BitBake places temporary files, which consist mostly of task logs and scripts, when building a particular recipe." + </info> <glossdef> <para>This variable points to a directory were BitBake places temporary files, which consist mostly of task logs and @@ -8380,7 +9867,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-TARGET_ARCH'><glossterm>TARGET_ARCH</glossterm> + <glossentry id='var-TARGET_ARCH'><glossterm><imagedata fileref="figures/define-generic.png" />TARGET_ARCH</glossterm> + <info> + TARGET_ARCH[doc] = "The architecture of the device being built. The OpenEmbedded build system supports the following architectures: arm, mips, ppc, x86, x86-64." + </info> <glossdef> <para> The target machine's architecture. @@ -8406,7 +9896,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-TARGET_AS_ARCH'><glossterm>TARGET_AS_ARCH</glossterm> + <glossentry id='var-TARGET_AS_ARCH'><glossterm><imagedata fileref="figures/define-generic.png" />TARGET_AS_ARCH</glossterm> + <info> + TARGET_AS_ARCH[doc] = "Specifies architecture-specific assembler flags for the target system." + </info> <glossdef> <para> Specifies architecture-specific assembler flags for the @@ -8422,7 +9915,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-TARGET_CC_ARCH'><glossterm>TARGET_CC_ARCH</glossterm> + <glossentry id='var-TARGET_CC_ARCH'><glossterm><imagedata fileref="figures/define-generic.png" />TARGET_CC_ARCH</glossterm> + <info> + TARGET_CC_ARCH[doc] = "Specifies architecture-specific C compiler flags for the target system." + </info> <glossdef> <para> Specifies architecture-specific C compiler flags for the @@ -8442,7 +9938,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-TARGET_CC_KERNEL_ARCH'><glossterm>TARGET_CC_KERNEL_ARCH</glossterm> + <glossentry id='var-TARGET_CC_KERNEL_ARCH'><glossterm><imagedata fileref="figures/define-generic.png" />TARGET_CC_KERNEL_ARCH</glossterm> + <info> + TARGET_CC_KERNEL_ARCH[doc] = "This is a specific kernel compiler flag for a CPU or Application Binary Interface (ABI) tune." + </info> <glossdef> <para> This is a specific kernel compiler flag for a CPU or @@ -8463,7 +9962,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-TARGET_CFLAGS'><glossterm>TARGET_CFLAGS</glossterm> + <glossentry id='var-TARGET_CFLAGS'><glossterm><imagedata fileref="figures/define-generic.png" />TARGET_CFLAGS</glossterm> + <info> + TARGET_CFLAGS[doc] = "Flags passed to the C compiler for the target system. This variable evaluates to the same as CFLAGS." + </info> <glossdef> <para> Specifies the flags to pass to the C compiler when building @@ -8485,7 +9987,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-TARGET_CPPFLAGS'><glossterm>TARGET_CPPFLAGS</glossterm> + <glossentry id='var-TARGET_CPPFLAGS'><glossterm><imagedata fileref="figures/define-generic.png" />TARGET_CPPFLAGS</glossterm> + <info> + TARGET_CPPFLAGS[doc] = "Specifies the flags to pass to the C pre-processor (i.e. to both the C and the C++ compilers) when building for the target." + </info> <glossdef> <para> Specifies the flags to pass to the C pre-processor @@ -8508,7 +10013,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-TARGET_CXXFLAGS'><glossterm>TARGET_CXXFLAGS</glossterm> + <glossentry id='var-TARGET_CXXFLAGS'><glossterm><imagedata fileref="figures/define-generic.png" />TARGET_CXXFLAGS</glossterm> + <info> + TARGET_CXXFLAGS[doc] = "Specifies the flags to pass to the C++ compiler when building for the target." + </info> <glossdef> <para> Specifies the flags to pass to the C++ compiler when @@ -8530,7 +10038,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-TARGET_FPU'><glossterm>TARGET_FPU</glossterm> + <glossentry id='var-TARGET_FPU'><glossterm><imagedata fileref="figures/define-generic.png" />TARGET_FPU</glossterm> + <info> + TARGET_FPU[doc] = "Specifies the method for handling FPU code. For FPU-less targets, which include most ARM CPUs, the variable must be set to 'soft'. If not, the kernel emulation gets used, which results in a performance penalty." + </info> <glossdef> <para>Specifies the method for handling FPU code. For FPU-less targets, which include most ARM CPUs, the variable must be @@ -8539,7 +10050,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-TARGET_LD_ARCH'><glossterm>TARGET_LD_ARCH</glossterm> + <glossentry id='var-TARGET_LD_ARCH'><glossterm><imagedata fileref="figures/define-generic.png" />TARGET_LD_ARCH</glossterm> + <info> + TARGET_LD_ARCH[doc] = "Specifies architecture-specific linker flags for the target system." + </info> <glossdef> <para> Specifies architecture-specific linker flags for the @@ -8555,7 +10069,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-TARGET_LDFLAGS'><glossterm>TARGET_LDFLAGS</glossterm> + <glossentry id='var-TARGET_LDFLAGS'><glossterm><imagedata fileref="figures/define-generic.png" />TARGET_LDFLAGS</glossterm> + <info> + TARGET_LDFLAGS[doc] = "Specifies the flags to pass to the linker when building for the target." + </info> <glossdef> <para> Specifies the flags to pass to the linker when building @@ -8577,7 +10094,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-TARGET_OS'><glossterm>TARGET_OS</glossterm> + <glossentry id='var-TARGET_OS'><glossterm><imagedata fileref="figures/define-generic.png" />TARGET_OS</glossterm> + <info> + TARGET_OS[doc] = "Specifies the target's operating system." + </info> <glossdef> <para>Specifies the target's operating system. The variable can be set to "linux" for <filename>eglibc</filename>-based systems and @@ -8587,7 +10107,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-TCLIBC'><glossterm>TCLIBC</glossterm> + <glossentry id='var-TCLIBC'><glossterm><imagedata fileref="figures/define-generic.png" />TCLIBC</glossterm> + <info> + TCLIBC[doc] = "Specifies GNU standard C library (libc) variant to use during the build process. You can select 'glibc' or 'uclibc'." + </info> <glossdef> <para> Specifies the GNU standard C library (<filename>libc</filename>) @@ -8605,7 +10128,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-TCMODE'><glossterm>TCMODE</glossterm> + <glossentry id='var-TCMODE'><glossterm><imagedata fileref="figures/define-generic.png" />TCMODE</glossterm> + <info> + TCMODE[doc] = "Enables an external toolchain (where provided by an additional layer) if set to a value other than 'default'." + </info> <glossdef> <para> Specifies the toolchain selector. @@ -8663,7 +10189,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-TEST_EXPORT_DIR'><glossterm>TEST_EXPORT_DIR</glossterm> + <glossentry id='var-TEST_EXPORT_DIR'><glossterm><imagedata fileref="figures/define-generic.png" />TEST_EXPORT_DIR</glossterm> + <info> + TEST_EXPORT_DIR[doc] = "The location the OpenEmbedded build system uses to export tests when the TEST_EXPORT_ONLY variable is set to "1"." + </info> <glossdef> <para> The location the OpenEmbedded build system uses to export @@ -8679,7 +10208,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-TEST_EXPORT_ONLY'><glossterm>TEST_EXPORT_ONLY</glossterm> + <glossentry id='var-TEST_EXPORT_ONLY'><glossterm><imagedata fileref="figures/define-generic.png" />TEST_EXPORT_ONLY</glossterm> + <info> + TEST_EXPORT_ONLY[doc] = "Specifies to export the tests only. Set this variable to "1" if you do not want to run the tests but you want them to be exported in a manner that you to run them outside of the build system." + </info> <glossdef> <para> Specifies to export the tests only. @@ -8690,7 +10222,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-TEST_IMAGE'><glossterm>TEST_IMAGE</glossterm> + <glossentry id='var-TEST_IMAGE'><glossterm><imagedata fileref="figures/define-generic.png" />TEST_IMAGE</glossterm> + <info> + TEST_IMAGE[doc] = "Enables test booting of virtual machine images under the QEMU emulator after any root filesystems are created and runs tests against those images." + </info> <glossdef> <para> Automatically runs the series of automated tests for @@ -8720,7 +10255,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-TEST_LOG_DIR'><glossterm>TEST_LOG_DIR</glossterm> + <glossentry id='var-TEST_LOG_DIR'><glossterm><imagedata fileref="figures/define-generic.png" />TEST_LOG_DIR</glossterm> + <info> + TEST_LOG_DIR[doc] = "Holds the SSH log and the boot log for QEMU machines. The <filename>TEST_LOG_DIR</filename> variable defaults to "${WORKDIR}/testimage"." + </info> <glossdef> <para> Holds the SSH log and the boot log for QEMU machines. @@ -8735,7 +10273,47 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-TEST_QEMUBOOT_TIMEOUT'><glossterm>TEST_QEMUBOOT_TIMEOUT</glossterm> + <glossentry id='var-TEST_POWERCONTROL_CMD'><glossterm><imagedata fileref="figures/define-generic.png" />TEST_POWERCONTROL_CMD</glossterm> + <info> + TEST_POWERCONTROL_CMD[doc] = "For automated hardware testing, specifies the command to use to control the power of the target machine under test" + </info> + <glossdef> + <para> + For automated hardware testing, specifies the command to + use to control the power of the target machine under test. + Typically, this command would point to a script that + performs the appropriate action (e.g. interacting + with a web-enabled power strip). + The specified command should expect to receive as the last + argument "off", "on" or "cycle" specifying to power off, + on, or cycle (power off and then power on) the device, + respectively. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-TEST_POWERCONTROL_EXTRA_ARGS'><glossterm><imagedata fileref="figures/define-generic.png" />TEST_POWERCONTROL_EXTRA_ARGS</glossterm> + <info> + TEST_POWERCONTROL_EXTRA_ARGS[doc] = "For automated hardware testing, specifies additional arguments to pass through to the command specified in TEST_POWERCONTROL_CMD" + </info> + <glossdef> + <para> + For automated hardware testing, specifies additional + arguments to pass through to the command specified in + <link linkend='var-TEST_POWERCONTROL_CMD'><filename>TEST_POWERCONTROL_CMD</filename></link>. + Setting <filename>TEST_POWERCONTROL_EXTRA_ARGS</filename> + is optional. + You can use it if you wish, for example, to separate the + machine-specific and non-machine-specific parts of the + arguments. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-TEST_QEMUBOOT_TIMEOUT'><glossterm><imagedata fileref="figures/define-generic.png" />TEST_QEMUBOOT_TIMEOUT</glossterm> + <info> + TEST_QEMUBOOT_TIMEOUT[doc] = "The time in seconds allowed for an image to boot before automated runtime tests begin to run against an image." + </info> <glossdef> <para> The time in seconds allowed for an image to boot before @@ -8755,7 +10333,53 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-TEST_SERVER_IP'><glossterm>TEST_SERVER_IP</glossterm> + <glossentry id='var-TEST_SERIALCONTROL_CMD'><glossterm><imagedata fileref="figures/define-generic.png" />TEST_SERIALCONTROL_CMD</glossterm> + <info> + TEST_SERIALCONTROL_CMD[doc] = "For automated hardware testing, specifies the command to use to connect to the serial console of the target machine under test." + </info> + <glossdef> + <para> + For automated hardware testing, specifies the command + to use to connect to the serial console of the target + machine under test. + This command simply needs to connect to the serial console + and forward that connection to standard input and output + as any normal terminal program does. + </para> + + <para> + For example, to use the Picocom terminal program on + serial device <filename>/dev/ttyUSB0</filename> at + 115200bps, you would set the variable as follows: + <literallayout class='monospaced'> + TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200" + </literallayout> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-TEST_SERIALCONTROL_EXTRA_ARGS'><glossterm><imagedata fileref="figures/define-generic.png" />TEST_SERIALCONTROL_EXTRA_ARGS</glossterm> + <info> + TEST_SERIALCONTROL_EXTRA_ARGS[doc] = "For automated hardware testing, specifies additional arguments to pass through to the command specified in TEST_SERIALCONTROL_CMD." + </info> + <glossdef> + <para> + For automated hardware testing, specifies additional + arguments to pass through to the command specified in + <link linkend='var-TEST_SERIALCONTROL_CMD'><filename>TEST_SERIALCONTROL_CMD</filename></link>. + Setting <filename>TEST_SERIALCONTROL_EXTRA_ARGS</filename> + is optional. + You can use it if you wish, for example, to separate the + machine-specific and non-machine-specific parts of the + command. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-TEST_SERVER_IP'><glossterm><imagedata fileref="figures/define-generic.png" />TEST_SERVER_IP</glossterm> + <info> + TEST_SERVER_IP[doc] = "The IP address of the build machine (host machine). This IP address is usually automatically detected." + </info> <glossdef> <para> The IP address of the build machine (host machine). @@ -8773,7 +10397,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-TEST_TARGET'><glossterm>TEST_TARGET</glossterm> + <glossentry id='var-TEST_TARGET'><glossterm><imagedata fileref="figures/define-generic.png" />TEST_TARGET</glossterm> + <info> + TEST_TARGET[doc] = "For automated runtime testing, specifies the method of deploying the image and running tests on the target machine." + </info> <glossdef> <para> Specifies the target controller to use when running tests @@ -8838,7 +10465,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-TEST_TARGET_IP'><glossterm>TEST_TARGET_IP</glossterm> + <glossentry id='var-TEST_TARGET_IP'><glossterm><imagedata fileref="figures/define-generic.png" />TEST_TARGET_IP</glossterm> + <info> + TEST_TARGET_IP[doc] = "The IP address of your hardware under test." + </info> <glossdef> <para> The IP address of your hardware under test. @@ -8864,7 +10494,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-TEST_SUITES'><glossterm>TEST_SUITES</glossterm> + <glossentry id='var-TEST_SUITES'><glossterm><imagedata fileref="figures/define-generic.png" />TEST_SUITES</glossterm> + <info> + TEST_SUITES[doc] = "An ordered list of tests (modules) to run against an image when performing automated runtime testing." + </info> <glossdef> <para> An ordered list of tests (modules) to run against @@ -8884,7 +10517,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" You can add your own tests to the list of tests by appending <filename>TEST_SUITES</filename> as follows: <literallayout class='monospaced'> - TEST_SUITES_append = " mytest" + TEST_SUITES_append = " <replaceable>mytest</replaceable>" </literallayout> Alternatively, you can provide the "auto" option to have all applicable tests run against the image. @@ -8919,7 +10552,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-THISDIR'><glossterm>THISDIR</glossterm> + <glossentry id='var-THISDIR'><glossterm><imagedata fileref="figures/define-generic.png" />THISDIR</glossterm> + <info> + THISDIR[doc] = "The directory in which the file BitBake is currently parsing is located." + </info> <glossdef> <para> The directory in which the file BitBake is currently @@ -8929,7 +10565,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-TMPDIR'><glossterm>TMPDIR</glossterm> + <glossentry id='var-TMPDIR'><glossterm><imagedata fileref="figures/define-generic.png" />TMPDIR</glossterm> + <info> + TMPDIR[doc] = "The temporary directory the OpenEmbedded build system uses when it does its work building images. By default, the TMPDIR variable is named tmp within the Build Directory." + </info> <glossdef> <para> This variable is the base directory the OpenEmbedded @@ -8967,7 +10606,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-TOOLCHAIN_HOST_TASK'><glossterm>TOOLCHAIN_HOST_TASK</glossterm> + <glossentry id='var-TOOLCHAIN_HOST_TASK'><glossterm><imagedata fileref="figures/define-generic.png" />TOOLCHAIN_HOST_TASK</glossterm> + <info> + TOOLCHAIN_HOST_TASK[doc] = "This variable lists packages the OpenEmbedded build system uses when building an SDK, which contains a cross-development environment." + </info> <glossdef> <para> This variable lists packages the OpenEmbedded build system @@ -8997,7 +10639,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-TOOLCHAIN_TARGET_TASK'><glossterm>TOOLCHAIN_TARGET_TASK</glossterm> + <glossentry id='var-TOOLCHAIN_TARGET_TASK'><glossterm><imagedata fileref="figures/define-generic.png" />TOOLCHAIN_TARGET_TASK</glossterm> + <info> + TOOLCHAIN_TARGET_TASK[doc] = "This variable lists packages the OpenEmbedded build system uses when it creates the target part of an SDK, which includes libraries and headers." + </info> <glossdef> <para> This variable lists packages the OpenEmbedded build system @@ -9019,7 +10664,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-TOPDIR'><glossterm>TOPDIR</glossterm> + <glossentry id='var-TOPDIR'><glossterm><imagedata fileref="figures/define-generic.png" />TOPDIR</glossterm> + <info> + TOPDIR[doc] = "The Build Directory. BitBake automatically sets this variable. The OpenEmbedded build system uses the Build Directory when building images." + </info> <glossdef> <para> The top-level @@ -9033,7 +10681,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-TRANSLATED_TARGET_ARCH'><glossterm>TRANSLATED_TARGET_ARCH</glossterm> + <glossentry id='var-TRANSLATED_TARGET_ARCH'><glossterm><imagedata fileref="figures/define-generic.png" />TRANSLATED_TARGET_ARCH</glossterm> + <info> + TRANSLATED_TARGET_ARCH[doc] = "A sanitized version of TARGET_ARCH. This variable is used where the architecture is needed in a value where underscores are not allowed." + </info> <glossdef> <para> A sanitized version of @@ -9051,7 +10702,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-TUNE_ARCH'><glossterm>TUNE_ARCH</glossterm> + <glossentry id='var-TUNE_ARCH'><glossterm><imagedata fileref="figures/define-generic.png" />TUNE_ARCH</glossterm> + <info> + TUNE_ARCH[doc] = "The GNU canonical architecture for a specific architecture (i.e. arm, armeb, mips, mips64, and so forth)." + </info> <glossdef> <para> The GNU canonical architecture for a specific architecture @@ -9106,7 +10760,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-TUNE_ASARGS'><glossterm>TUNE_ASARGS</glossterm> + <glossentry id='var-TUNE_ASARGS'><glossterm><imagedata fileref="figures/define-generic.png" />TUNE_ASARGS</glossterm> + <info> + TUNE_ASARGS[doc] = "Specifies architecture-specific assembler flags for the target system." + </info> <glossdef> <para> Specifies architecture-specific assembler flags for @@ -9115,7 +10772,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <filename>TUNE_ASARGS</filename> is set using the tune include files, which are typically under <filename>meta/conf/machine/include/</filename> and are - influenced through <filename>TUNE_FEATURES</filename>. + influenced through + <link linkend='var-TUNE_FEATURES'><filename>TUNE_FEATURES</filename></link>. For example, the <filename>meta/conf/machine/include/x86/arch-x86.inc</filename> file defines the flags for the x86 architecture as follows: @@ -9123,14 +10781,19 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" TUNE_ASARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-x32", "", d)}" </literallayout> <note> - Board Support Packages (BSPs) can supply their own - set of flags. + Board Support Packages (BSPs) select the tune. + The selected tune, in turn, affects the tune variables + themselves (i.e. the tune can supply its own + set of flags). </note> </para> </glossdef> </glossentry> - <glossentry id='var-TUNE_CCARGS'><glossterm>TUNE_CCARGS</glossterm> + <glossentry id='var-TUNE_CCARGS'><glossterm><imagedata fileref="figures/define-generic.png" />TUNE_CCARGS</glossterm> + <info> + TUNE_CCARGS[doc] = "Specifies architecture-specific C compiler flags for the target system." + </info> <glossdef> <para> Specifies architecture-specific C compiler flags for @@ -9139,16 +10802,22 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <filename>TUNE_CCARGS</filename> is set using the tune include files, which are typically under <filename>meta/conf/machine/include/</filename> and are - influenced through <filename>TUNE_FEATURES</filename>. + influenced through + <link linkend='var-TUNE_FEATURES'><filename>TUNE_FEATURES</filename></link>. <note> - Board Support Packages (BSPs) can supply their own - set of flags. + Board Support Packages (BSPs) select the tune. + The selected tune, in turn, affects the tune variables + themselves (i.e. the tune can supply its own + set of flags). </note> </para> </glossdef> </glossentry> - <glossentry id='var-TUNE_LDARGS'><glossterm>TUNE_LDARGS</glossterm> + <glossentry id='var-TUNE_LDARGS'><glossterm><imagedata fileref="figures/define-generic.png" />TUNE_LDARGS</glossterm> + <info> + TUNE_LDARGS[doc] = "Specifies architecture-specific linker flags for the target system." + </info> <glossdef> <para> Specifies architecture-specific linker flags for @@ -9157,7 +10826,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <filename>TUNE_LDARGS</filename> is set using the tune include files, which are typically under <filename>meta/conf/machine/include/</filename> and are - influenced through <filename>TUNE_FEATURES</filename>. + influenced through + <link linkend='var-TUNE_FEATURES'><filename>TUNE_FEATURES</filename></link>. For example, the <filename>meta/conf/machine/include/x86/arch-x86.inc</filename> file defines the flags for the x86 architecture as follows: @@ -9165,14 +10835,19 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" TUNE_LDARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-m elf32_x86_64", "", d)}" </literallayout> <note> - Board Support Packages (BSPs) can supply their own - set of flags. + Board Support Packages (BSPs) select the tune. + The selected tune, in turn, affects the tune variables + themselves (i.e. the tune can supply its own + set of flags). </note> </para> </glossdef> </glossentry> - <glossentry id='var-TUNE_FEATURES'><glossterm>TUNE_FEATURES</glossterm> + <glossentry id='var-TUNE_FEATURES'><glossterm><imagedata fileref="figures/define-generic.png" />TUNE_FEATURES</glossterm> + <info> + TUNE_FEATURES[doc] = "Features used to "tune" a compiler for optimal use given a specific processor." + </info> <glossdef> <para> Features used to "tune" a compiler for optimal use @@ -9202,22 +10877,20 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-TUNE_PKGARCH'><glossterm>TUNE_PKGARCH</glossterm> + <glossentry id='var-TUNE_PKGARCH'><glossterm><imagedata fileref="figures/define-generic.png" />TUNE_PKGARCH</glossterm> + <info> + TUNE_PKGARCH[doc] = "The package architecture understood by the packaging system to define the architecture, ABI, and tuning of output packages." + </info> <glossdef> <para> The package architecture understood by the packaging system to define the architecture, ABI, and tuning of output packages. - </para> - </glossdef> - </glossentry> - - <glossentry id='var-TUNE_PKGARCH_tune'><glossterm>TUNE_PKGARCH_tune</glossterm> - <glossdef> - <para> - The CPU or Application Binary Interface (ABI) specific - tuning of the - <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>. + The specific tune is defined using the "_tune" override + as follows: + <literallayout class='monospaced'> + TUNE_PKGARCH_tune-<replaceable>tune</replaceable> = "<replaceable>tune</replaceable>" + </literallayout> </para> <para> @@ -9234,7 +10907,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-TUNEABI'><glossterm>TUNEABI</glossterm> + <glossentry id='var-TUNEABI'><glossterm><imagedata fileref="figures/define-generic.png" />TUNEABI</glossterm> + <info> + TUNEABI[doc] = "An underlying ABI used by a particular tuning in a given toolchain layer. This feature allows providers using prebuilt libraries to check compatibility of a tuning against their selection of libraries." + </info> <glossdef> <para> An underlying Application Binary Interface (ABI) used by @@ -9258,7 +10934,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-TUNEABI_OVERRIDE'><glossterm>TUNEABI_OVERRIDE</glossterm> + <glossentry id='var-TUNEABI_OVERRIDE'><glossterm><imagedata fileref="figures/define-generic.png" />TUNEABI_OVERRIDE</glossterm> + <info> + TUNEABI_OVERRIDE[doc] = "If set, ignores TUNEABI_WHITELIST." + </info> <glossdef> <para> If set, the OpenEmbedded system ignores the @@ -9281,7 +10960,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-TUNEABI_WHITELIST'><glossterm>TUNEABI_WHITELIST</glossterm> + <glossentry id='var-TUNEABI_WHITELIST'><glossterm><imagedata fileref="figures/define-generic.png" />TUNEABI_WHITELIST</glossterm> + <info> + TUNEABI_WHITELIST[doc] = "A whitelist of permissible TUNEABI values. If the variable is not set, all values are allowed." + </info> <glossdef> <para> A whitelist of permissible @@ -9305,11 +10987,14 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-TUNECONFLICT'><glossterm>TUNECONFLICT[<feature>]</glossterm> + <glossentry id='var-TUNECONFLICTS'><glossterm><imagedata fileref="figures/define-generic.png" />TUNECONFLICTS[<replaceable>feature</replaceable>]</glossterm> + <info> + TUNECONFLICTS[doc] = "Specifies CPU or Application Binary Interface (ABI) tuning features that conflict with specified feature." + </info> <glossdef> <para> Specifies CPU or Application Binary Interface (ABI) - tuning features that conflict with >feature<. + tuning features that conflict with <replaceable>feature</replaceable>. </para> <para> @@ -9327,7 +11012,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-TUNEVALID'><glossterm>TUNEVALID[<feature>]</glossterm> + <glossentry id='var-TUNEVALID'><glossterm><imagedata fileref="figures/define-generic.png" />TUNEVALID[<replaceable>feature</replaceable>]</glossterm> + <info> + TUNEVALID[doc] = "Descriptions, stored as flags, of valid tuning features." + </info> <glossdef> <para> Specifies a valid CPU or Application Binary Interface (ABI) @@ -9350,7 +11038,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossdiv id='var-glossary-u'><title>U</title> - <glossentry id='var-UBOOT_CONFIG'><glossterm>UBOOT_CONFIG</glossterm> + <glossentry id='var-UBOOT_CONFIG'><glossterm><imagedata fileref="figures/define-generic.png" />UBOOT_CONFIG</glossterm> + <info> + UBOOT_CONFIG[doc] = "Configures the UBOOT_MACHINE and can also define IMAGE_FSTYPES for individual cases." + </info> <glossdef> <para> Configures the @@ -9389,7 +11080,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-UBOOT_ENTRYPOINT'><glossterm>UBOOT_ENTRYPOINT</glossterm> + <glossentry id='var-UBOOT_ENTRYPOINT'><glossterm><imagedata fileref="figures/define-generic.png" />UBOOT_ENTRYPOINT</glossterm> + <info> + UBOOT_ENTRYPOINT[doc] = "Specifies the entry point for the U-Boot image." + </info> <glossdef> <para> Specifies the entry point for the U-Boot image. @@ -9401,7 +11095,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-UBOOT_LOADADDRESS'><glossterm>UBOOT_LOADADDRESS</glossterm> + <glossentry id='var-UBOOT_LOADADDRESS'><glossterm><imagedata fileref="figures/define-generic.png" />UBOOT_LOADADDRESS</glossterm> + <info> + UBOOT_LOADADDRESS[doc] = "Specifies the load address for the U-Boot image." + </info> <glossdef> <para> Specifies the load address for the U-Boot image. @@ -9413,7 +11110,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-UBOOT_LOCALVERSION'><glossterm>UBOOT_LOCALVERSION</glossterm> + <glossentry id='var-UBOOT_LOCALVERSION'><glossterm><imagedata fileref="figures/define-generic.png" />UBOOT_LOCALVERSION</glossterm> + <info> + UBOOT_LOCALVERSION[doc] = "Appends a string to the name of the local version of the U-Boot image." + </info> <glossdef> <para> Appends a string to the name of the local version of the @@ -9429,7 +11129,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-UBOOT_MACHINE'><glossterm>UBOOT_MACHINE</glossterm> + <glossentry id='var-UBOOT_MACHINE'><glossterm><imagedata fileref="figures/define-generic.png" />UBOOT_MACHINE</glossterm> + <info> + UBOOT_MACHINE[doc] = "Specifies the value passed on the make command line when building a U-Boot image." + </info> <glossdef> <para> Specifies the value passed on the @@ -9438,7 +11141,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" The value indicates the target platform configuration. You typically set this variable from the machine configuration file (i.e. - <filename>conf/machine/<machine_name>.conf</filename>). + <filename>conf/machine/<replaceable>machine_name</replaceable>.conf</filename>). </para> <para> @@ -9449,7 +11152,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-UBOOT_MAKE_TARGET'><glossterm>UBOOT_MAKE_TARGET</glossterm> + <glossentry id='var-UBOOT_MAKE_TARGET'><glossterm><imagedata fileref="figures/define-generic.png" />UBOOT_MAKE_TARGET</glossterm> + <info> + UBOOT_MAKE_TARGET[doc] = "Specifies the target called in the Makefile." + </info> <glossdef> <para> Specifies the target called in the @@ -9459,7 +11165,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-UBOOT_SUFFIX'><glossterm>UBOOT_SUFFIX</glossterm> + <glossentry id='var-UBOOT_SUFFIX'><glossterm><imagedata fileref="figures/define-generic.png" />UBOOT_SUFFIX</glossterm> + <info> + UBOOT_SUFFIX[doc] = "Points to the generated U-Boot extension." + </info> <glossdef> <para> Points to the generated U-Boot extension. @@ -9474,7 +11183,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-UBOOT_TARGET'><glossterm>UBOOT_TARGET</glossterm> + <glossentry id='var-UBOOT_TARGET'><glossterm><imagedata fileref="figures/define-generic.png" />UBOOT_TARGET</glossterm> + <info> + UBOOT_TARGET[doc] = "Specifies the target used for building U-Boot." + </info> <glossdef> <para> Specifies the target used for building U-Boot. @@ -9487,7 +11199,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-USE_VT'><glossterm>USE_VT</glossterm> + <glossentry id='var-USE_VT'><glossterm><imagedata fileref="figures/define-generic.png" />USE_VT</glossterm> + <info> + USE_VT[doc] = "When using SysVinit, determines whether or not to run a getty on any virtual terminals in order to enable logging in through those terminals." + </info> <glossdef> <para> When using @@ -9509,7 +11224,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-USER_CLASSES'><glossterm>USER_CLASSES</glossterm> + <glossentry id='var-USER_CLASSES'><glossterm><imagedata fileref="figures/define-generic.png" />USER_CLASSES</glossterm> + <info> + USER_CLASSES[doc] = "List of additional classes to use when building images that enable extra features." + </info> <glossdef> <para> A list of classes to globally inherit. @@ -9533,7 +11251,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-USERADD_ERROR_DYNAMIC'><glossterm>USERADD_ERROR_DYNAMIC</glossterm> + <glossentry id='var-USERADD_ERROR_DYNAMIC'><glossterm><imagedata fileref="figures/define-generic.png" />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." + </info> <glossdef> <para> Forces the OpenEmbedded build system to produce an error @@ -9570,7 +11291,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-USERADD_GID_TABLES'><glossterm>USERADD_GID_TABLES</glossterm> + <glossentry id='var-USERADD_GID_TABLES'><glossterm><imagedata fileref="figures/define-generic.png" />USERADD_GID_TABLES</glossterm> + <info> + USERADD_GID_TABLES[doc] = "Specifies a password file to use for obtaining static group identification (gid) values when the OpenEmbedded build system adds a group to the system during package installation." + </info> <glossdef> <para> Specifies a password file to use for obtaining static @@ -9602,43 +11326,15 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-USERADD_UID_TABLES'><glossterm>USERADD_UID_TABLES</glossterm> - <glossdef> - <para> - Specifies a password file to use for obtaining static - user identification (<filename>uid</filename>) values - when the OpenEmbedded build system adds a user to the - system during package installation. - </para> - - <para> - When applying static user identification - (<filename>uid</filename>) values, the OpenEmbedded build - system looks in - <link linkend='var-BBPATH'><filename>BBPATH</filename></link> - for a <filename>files/passwd</filename> file and then applies - those <filename>uid</filename> values. - Set the variable as follows in your - <filename>local.conf</filename> file: - <literallayout class='monospaced'> - USERADD_UID_TABLES = "files/passwd" - </literallayout> - </para> - - <note> - Setting the - <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link> - variable to "useradd-staticids" causes the build system - to use static <filename>uid</filename> values. - </note> - </glossdef> - </glossentry> - - <glossentry id='var-USERADD_PACKAGES'><glossterm>USERADD_PACKAGES</glossterm> + <glossentry id='var-USERADD_PACKAGES'><glossterm><imagedata fileref="figures/define-generic.png" />USERADD_PACKAGES</glossterm> + <info> + USERADD_PACKAGES[doc] = "When a recipe inherits the useradd class, this variable specifies the individual packages within the recipe that require users and/or groups to be added." + </info> <glossdef> <para> - When a recipe inherits the - <filename>useradd</filename> class, this variable + When inheriting the + <link linkend='ref-classes-useradd'><filename>useradd</filename></link> + class, this variable specifies the individual packages within the recipe that require users and/or groups to be added. </para> @@ -9666,11 +11362,15 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-USERADD_PARAM'><glossterm>USERADD_PARAM</glossterm> + <glossentry id='var-USERADD_PARAM'><glossterm><imagedata fileref="figures/define-generic.png" />USERADD_PARAM</glossterm> + <info> + USERADD_PARAM[doc] = "When a recipe inherits the useradd class, this variable specifies for a package what parameters should be passed to the useradd command if you wish to add a user to the system when the package is installed." + </info> <glossdef> <para> - When a recipe inherits the - <filename>useradd</filename> class, this variable + When inheriting the + <link linkend='ref-classes-useradd'><filename>useradd</filename></link> + class, this variable specifies for a package what parameters should be passed to the <filename>useradd</filename> command if you wish to add a user to the system when the package @@ -9692,7 +11392,45 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-USERADDEXTENSION'><glossterm>USERADDEXTENSION</glossterm> + <glossentry id='var-USERADD_UID_TABLES'><glossterm><imagedata fileref="figures/define-generic.png" />USERADD_UID_TABLES</glossterm> + <info> + USERADD_UID_TABLES[doc] = "Specifies a password file to use for obtaining static user identification (uid) values when the OpenEmbedded build system adds a user to the system during package installation." + </info> + <glossdef> + <para> + Specifies a password file to use for obtaining static + user identification (<filename>uid</filename>) values + when the OpenEmbedded build system adds a user to the + system during package installation. + </para> + + <para> + When applying static user identification + (<filename>uid</filename>) values, the OpenEmbedded build + system looks in + <link linkend='var-BBPATH'><filename>BBPATH</filename></link> + for a <filename>files/passwd</filename> file and then applies + those <filename>uid</filename> values. + Set the variable as follows in your + <filename>local.conf</filename> file: + <literallayout class='monospaced'> + USERADD_UID_TABLES = "files/passwd" + </literallayout> + </para> + + <note> + Setting the + <link linkend='var-USERADDEXTENSION'><filename>USERADDEXTENSION</filename></link> + variable to "useradd-staticids" causes the build system + to use static <filename>uid</filename> values. + </note> + </glossdef> + </glossentry> + + <glossentry id='var-USERADDEXTENSION'><glossterm><imagedata fileref="figures/define-generic.png" />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." + </info> <glossdef> <para> When set to "useradd-staticids", causes the @@ -9744,7 +11482,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossdiv id='var-glossary-w'><title>W</title> - <glossentry id='var-WARN_QA'><glossterm>WARN_QA</glossterm> + <glossentry id='var-WARN_QA'><glossterm><imagedata fileref="figures/define-generic.png" />WARN_QA</glossterm> + <info> + WARN_QA[doc] = "Specifies the quality assurance checks whose failures are reported as warnings by the OpenEmbedded build system." + </info> <glossdef> <para> Specifies the quality assurance checks whose failures are @@ -9759,7 +11500,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-WORKDIR'><glossterm>WORKDIR</glossterm> + <glossentry id='var-WORKDIR'><glossterm><imagedata fileref="figures/define-generic.png" />WORKDIR</glossterm> + <info> + WORKDIR[doc] = "The pathname of the working directory in which the OpenEmbedded build system builds a recipe. This directory is located within the TMPDIR directory structure and changes as different packages are built." + </info> <glossdef> <para> The pathname of the work directory in which the OpenEmbedded @@ -9815,8 +11559,32 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdiv> -<!-- <glossdiv id='var-glossary-x'><title>X</title>--> -<!-- </glossdiv>--> + <glossdiv id='var-glossary-x'><title>X</title> + + <glossentry id='var-XSERVER'><glossterm><imagedata fileref="figures/define-generic.png" />XSERVER</glossterm> + <info> + XSERVER[doc] = "Specifies the packages that should be installed + to provide an X server and drivers for the current machine." + </info> + <glossdef> + <para> + Specifies the packages that should be installed to + provide an X server and drivers for the current machine, + assuming your image directly includes + <filename>packagegroup-core-x11-xserver</filename> or, + perhaps indirectly, includes "x11-base" in + <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>. + </para> + + <para> + The default value of <filename>XSERVER</filename>, if not + specified in the machine configuration, is + "xserver-xorg xf86-video-fbdev xf86-input-evdev". + </para> + </glossdef> + </glossentry> + + </glossdiv> <!-- <glossdiv id='var-glossary-y'><title>Y</title>--> <!-- </glossdiv>--> diff --git a/documentation/ref-manual/resources.xml b/documentation/ref-manual/resources.xml index 686b48a546..17b8e97145 100644 --- a/documentation/ref-manual/resources.xml +++ b/documentation/ref-manual/resources.xml @@ -54,6 +54,8 @@ announcements.</para></listitem> </itemizedlist> </para> + For more Yocto Project-related mailing lists, see the Yocto Project community mailing lists page + <ulink url='&YOCTO_HOME_URL;/tools-resources/community/mailing-lists'>here</ulink>. </section> <section id='resources-irc'> @@ -80,7 +82,7 @@ Project.</para></listitem> <listitem><para><emphasis> <ulink url='http://www.intel.com/'>Intel Corporation</ulink>:</emphasis> - The company who acquired OpenedHand in 2008 and began + The company that acquired OpenedHand in 2008 and began development on the Yocto Project.</para></listitem> <listitem><para><emphasis> <ulink url='&OE_HOME_URL;'>OpenEmbedded</ulink>:</emphasis> @@ -89,7 +91,7 @@ Poky derives from and contributes back to the OpenEmbedded project.</para></listitem> <listitem><para><emphasis> - <ulink url='http://developer.berlios.de/projects/bitbake/'> + <ulink url='http://www.openembedded.org/wiki/BitBake'> BitBake</ulink>:</emphasis> The tool used to process metadata.</para></listitem> <listitem><para><emphasis> <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>:</emphasis> @@ -116,7 +118,7 @@ pull requests, or by submitting patches through email. For information on how to do both as well as information on how - to find out who is the maintainer for areas of code, see the + to identify the maintainer for each area of code, see the "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>How to Submit a Change</ulink>" section in the Yocto Project Development Manual. </para> diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml index b0588351d5..6bb3381e72 100644 --- a/documentation/ref-manual/technical-details.xml +++ b/documentation/ref-manual/technical-details.xml @@ -85,7 +85,7 @@ </para> <para> - The most common usage for BitBake is <filename>bitbake <packagename></filename>, where + The most common usage for BitBake is <filename>bitbake <replaceable>packagename</replaceable></filename>, where <filename>packagename</filename> is the name of the package you want to build (referred to as the "target" in this manual). The target often equates to the first part of a recipe's filename @@ -304,7 +304,8 @@ <para> Here is the bootstrap process for the relocatable toolchain: <literallayout class='monospaced'> - gcc -> binutils-crosssdk -> gcc-crosssdk-initial -> linux-libc-headers -> eglibc-initial -> nativesdk-eglibc -> gcc-crosssdk -> gcc-cross-canadian + gcc -> binutils-crosssdk -> gcc-crosssdk-initial -> linux-libc-headers -> + eglibc-initial -> nativesdk-eglibc -> gcc-crosssdk -> gcc-cross-canadian </literallayout> <itemizedlist> <listitem><para><filename>gcc</filename>: @@ -608,13 +609,13 @@ make some dependency and hash information available to the build. This information includes: <itemizedlist> - <listitem><para><filename>BB_BASEHASH_task-<taskname></filename>: + <listitem><para><filename>BB_BASEHASH_task-</filename><replaceable>taskname</replaceable>: The base hashes for each task in the recipe. </para></listitem> - <listitem><para><filename>BB_BASEHASH_<filename:taskname></filename>: + <listitem><para><filename>BB_BASEHASH_</filename><replaceable>filename</replaceable><filename>:</filename><replaceable>taskname</replaceable>: The base hashes for each dependent task. </para></listitem> - <listitem><para><filename>BBHASHDEPS_<filename:taskname></filename>: + <listitem><para><filename>BBHASHDEPS_</filename><replaceable>filename</replaceable><filename>:</filename><replaceable>taskname</replaceable>: The task dependencies for each task. </para></listitem> <listitem><para><filename>BB_TASKHASH</filename>: diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml index 3c82d8185b..41f872c07e 100644 --- a/documentation/ref-manual/usingpoky.xml +++ b/documentation/ref-manual/usingpoky.xml @@ -35,12 +35,12 @@ <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>). Here is an example: <literallayout class='monospaced'> - $ source &OE_INIT_FILE; [<build_dir>] + $ source &OE_INIT_FILE; [<replaceable>build_dir</replaceable>] </literallayout> </para> <para> - The <filename>build_dir</filename> argument is optional and specifies the directory the + The <replaceable>build_dir</replaceable> argument is optional and specifies the directory the OpenEmbedded build system uses for the build - the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. If you do not specify a Build Directory, it defaults to a directory @@ -53,12 +53,12 @@ <para> Once the build environment is set up, you can build a target using: <literallayout class='monospaced'> - $ bitbake <target> + $ bitbake <replaceable>target</replaceable> </literallayout> </para> <para> - The <filename>target</filename> is the name of the recipe you want to build. + The <replaceable>target</replaceable> is the name of the recipe you want to build. Common targets are the images in <filename>meta/recipes-core/images</filename>, <filename>meta/recipes-sato/images</filename>, etc. all found in the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. @@ -69,8 +69,9 @@ </para> <note> - Building an image without GNU General Public License Version 3 (GPLv3) components - is supported for only minimal and base images. + Building an image without GNU General Public License Version + 3 (GPLv3), or similarly licensed, components is supported for + only minimal and base images. See the "<link linkend='ref-images'>Images</link>" chapter for more information. </note> </section> @@ -153,14 +154,14 @@ <title>Task Failures</title> <para>The log file for shell tasks is available in - <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>. - For example, the <filename>compile</filename> task for the QEMU minimal image for the x86 + <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_taskname.pid</filename> file located in the same directory. + <filename>run.do_<replaceable>taskname</replaceable>.pid</filename> file located in the same directory. </para> <para> @@ -179,7 +180,7 @@ <filename>do_patch</filename>, <filename>do_configure</filename>, <filename>do_compile</filename>, <filename>do_install</filename>, <filename>do_package</filename>, - <filename>do_package_write</filename>, and + <filename>do_package_write_*</filename>, and <filename>do_build</filename>. The default task is <filename>do_build</filename> and any tasks on which it depends build first. @@ -202,7 +203,7 @@ $ bitbake matchbox-desktop . . - [make some changes to the source code in the work directory] + <replaceable>make some changes to the source code in the work directory</replaceable> . . $ bitbake matchbox-desktop -c compile -f @@ -237,7 +238,7 @@ <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 <targetname></filename> command + 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 @@ -246,7 +247,7 @@ 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 <targetname></filename> + <filename>bitbake -g -u depexp <replaceable>targetname</replaceable></filename> command to display the results in a more human-readable form. </para> </section> @@ -263,7 +264,7 @@ </para> <para> - The output from <filename>bitbake -DDD -v targetname</filename> can reveal why + The output from <filename>bitbake -DDD -v</filename> <replaceable>targetname</replaceable> can reveal why BitBake chose a certain version of a package or why BitBake picked a certain provider. This command could also help you in a situation where you think BitBake did something @@ -309,7 +310,7 @@ To build a specific recipe (<filename>.bb</filename> file), you can use the following command form: <literallayout class='monospaced'> - $ bitbake -b <somepath/somerecipe.bb> + $ bitbake -b <replaceable>somepath</replaceable>/<replaceable>somerecipe</replaceable>.bb </literallayout> This command form does not check for dependencies. Consequently, you should use it @@ -333,7 +334,7 @@ This next example shows the parsing environment for a specific recipe: <literallayout class='monospaced'> - $ bitbake -e <recipename> + $ bitbake -e <replaceable>recipename</replaceable> </literallayout> </para> </section> @@ -539,7 +540,7 @@ <para> Build history information is kept in - <filename>$</filename><link linkend='var-TOPDIR'><filename>TOPDIR</filename></link><filename>/buildhistory</filename> + <filename>${</filename><link linkend='var-TOPDIR'><filename>TOPDIR</filename></link><filename>}/buildhistory</filename> in the Build Directory as defined by the <link linkend='var-BUILDHISTORY_DIR'><filename>BUILDHISTORY_DIR</filename></link> variable. @@ -678,9 +679,11 @@ The files are defined by <link linkend='var-BUILDHISTORY_IMAGE_FILES'><filename>BUILDHISTORY_IMAGE_FILES</filename></link>. </para></listitem> - <listitem><para><filename>build-id:</filename> + <listitem><para><filename>build-id.txt:</filename> Human-readable information about the build configuration - and metadata source revisions.</para></listitem> + and metadata source revisions. + This file contains the full build header as printed + by BitBake.</para></listitem> <listitem><para><filename>*.dot:</filename> Dependency graphs for the image that are compatible with <filename>graphviz</filename>. @@ -720,7 +723,7 @@ IMAGE_FEATURES = debug-tweaks x11-base apps-x11-core \ package-management ssh-server-dropbear package-management IMAGE_LINGUAS = en-us en-gb - IMAGE_INSTALL = task-core-boot task-base-extended + IMAGE_INSTALL = packagegroup-core-boot packagegroup-base-extended BAD_RECOMMENDATIONS = ROOTFS_POSTPROCESS_COMMAND = buildhistory_get_image_installed ; rootfs_update_timestamp ; IMAGE_POSTPROCESS_COMMAND = buildhistory_get_imageinfo ; @@ -885,6 +888,148 @@ </section> </section> +<section id='speeding-up-the-build'> + <title>Speeding Up the Build</title> + + <para> + Build time can be an issue. + By default, the build system uses three simple controls to try and + maximize build efficiency: + <itemizedlist> + <listitem><para> + <link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link> + </para></listitem> + <listitem><para> + <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_NUMBER_PARSE_THREADS'><filename>BB_NUMBER_PARSE_THREADS</filename></ulink> + </para></listitem> + <listitem><para> + <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link> + </para></listitem> + </itemizedlist> + These three variables all scale to the number of processor cores + available on the build system. + This auto-scaling ensures that the build system fundamentally takes + advantage of potential parallel operations during the build + based on the build machine's capabilities. + </para> + + <para> + If you need to achieve even faster builds than what the build system + produces by default, you can consider and implement some of the + following: + <itemizedlist> + <listitem><para> + <filename>BB_NUMBER_THREADS</filename>, + <filename>BB_NUMBER_PARSE_THREADS</filename>, and + <filename>PARALLEL_MAKE</filename>: + As previously mentioned, the build system scales the values + for these variables. + However, you can manually override them in your + <filename>local.conf</filename> file if you are not satisfied + with the defaults. + </para></listitem> + <listitem><para> + File system type: + The file system type that the build is being performed on can + also influence performance. + Using <filename>ext4</filename> is recommended as compared + to <filename>ext2</filename> and <filename>ext3</filename> + due to <filename>ext4</filename> improved features + such as extents. + </para></listitem> + <listitem><para> + Disabling the updating of access time using + <filename>noatime</filename>: + The <filename>noatime</filename> mount option prevents the + build system from updating file and directory access times. + </para></listitem> + <listitem><para> + Setting a longer commit: + Using the "commit=" mount option increases the interval + in seconds between disk cache writes. + Changing this interval from the five second default to + something longer increases the risk of data loss but decreases + the need to write to the disk, thus increasing the build + performance. + </para></listitem> + <listitem><para> + Choosing the packaging backend: + Of the available packaging backends, IPK is the fastest. + Additionally, selecting a singular packaging backend also + helps. + </para></listitem> + <listitem><para> + Using <filename>/tmp</filename> as a temporary file system: + While this can help speed up the build, the benefits are + limited due to the compiler using + <filename>-pipe</filename>. + The build system goes to some lengths to avoid + <filename>sync()</filename> calls into the + file system on the principle that if there was a significant + failure, the + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> + contents could easily be rebuilt. + </para></listitem> + <listitem><para> + Inheriting the + <link linkend='ref-classes-rm-work'><filename>rm_work</filename></link> + class: + Inheriting this class has shown to speed up builds due to + significantly lower amounts of data stored in the data + cache as well as on disk. + Inheriting this class also makes cleanup of + <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> + faster, at the expense of being easily able to dive into the + source code. + File system maintainers have recommended that the fastest way + to clean up large numbers of files is to reformat partitions + rather than delete files due to the linear nature of partitions. + This, of course, assumes you structure the disk partitions and + file systems in a way that this is practical. + </para></listitem> + </itemizedlist> + Aside from the previous list, you should keep some trade offs in + mind that can help you speed up the build: + <itemizedlist> + <listitem><para> + Exclude debug symbols and other debug information: + If you do not need these symbols and other debug information, + disabling the <filename>*-dbg</filename> package generation + can speed up the build. + You can disable this generation by setting the + <link linkend='var-INHIBIT_PACKAGE_DEBUG_SPLIT'><filename>INHIBIT_PACKAGE_DEBUG_SPLIT</filename></link> + variable to "1". + </para></listitem> + <listitem><para> + Disable static library generation for recipes derived from + <filename>autoconf</filename> or <filename>libtool</filename>: + Following is an example showing how to disable static + libraries and still provide an override to handle exceptions: + <literallayout class='monospaced'> + STATICLIBCONF = "--disable-static" + STATICLIBCONF_sqlite3-native = "" + EXTRA_OECONF += "${STATICLIBCONF}" + </literallayout> + <note><title>Notes</title> + <itemizedlist> + <listitem><para> + Some recipes need static libraries in order to work + correctly (e.g. <filename>pseudo-native</filename> + needs <filename>sqlite3-native</filename>). + Overrides, as in the previous example, account for + these kinds of exceptions. + </para></listitem> + <listitem><para> + Some packages have packaging code that assumes the + presence of the static libraries. + If so, you might need to exclude them as well. + </para></listitem> + </itemizedlist> + </note> + </para></listitem> + </itemizedlist> + </para> +</section> </chapter> <!-- vim: expandtab tw=80 ts=4 diff --git a/documentation/template/qa-code-permalinks.xsl b/documentation/template/qa-code-permalinks.xsl new file mode 100644 index 0000000000..a309095c60 --- /dev/null +++ b/documentation/template/qa-code-permalinks.xsl @@ -0,0 +1,23 @@ +<!--
+This XSL sheet enables creation of permalinks for <para><code>
+constructs. Right now, this construct occurs only in the ref-manual
+book's qa issues and warnings chapter. However, if the construct
+were to appear anywhere in that ref-manual, a permalink would be
+generated. I don't foresee any <para><code> constructs being used
+in the future but if they are then a permalink with a generically
+numbered permalink would be generated.
+-->
+<xsl:stylesheet version="1.0"
+ xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ xmlns:d="http://docbook.org/ns/docbook"
+ xmlns="http://www.w3.org/1999/xhtml">
+
+ <xsl:template match="para/code">
+ <xsl:apply-imports/>
+ <xsl:if test="$generate.permalink != 0">
+ <xsl:call-template name="permalink">
+ <xsl:with-param name="node" select=".."/>
+ </xsl:call-template>
+ </xsl:if>
+ </xsl:template>
+</xsl:stylesheet>
diff --git a/documentation/tools/mega-manual.sed b/documentation/tools/mega-manual.sed index 69a5b825c7..748632bb55 100644 --- a/documentation/tools/mega-manual.sed +++ b/documentation/tools/mega-manual.sed @@ -1,14 +1,31 @@ -# Processes ref-manual and yocto-project-qs manual (<word>-<word>-<word> style) -s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.7\/[a-z]*-[a-z]*-[a-z]*\/[a-z]*-[a-z]*-[a-z]*.html#/\"link\" href=\"#/g +# Processes poky-ref-manual and yocto-project-qs manual (<word>-<word>-<word> style). +# This style is for manual folders like "yocto-project-qs" and "poky-ref-manual". +# This is the old way that did it. Can't do that now that we have "bitbake-user-manual" strings +# in the mega-manual. +# s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.8\/[a-z]*-[a-z]*-[a-z]*\/[a-z]*-[a-z]*-[a-z]*.html#/\"link\" href=\"#/g +s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.8\/yocto-project-qs\/yocto-project-qs.html#/\"link\" href=\"#/g +s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.8\/poky-ref-manual\/poky-ref-manual.html#/\"link\" href=\"#/g -# Processes all other manuals (<word>-<word> style) -s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.7\/[a-z]*-[a-z]*\/[a-z]*-[a-z]*.html#/\"link\" href=\"#/g +# Processes all other manuals (<word>-<word> style) except for the BitBake User Manual because +# it is not included in the mega-manual. +# This style is for manual folders that use two word, which is the standard now (e.g. "ref-manual"). +# This was the one-liner that worked before we introduced the BitBake User Manual, which is +# not in the mega-manual. +# s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.8\/[a-z]*-[a-z]*\/[a-z]*-[a-z]*.html#/\"link\" href=\"#/g + +s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.8\/adt-manual\/adt-manual.html#/\"link\" href=\"#/g +s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.8\/bsp-guide\/bsp-guide.html#/\"link\" href=\"#/g +s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.8\/dev-manual\/dev-manual.html#/\"link\" href=\"#/g +s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.8\/kernel-dev\/kernel-dev.html#/\"link\" href=\"#/g +s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.8\/profile-manual\/profile-manual.html#/\"link\" href=\"#/g +s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.8\/ref-manual\/ref-manual.html#/\"link\" href=\"#/g +s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.8\/yocto-project-qs\/yocto-project-qs.html#/\"link\" href=\"#/g # Process cases where just an external manual is referenced without an id anchor -s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.7\/yocto-project-qs\/yocto-project-qs.html\" target=\"_top\">Yocto Project Quick Start<\/a>/Yocto Project Quick Start/g -s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.7\/dev-manual\/dev-manual.html\" target=\"_top\">Yocto Project Development Manual<\/a>/Yocto Project Development Manual/g -s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.7\/adt-manual\/adt-manual.html\" target=\"_top\">Yocto Project Application Developer's Guide<\/a>/Yocto Project Application Developer's Guide/g -s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.7\/bsp-guide\/bsp-guide.html\" target=\"_top\">Yocto Project Board Support Package (BSP) Developer's Guide<\/a>/Yocto Project Board Support Package (BSP) Developer's Guide/g -s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.7\/profile-manual\/profile-manual.html\" target=\"_top\">Yocto Project Profiling and Tracing Manual<\/a>/Yocto Project Profiling and Tracing Manual/g -s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.7\/kernel-dev\/kernel-dev.html\" target=\"_top\">Yocto Project Linux Kernel Development Manual<\/a>/Yocto Project Linux Kernel Development Manual/g -s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.7\/ref-manual\/ref-manual.html\" target=\"_top\">Yocto Project Reference Manual<\/a>/Yocto Project Reference Manual/g +s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.8\/yocto-project-qs\/yocto-project-qs.html\" target=\"_top\">Yocto Project Quick Start<\/a>/Yocto Project Quick Start/g +s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.8\/dev-manual\/dev-manual.html\" target=\"_top\">Yocto Project Development Manual<\/a>/Yocto Project Development Manual/g +s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.8\/adt-manual\/adt-manual.html\" target=\"_top\">Yocto Project Application Developer's Guide<\/a>/Yocto Project Application Developer's Guide/g +s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.8\/bsp-guide\/bsp-guide.html\" target=\"_top\">Yocto Project Board Support Package (BSP) Developer's Guide<\/a>/Yocto Project Board Support Package (BSP) Developer's Guide/g +s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.8\/profile-manual\/profile-manual.html\" target=\"_top\">Yocto Project Profiling and Tracing Manual<\/a>/Yocto Project Profiling and Tracing Manual/g +s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.8\/kernel-dev\/kernel-dev.html\" target=\"_top\">Yocto Project Linux Kernel Development Manual<\/a>/Yocto Project Linux Kernel Development Manual/g +s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.8\/ref-manual\/ref-manual.html\" target=\"_top\">Yocto Project Reference Manual<\/a>/Yocto Project Reference Manual/g diff --git a/documentation/yocto-project-qs/yocto-project-qs-customization.xsl b/documentation/yocto-project-qs/yocto-project-qs-customization.xsl index 5d11e7ee70..3dad6b96c5 100644 --- a/documentation/yocto-project-qs/yocto-project-qs-customization.xsl +++ b/documentation/yocto-project-qs/yocto-project-qs-customization.xsl @@ -1,7 +1,7 @@ <?xml version='1.0'?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0"> - <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl" /> + <xsl:import href="http://docbook.sourceforge.net/release/xsl/1.76.1/xhtml/docbook.xsl" /> <xsl:import href="yocto-project-qs-titlepage.xsl"/> <xsl:include href="../template/permalinks.xsl"/> diff --git a/documentation/yocto-project-qs/yocto-project-qs.xml b/documentation/yocto-project-qs/yocto-project-qs.xml index ea2b35234c..9f1a4fbb36 100644 --- a/documentation/yocto-project-qs/yocto-project-qs.xml +++ b/documentation/yocto-project-qs/yocto-project-qs.xml @@ -1,4 +1,4 @@ -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +<!DOCTYPE article 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; ] > @@ -86,10 +86,12 @@ the Yocto Project Reference Manual. </para></listitem> <listitem><para><emphasis>Developer Screencast:</emphasis> The - <ulink url='http://vimeo.com/36450321'>Getting Started with the Yocto Project - New - Developer Screencast Tutorial</ulink> provides a 30-minute video - created for users unfamiliar with the Yocto Project but familiar - with Linux build systems.</para></listitem> + <ulink url='http://vimeo.com/36450321'>Getting Started with the Yocto Project - New Developer Screencast Tutorial</ulink> + provides a 30-minute video created for users unfamiliar with + the Yocto Project but familiar with Linux build systems. + While this screencast is somewhat dated, the introductory + and fundamental concepts are useful for the beginner. + </para></listitem> </itemizedlist> </para> </section> @@ -177,7 +179,8 @@ decrease the time needed to build images. </para></listitem> <listitem><para> - The right packages. + Appropriate packages installed on the system you are using for + builds. </para></listitem> <listitem><para> A release of the Yocto Project. @@ -404,13 +407,30 @@ Use the following commands to build your image. The OpenEmbedded build process creates an entire Linux distribution, including the toolchain, from source. - <note> - By default, the build process searches for source code using - a pre-determined order through a set of locations. - If you encounter problems with the build process finding and - downloading source code, see the - "<ulink url='&YOCTO_DOCS_REF_URL;#how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>How does the OpenEmbedded build system obtain source code and will it work behind my firewall or proxy server?</ulink>" - entry in the Yocto Project Reference Manual FAQ. + <note><title>Note about Network Proxies</title> + <para> + By default, the build process searches for source code + using a pre-determined order through a set of locations. + If you are working behind a firewall and your build system + is not set up for proxies, you could encounter problems + with the build process when fetching source code (e.g. + fetcher failures or Git failures). + </para> + + <para> + If you do not know your proxy settings, consult your + local network infrastructure resources and get that + information. + A good starting point could also be to check your web + browser settings. + Finally, you can find more information on using the Yocto + Project behind a firewall in the Yocto Project Reference + Manual + <ulink url='&YOCTO_DOCS_REF_URL;#how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>FAQ</ulink> + and on the + "<ulink url='https://wiki.yoctoproject.org/wiki/Working_Behind_a_Network_Proxy'>Working Behind a Network Proxy</ulink>" + wiki page. + </para> </note> </para> @@ -492,7 +512,7 @@ Another couple of variables of interest are the <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></ulink> and the <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink> variables. - By default, these variables are set to how ever many processor + By default, these variables are set to the number of processor cores your build host uses. However, if your build host uses multiple processor cores, you should increase these settings to twice the number of @@ -518,7 +538,7 @@ <filename>bitbake --help</filename> command, see the "<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-components-bitbake'>BitBake</ulink>" section in the Yocto Project Reference Manual, or see the - "<ulink url='&YOCTO_DOCS_BB_URL;#user-manual-command'>BitBake Command</ulink>" + "<ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual-command'>BitBake Command</ulink>" section in the BitBake User Manual. <literallayout class='monospaced'> $ bitbake -k core-image-sato @@ -529,7 +549,7 @@ "<ulink url='&YOCTO_DOCS_REF_URL;#required-git-tar-and-python-versions'>Required Git, tar, and Python</ulink>" section in the Yocto Project Reference Manual. </note> - The final command runs the image: + The final command runs the image using the QEMU emulator: <literallayout class='monospaced'> $ runqemu qemux86 </literallayout> @@ -605,25 +625,25 @@ </para> <literallayout class='monospaced'> - poky-eglibc-<<emphasis>host_system</emphasis>>-<<emphasis>image_type</emphasis>>-<<emphasis>arch</emphasis>>-toolchain-<<emphasis>release_version</emphasis>>.sh + poky-eglibc-<replaceable>host_system</replaceable>-<replaceable>image_type</replaceable>-<replaceable>arch</replaceable>-toolchain-<replaceable>release_version</replaceable>.sh Where: - <<emphasis>host_system</emphasis>> is a string representing your development system: + <replaceable>host_system</replaceable> is a string representing your development system: i686 or x86_64. - <<emphasis>image_type</emphasis>> is a string representing the image you wish to + <replaceable>image_type</replaceable> is a string representing the image you wish to develop a Software Development Toolkit (SDK) for use against. The Yocto Project builds toolchain installers using the following BitBake command: bitbake core-image-sato -c populate_sdk - <<emphasis>arch</emphasis>> is a string representing the tuned target architecture: + <replaceable>arch</replaceable> is a string representing the tuned target architecture: i586, x86_64, powerpc, mips, armv7a or armv5te - <<emphasis>release_version</emphasis>> is a string representing the release number of the + <replaceable>release_version</replaceable> is a string representing the release number of the Yocto Project: &DISTRO;, &DISTRO;+snapshot @@ -689,11 +709,11 @@ <para> Most kernel files have one of the following forms: <literallayout class='monospaced'> - *zImage-qemu<<emphasis>arch</emphasis>>.bin - vmlinux-qemu<<emphasis>arch</emphasis>>.bin + *zImage-qemu<replaceable>arch</replaceable>.bin + vmlinux-qemu<replaceable>arch</replaceable>.bin Where: - <<emphasis>arch</emphasis>> is a string representing the target architecture: + <replaceable>arch</replaceable> is a string representing the target architecture: x86, x86-64, ppc, mips, or arm. </literallayout> </para> @@ -723,17 +743,17 @@ The <filename>tar</filename> form can be flattened out in your host development system and used for build purposes with the Yocto Project. <literallayout class='monospaced'> - core-image-<<emphasis>profile</emphasis>>-qemu<<emphasis>arch</emphasis>>.ext3 - core-image-<<emphasis>profile</emphasis>>-qemu<<emphasis>arch</emphasis>>.tar.bz2 + core-image-<replaceable>profile</replaceable>-qemu<replaceable>arch</replaceable>.ext3 + core-image-<replaceable>profile</replaceable>-qemu<replaceable>arch</replaceable>.tar.bz2 Where: - <<emphasis>profile</emphasis>> is the filesystem image's profile: + <replaceable>profile</replaceable> is the filesystem image's profile: lsb, lsb-dev, lsb-sdk, lsb-qt3, minimal, minimal-dev, sato, sato-dev, or sato-sdk. For information on these types of image - profiles, see the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter in the Yocto Project - Reference Manual. + profiles, see the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" + chapter in the Yocto Project Reference Manual. - <<emphasis>arch</emphasis>> is a string representing the target architecture: + <replaceable>arch</replaceable> is a string representing the target architecture: x86, x86-64, ppc, mips, or arm. </literallayout> </para> @@ -746,13 +766,13 @@ Before you start the QEMU emulator, you need to set up the emulation environment. The following command form sets up the emulation environment. <literallayout class='monospaced'> - $ source &YOCTO_ADTPATH_DIR;/environment-setup-<<emphasis>arch</emphasis>>-poky-linux-<<emphasis>if</emphasis>> + $ source &YOCTO_ADTPATH_DIR;/environment-setup-<replaceable>arch</replaceable>-poky-linux-<replaceable>if</replaceable> Where: - <<emphasis>arch</emphasis>> is a string representing the target architecture: + <replaceable>arch</replaceable> is a string representing the target architecture: i586, x86_64, ppc603e, mips, or armv5te. - <<emphasis>if</emphasis>> is a string representing an embedded application binary interface. + <replaceable>if</replaceable> is a string representing an embedded application binary interface. Not all setup scripts include this string. </literallayout> </para> @@ -760,15 +780,15 @@ <para> Finally, this command form invokes the QEMU emulator <literallayout class='monospaced'> - $ runqemu <<emphasis>qemuarch</emphasis>> <<emphasis>kernel-image</emphasis>> <<emphasis>filesystem-image</emphasis>> + $ runqemu <replaceable>qemuarch</replaceable> <replaceable>kernel-image</replaceable> <replaceable>filesystem-image</replaceable> Where: - <<emphasis>qemuarch</emphasis>> is a string representing the target architecture: qemux86, qemux86-64, + <replaceable>qemuarch</replaceable> is a string representing the target architecture: qemux86, qemux86-64, qemuppc, qemumips, or qemuarm. - <<emphasis>kernel-image</emphasis>> is the architecture-specific kernel image. + <replaceable>kernel-image</replaceable> is the architecture-specific kernel image. - <<emphasis>filesystem-image</emphasis>> is the .ext3 filesystem image. + <replaceable>filesystem-image</replaceable> is the .ext3 filesystem image. </literallayout> </para> |
