diff options
Diffstat (limited to 'documentation')
85 files changed, 11405 insertions, 2669 deletions
diff --git a/documentation/Makefile b/documentation/Makefile index 3bc9a213ee..71420ac2bb 100644 --- a/documentation/Makefile +++ b/documentation/Makefile @@ -1,28 +1,37 @@ -# This is a single Makefile to handle all generated Yocto Project documents. +# This is a single Makefile to handle all generated Yocto Project documents, +# which includes the BitBake User Manual and the Toaster User Manual. # 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. +# +# Some manuals are available as linked help through the Eclipse development +# system. These manuals also include an "eclipse" sub-directory as part of +# the make process. +# # Note that the figures for the Yocto Project Development Manual # differ depending on the BRANCH being built. # # The Makefile has these targets: +# all: If you leave off the target then "all" is implied. +# You will generate HTML, eclipse help (if applicable), +# and a tarball of 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 +# 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 +# The Makefile can generate an HTML and PDF version of every document except the # Yocto Project Quick Start and the single, HTML mega-manual, which is comprised -# of all the individual Yocto Project manuals. These two manuals are in HTML -# form only. The variable DOC indicates the folder name for a given manual. The -# variable VER represents the distro version of the Yocto Release for which the +# of all the individual Yocto Project manuals. You can generate these two manuals +# in HTML form only. The variable DOC indicates the folder name for a given manual. +# The variable VER represents the distro version of the Yocto Release for which the # manuals are being generated. The variable BRANCH is used to indicate the # branch (edison or denzil) and is used only when DOC=dev-manual or # DOC=mega-manual. If you do not specify a BRANCH, the default branch used @@ -33,50 +42,54 @@ # 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: # # make DOC=bsp-guide -# make DOC=yocto-project-qs +# make html DOC=yocto-project-qs # make pdf DOC=ref-manual # make DOC=dev-manual BRANCH=edison # 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 -# tarball of figures. Any example that does not use the BRANCH argument -# builds the current version of the manual set. +# The first example generates the HTML and Eclipse help 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. So, the +# 'make DOC=yocto-project-qs' command would be equivalent. The third example +# generates just the PDF version of the Yocto Project Reference Manual. +# The fourth example generates the HTML 'edison' version and (if available) +# the Eclipse help version 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. +# +# The publish target pushes the generated manuals to the Yocto Project +# website. Unless you are a developer on the YP team, you will not succeed in +# pushing manuals to this server. All files needed for the manual's HTML form are +# pushed as well as applicable Eclipse versions. # -# 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). # Examples: # -# make publish DOC=bsp-guide VER=1.3 -# make publish DOC=adt-manual VER=1.3 +# make publish DOC=bsp-guide VER=1.7 +# make publish DOC=adt-manual VER=1.6 # 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.7 version of both the PDF and HTML versions of +# the BSP Guide. The second example publishes the 1.6 version of both the PDF and +# HTML versions of the ADT Manual. The third example publishes the 1.1.1 version of +# the PDF and HTML YP Development Manual for the 'edison' branch. The fourth example +# publishes the 1.2 version of the PDF and HTML YP Development Manual for the +# 'denzil' branch. # ifeq ($(DOC),bsp-guide) XSLTOPTS = --xinclude -ALLPREQ = html pdf eclipse tarball -TARFILES = bsp-style.css bsp-guide.html bsp-guide.pdf figures/bsp-title.png \ +ALLPREQ = html eclipse tarball +TARFILES = bsp-style.css bsp-guide.html figures/bsp-title.png \ eclipse -MANUALS = $(DOC)/$(DOC).html $(DOC)/$(DOC).pdf $(DOC)/eclipse +MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse FIGURES = figures STYLESHEET = $(DOC)/*.css @@ -84,42 +97,47 @@ endif ifeq ($(DOC),dev-manual) XSLTOPTS = --xinclude -ALLPREQ = html pdf eclipse tarball +ALLPREQ = html 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 \ +TARFILES = dev-style.css dev-manual.html \ + 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 = 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 \ +TARFILES = dev-style.css dev-manual.html \ + 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 = 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 \ +TARFILES = dev-style.css dev-manual.html \ + 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 figures/build-workspace-directory.png \ eclipse endif -MANUALS = $(DOC)/$(DOC).html $(DOC)/$(DOC).pdf $(DOC)/eclipse +MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse FIGURES = figures STYLESHEET = $(DOC)/*.css @@ -146,62 +164,86 @@ 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/sdk-generation.png figures/recipe-workflow.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 \ + figures/build-workspace-directory.png figures/mega-title.png \ + figures/toaster-title.png figures/hosted-service.png \ + figures/simple-configuration.png endif MANUALS = $(DOC)/$(DOC).html @@ -212,7 +254,7 @@ endif ifeq ($(DOC),ref-manual) XSLTOPTS = --xinclude -ALLPREQ = html pdf eclipse tarball +ALLPREQ = html eclipse tarball TARFILES = ref-manual.html ref-style.css figures/poky-title.png \ figures/buildhistory.png figures/buildhistory-web.png eclipse \ figures/cross-development-toolchains.png figures/layer-input.png \ @@ -222,7 +264,7 @@ TARFILES = ref-manual.html ref-style.css figures/poky-title.png \ figures/patching.png figures/configuration-compile-autoreconf.png \ figures/analysis-for-package-splitting.png figures/image-generation.png \ figures/sdk-generation.png -MANUALS = $(DOC)/$(DOC).html $(DOC)/$(DOC).pdf $(DOC)/eclipse +MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse FIGURES = figures STYLESHEET = $(DOC)/*.css endif @@ -230,47 +272,68 @@ endif ifeq ($(DOC),adt-manual) XSLTOPTS = --xinclude -ALLPREQ = html pdf eclipse tarball -TARFILES = adt-manual.html adt-manual.pdf adt-style.css figures/adt-title.png \ +ALLPREQ = html eclipse tarball +TARFILES = adt-manual.html adt-style.css figures/adt-title.png \ eclipse -MANUALS = $(DOC)/$(DOC).html $(DOC)/$(DOC).pdf $(DOC)/eclipse +MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse FIGURES = figures STYLESHEET = $(DOC)/*.css endif ifeq ($(DOC),profile-manual) XSLTOPTS = --xinclude -ALLPREQ = html pdf eclipse tarball -TARFILES = profile-manual.html profile-manual.pdf profile-manual-style.css \ +ALLPREQ = html eclipse tarball +TARFILES = profile-manual.html 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 -MANUALS = $(DOC)/$(DOC).html $(DOC)/$(DOC).pdf $(DOC)/eclipse +MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse FIGURES = figures STYLESHEET = $(DOC)/*.css 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 \ +ALLPREQ = html eclipse tarball +TARFILES = kernel-dev.html kernel-dev-style.css \ + figures/kernel-dev-title.png \ figures/kernel-architecture-overview.png \ eclipse -MANUALS = $(DOC)/$(DOC).html $(DOC)/$(DOC).pdf $(DOC)/eclipse +MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse +FIGURES = figures +STYLESHEET = $(DOC)/*.css +endif + +ifeq ($(DOC),toaster-manual) +XSLTOPTS = --xinclude +ALLPREQ = html tarball +TARFILES = toaster-manual.html toaster-manual-style.css \ + figures/toaster-title.png figures/simple-configuration.png \ + figures/hosted-service.png +MANUALS = $(DOC)/$(DOC).html $(DOC)/$(DOC).pdf FIGURES = figures STYLESHEET = $(DOC)/*.css endif @@ -278,8 +341,8 @@ endif ## # These URI should be rewritten by your distribution's xml catalog to -# match your localy installed XSL stylesheets. -XSL_BASE_URI = http://docbook.sourceforge.net/release/xsl/current +# match your locally installed XSL stylesheets. +XSL_BASE_URI = http://docbook.sourceforge.net/release/xsl/1.76.1 XSL_XHTML_URI = $(XSL_BASE_URI)/xhtml/docbook.xsl all: $(ALLPREQ) diff --git a/documentation/adt-manual/adt-command.xml b/documentation/adt-manual/adt-command.xml index 164b1efbff..89184b2226 100644 --- a/documentation/adt-manual/adt-command.xml +++ b/documentation/adt-manual/adt-command.xml @@ -24,6 +24,10 @@ are also defined so that, for example, <filename>configure.sh</filename> can find pre-generated test results for tests that need target hardware on which to run. + You can see the + "<link linkend='setting-up-the-cross-development-environment'>Setting Up the Cross-Development Environment</link>" + section for the list of cross-toolchain environment variables + established by the script. </para> <para> @@ -99,7 +103,7 @@ "poky-linux". Here is an example that sources a script from the default ADT installation directory that uses the - 32-bit Intel x86 Architecture and using the + 32-bit Intel x86 Architecture and the &DISTRO_NAME; Yocto Project release: <literallayout class='monospaced'> $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux @@ -128,7 +132,11 @@ $ automake -a </literallayout></para></listitem> <listitem><para><emphasis>Cross-compile the project:</emphasis> - This command compiles the project using the cross-compiler: + This command compiles the project using the cross-compiler. + The + <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS'><filename>CONFIGURE_FLAGS</filename></ulink> + environment variable provides the minimal arguments for + GNU configure: <literallayout class='monospaced'> $ ./configure ${CONFIGURE_FLAGS} </literallayout></para></listitem> @@ -174,16 +182,12 @@ is <filename>armv5te-poky-linux-gnueabi</filename>. You will notice that the name of the script is <filename>environment-setup-armv5te-poky-linux-gnueabi</filename>. - Thus, the following command works: + Thus, the following command works to update your project and + rebuild it using the appropriate cross-toolchain tools: <literallayout class='monospaced'> $ ./configure --host=armv5te-poky-linux-gnueabi \ - --with-libtool-sysroot=<replaceable>sysroot-dir</replaceable> + --with-libtool-sysroot=<replaceable>sysroot_dir</replaceable> </literallayout> - </para> - - <para> - This single command updates your project and rebuilds it using the appropriate - cross-toolchain tools. <note> If the <filename>configure</filename> script results in problems recognizing the <filename>--with-libtool-sysroot=</filename><replaceable>sysroot-dir</replaceable> option, @@ -206,15 +210,28 @@ <title>Makefile-Based Projects</title> <para> - For a Makefile-based project, you use the cross-toolchain by making sure - the tools are used. - You can do this as follows: + For Makefile-based projects, the cross-toolchain environment + variables established by running the cross-toolchain environment + setup script override any settings you might have in your + <filename>Makefile</filename>. + For example, if you had settings such as the following in your + <filename>Makefile</filename>, the environment variables defined + by the script would override them: <literallayout class='monospaced'> - CC=arm-poky-linux-gnueabi-gcc - LD=arm-poky-linux-gnueabi-ld - CFLAGS=”${CFLAGS} --sysroot=<sysroot-dir>” - CXXFLAGS=”${CXXFLAGS} --sysroot=<sysroot-dir>” + <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'>CC</ulink>=arm-poky-linux-gnueabi-gcc + <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'>LD</ulink>=arm-poky-linux-gnueabi-ld + <ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'>CFLAGS</ulink>=”${CFLAGS} --sysroot=<sysroot-dir>” + <ulink url='&YOCTO_DOCS_REF_URL;#var-CXXFLAGS'>CXXFLAGS</ulink>=”${CXXFLAGS} --sysroot=<sysroot-dir>” </literallayout> + Consequently, you should not set variables like + <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink> + and + <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink> + in your <filename>Makefile</filename>. + For the list of variables set up by the cross-toolchain environment + setup script, see the + "<link linkend='setting-up-the-cross-development-environment'>Setting Up the Cross-Development Environment</link>" + section. </para> </section> diff --git a/documentation/adt-manual/adt-intro.xml b/documentation/adt-manual/adt-intro.xml index ed13a23a5f..597c7120ba 100644 --- a/documentation/adt-manual/adt-intro.xml +++ b/documentation/adt-manual/adt-intro.xml @@ -16,7 +16,8 @@ Fundamentally, the ADT consists of the following: <itemizedlist> <listitem><para>An architecture-specific cross-toolchain and matching - sysroot both built by the OpenEmbedded build system. + sysroot both built by the + <ulink url='&YOCTO_DOCS_DEV_URL;#build-system-term'>OpenEmbedded build system</ulink>. The toolchain and sysroot are based on a <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> configuration and extensions, @@ -126,7 +127,7 @@ <title>User-Space Tools</title> <para> - User-space tools are included as part of the distribution. + User-space tools are included as part of the Yocto Project. You will find these tools helpful during development. The tools include LatencyTOP, PowerTOP, OProfile, Perf, SystemTap, and Lttng-ust. These tools are common development tools for the Linux platform. 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-eclipse-customization.xsl b/documentation/adt-manual/adt-manual-eclipse-customization.xsl index d16ffbb68e..60791bfcd4 100644 --- a/documentation/adt-manual/adt-manual-eclipse-customization.xsl +++ b/documentation/adt-manual/adt-manual-eclipse-customization.xsl @@ -6,7 +6,7 @@ version="1.0"> <xsl:import - href="http://docbook.sourceforge.net/release/xsl/current/eclipse/eclipse3.xsl" /> + href="http://docbook.sourceforge.net/release/xsl/1.76.1/eclipse/eclipse3.xsl" /> <xsl:param name="chunker.output.indent" select="'yes'"/> <xsl:param name="chunk.quietly" select="1"/> diff --git a/documentation/adt-manual/adt-manual-intro.xml b/documentation/adt-manual/adt-manual-intro.xml index fccacc4ba4..034fdff609 100644 --- a/documentation/adt-manual/adt-manual-intro.xml +++ b/documentation/adt-manual/adt-manual-intro.xml @@ -18,9 +18,9 @@ This manual describes the ADT and how you can configure and install it, how to access and use the cross-development toolchains, how to customize the development packages installation, - how to use command line development for both Autotools-based and Makefile-based projects, - and an introduction to the <trademark class='trade'>Eclipse</trademark> IDE - Yocto Plug-in. + how to use command-line development for both Autotools-based and + Makefile-based projects, and an introduction to the + <trademark class='trade'>Eclipse</trademark> IDE Yocto Plug-in. <note> The ADT is distribution-neutral and does not require the Yocto Project reference distribution, which is called Poky. diff --git a/documentation/adt-manual/adt-manual.xml b/documentation/adt-manual/adt-manual.xml index 15ab24984d..ee2b44f09f 100644 --- a/documentation/adt-manual/adt-manual.xml +++ b/documentation/adt-manual/adt-manual.xml @@ -82,9 +82,9 @@ <revremark>Released with the Yocto Project 1.7 Release.</revremark> </revision> <revision> - <revnumber>1.7.1</revnumber> - <date>January 2015</date> - <revremark>Released with the Yocto Project 1.7.1 Release.</revremark> + <revnumber>1.8</revnumber> + <date>April 2015</date> + <revremark>Released with the Yocto Project 1.8 Release.</revremark> </revision> </revhistory> diff --git a/documentation/adt-manual/adt-package.xml b/documentation/adt-manual/adt-package.xml index 5c3196ea91..f3ffa06e4e 100644 --- a/documentation/adt-manual/adt-package.xml +++ b/documentation/adt-manual/adt-package.xml @@ -51,7 +51,8 @@ The first value you choose for the variable specifies the package file format for the root filesystem at sysroot. Additional values specify additional formats for convenience or testing. - See the configuration file for details. + See the <filename>conf/local.conf</filename> configuration file for + details. </para> <note> @@ -77,7 +78,7 @@ </para> <para> - Next, source the environment setup script found in the + Next, source the cross-toolchain 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 <replaceable>sysroot_dir</replaceable>. diff --git a/documentation/adt-manual/adt-prepare.xml b/documentation/adt-manual/adt-prepare.xml index 7faf39b9e2..3d0cfd42fb 100644 --- a/documentation/adt-manual/adt-prepare.xml +++ b/documentation/adt-manual/adt-prepare.xml @@ -17,24 +17,34 @@ <title>Installing the ADT and Toolchains</title> <para> - The following list describes installation methods that set up varying degrees of tool - availability on your system. + The following list describes installation methods that set up varying + degrees of tool availability on your system. Regardless of the installation method you choose, you must <filename>source</filename> the cross-toolchain - environment setup script before you use a toolchain. - See the "<link linkend='setting-up-the-cross-development-environment'>Setting Up the - Cross-Development Environment</link>" section for more information. + environment setup script, which establishes several key + environment variables, before you use a toolchain. + See the + "<link linkend='setting-up-the-cross-development-environment'>Setting Up the Cross-Development Environment</link>" + section for more information. </para> <note> - <para>Avoid mixing installation methods when installing toolchains for different architectures. - For example, avoid using the ADT Installer to install some toolchains and then hand-installing - cross-development toolchains by running the toolchain installer for different architectures. - Mixing installation methods can result in situations where the ADT Installer becomes - unreliable and might not install the toolchain.</para> - <para>If you must mix installation methods, you might avoid problems by deleting - <filename>/var/lib/opkg</filename>, thus purging the <filename>opkg</filename> package - metadata</para> + <para> + Avoid mixing installation methods when installing toolchains for + different architectures. + For example, avoid using the ADT Installer to install some + toolchains and then hand-installing cross-development toolchains + by running the toolchain installer for different architectures. + Mixing installation methods can result in situations where the + ADT Installer becomes unreliable and might not install the + toolchain. + </para> + + <para> + If you must mix installation methods, you might avoid problems by + deleting <filename>/var/lib/opkg</filename>, thus purging the + <filename>opkg</filename> package metadata. + </para> </note> <para> @@ -115,6 +125,10 @@ sure to make sure your <filename>local.conf</filename> file is properly configured. + See the + "<ulink url='&YOCTO_DOCS_REF_URL;#user-configuration'>User Configuration</ulink>" + section in the Yocto Project Reference Manual for + general configuration information. </note> <literallayout class='monospaced'> $ cd ~ @@ -276,7 +290,7 @@ target, go into the <filename>x86_64</filename> folder and download the following installer: <literallayout class='monospaced'> - poky-eglibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh + poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh </literallayout></para></listitem> <listitem><para>Build your own toolchain installer. For cases where you cannot use an installer @@ -296,7 +310,7 @@ The example assumes the toolchain installer is located in <filename>~/Downloads/</filename>. <literallayout class='monospaced'> - $ ~/Downloads/poky-eglibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh + $ ~/Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh </literallayout> The first thing the installer prompts you for is the directory into which you want to install the toolchain. @@ -406,6 +420,32 @@ <literallayout class='monospaced'> &YOCTO_ADTPATH_DIR;/environment-setup-x86_64-poky-linux </literallayout> + When you run the setup script, many environment variables are + defined: + <literallayout class='monospaced'> + <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKTARGETSYSROOT'><filename>SDKTARGETSYSROOT</filename></ulink> - The path to the sysroot used for cross-compilation + <ulink url='&YOCTO_DOCS_REF_URL;#var-PKG_CONFIG_PATH'><filename>PKG_CONFIG_PATH</filename></ulink> - The path to the target pkg-config files + <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIG_SITE'><filename>CONFIG_SITE</filename></ulink> - A GNU autoconf site file preconfigured for the target + <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink> - The minimal command and arguments to run the C compiler + <ulink url='&YOCTO_DOCS_REF_URL;#var-CXX'><filename>CXX</filename></ulink> - The minimal command and arguments to run the C++ compiler + <ulink url='&YOCTO_DOCS_REF_URL;#var-CPP'><filename>CPP</filename></ulink> - The minimal command and arguments to run the C preprocessor + <ulink url='&YOCTO_DOCS_REF_URL;#var-AS'><filename>AS</filename></ulink> - The minimal command and arguments to run the assembler + <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink> - The minimal command and arguments to run the linker + <ulink url='&YOCTO_DOCS_REF_URL;#var-GDB'><filename>GDB</filename></ulink> - The minimal command and arguments to run the GNU Debugger + <ulink url='&YOCTO_DOCS_REF_URL;#var-STRIP'><filename>STRIP</filename></ulink> - The minimal command and arguments to run 'strip', which strips symbols + <ulink url='&YOCTO_DOCS_REF_URL;#var-RANLIB'><filename>RANLIB</filename></ulink> - The minimal command and arguments to run 'ranlib' + <ulink url='&YOCTO_DOCS_REF_URL;#var-OBJCOPY'><filename>OBJCOPY</filename></ulink> - The minimal command and arguments to run 'objcopy' + <ulink url='&YOCTO_DOCS_REF_URL;#var-OBJDUMP'><filename>OBJDUMP</filename></ulink> - The minimal command and arguments to run 'objdump' + <ulink url='&YOCTO_DOCS_REF_URL;#var-AR'><filename>AR</filename></ulink> - The minimal command and arguments to run 'ar' + <ulink url='&YOCTO_DOCS_REF_URL;#var-NM'><filename>NM</filename></ulink> - The minimal command and arguments to run 'nm' + <ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></ulink> - The toolchain binary prefix for the target tools + <ulink url='&YOCTO_DOCS_REF_URL;#var-CROSS_COMPILE'><filename>CROSS_COMPILE</filename></ulink> - The toolchain binary prefix for the target tools + <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIGURE_FLAGS'><filename>CONFIGURE_FLAGS</filename></ulink> - The minimal arguments for GNU configure + <ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'><filename>CFLAGS</filename></ulink> - Suggested C flags + <ulink url='&YOCTO_DOCS_REF_URL;#var-CXXFLAGS'><filename>CXXFLAGS</filename></ulink> - Suggested C++ flags + <ulink url='&YOCTO_DOCS_REF_URL;#var-LDFLAGS'><filename>LDFLAGS</filename></ulink> - Suggested linker flags when you use CC to link + <ulink url='&YOCTO_DOCS_REF_URL;#var-CPPFLAGS'><filename>CPPFLAGS</filename></ulink> - Suggested preprocessor flags + </literallayout> </para> </section> @@ -539,7 +579,8 @@ <para> To extract the root filesystem, first <filename>source</filename> - the cross-development environment setup script. + the cross-development environment setup script to establish + necessary environment variables. If you built the toolchain in the Build Directory, you will find the toolchain environment script in the <filename>tmp</filename> directory. @@ -616,7 +657,10 @@ hardware can be passed to <filename>gcc</filename> as a set of compiler options. Those options are set up by the environment script and - contained in variables like CC and LD. + contained in variables such as + <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink> + and + <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink>. This reduces the space needed for the tools. Understand, however, that a sysroot is still needed for every target since those binaries are target-specific. @@ -656,15 +700,54 @@ <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink> variable inside your <filename>local.conf</filename> file to install the appropriate library packages. - Following is an example using <filename>eglibc</filename> static + Following is an example using <filename>glibc</filename> static development libraries: <literallayout class='monospaced'> - IMAGE_INSTALL_append = " eglibc-staticdev" + IMAGE_INSTALL_append = " glibc-staticdev" </literallayout> </note> </para> </section> +<section id='optionally-using-an-external-toolchain'> + <title>Optionally Using an External Toolchain</title> + + <para> + You might want to use an external toolchain as part of your + development. + If this is the case, the fundamental steps you need to accomplish + are as follows: + <itemizedlist> + <listitem><para> + Understand where the installed toolchain resides. + For cases where you need to build the external toolchain, you + would need to take separate steps to build and install the + toolchain. + </para></listitem> + <listitem><para> + Make sure you add the layer that contains the toolchain to + your <filename>bblayers.conf</filename> file through the + <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink> + variable. + </para></listitem> + <listitem><para> + Set the + <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNAL_TOOLCHAIN'><filename>EXTERNAL_TOOLCHAIN</filename></ulink> + variable in your <filename>local.conf</filename> file + to the location in which you installed the toolchain. + </para></listitem> + </itemizedlist> + A good example of an external toolchain used with the Yocto Project + is <trademark class='registered'>Mentor Graphics</trademark> + Sourcery G++ Toolchain. + You can see information on how to use that particular layer in the + <filename>README</filename> file at + <ulink url='http://github.com/MentorEmbedded/meta-sourcery/'></ulink>. + You can find further information by reading about the + <ulink url='&YOCTO_DOCS_REF_URL;#var-TCMODE'><filename>TCMODE</filename></ulink> + variable in the Yocto Project Reference Manual's variable glossary. + </para> +</section> </chapter> <!-- vim: expandtab tw=80 ts=4 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-eclipse-customization.xsl b/documentation/bsp-guide/bsp-guide-eclipse-customization.xsl index 1c80bee1cf..5de5652362 100644 --- a/documentation/bsp-guide/bsp-guide-eclipse-customization.xsl +++ b/documentation/bsp-guide/bsp-guide-eclipse-customization.xsl @@ -6,7 +6,7 @@ version="1.0"> <xsl:import - href="http://docbook.sourceforge.net/release/xsl/current/eclipse/eclipse3.xsl" /> + href="http://docbook.sourceforge.net/release/xsl/1.76.1/eclipse/eclipse3.xsl" /> <xsl:param name="chunker.output.indent" select="'yes'"/> <xsl:param name="chunk.quietly" select="1"/> diff --git a/documentation/bsp-guide/bsp-guide.xml b/documentation/bsp-guide/bsp-guide.xml index d5a8d3b70a..7c74707fd4 100644 --- a/documentation/bsp-guide/bsp-guide.xml +++ b/documentation/bsp-guide/bsp-guide.xml @@ -94,9 +94,9 @@ <revremark>Released with the Yocto Project 1.7 Release.</revremark> </revision> <revision> - <revnumber>1.7.1</revnumber> - <date>January 2015</date> - <revremark>Released with the Yocto Project 1.7.1 Release.</revremark> + <revnumber>1.8</revnumber> + <date>April 2015</date> + <revremark>Released with the Yocto Project 1.8 Release.</revremark> </revision> </revhistory> diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml index d4850234d1..ec39ec9b31 100644 --- a/documentation/bsp-guide/bsp.xml +++ b/documentation/bsp-guide/bsp.xml @@ -35,12 +35,20 @@ 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-<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. + <note><title>Tip</title> + Because the BSP layer naming convention is well-established, + it is advisable to follow it when creating layers. + Technically speaking, a BSP layer name does not need to + start with <filename>meta-</filename>. + However, you might run into situations where obscure + scripts assume this convention. + </note> </para> <para> @@ -58,7 +66,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> @@ -93,11 +101,6 @@ /usr/local/src/yocto/meta-yocto-bsp \ /usr/local/src/yocto/meta-mylayer \ " - - BBLAYERS_NON_REMOVABLE ?= " \ - /usr/local/src/yocto/meta \ - /usr/local/src/yocto/meta-yocto \ - " </literallayout> </para> @@ -115,8 +118,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 +135,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> @@ -190,37 +194,33 @@ </para> <para> - Below is an example of the Crown Bay BSP: + Below is an example of the eMenlow BSP: <literallayout class='monospaced'> - meta-crownbay/COPYING.MIT - meta-crownbay/README - meta-crownbay/README.sources - meta-crownbay/binary/ - 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/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-emenlow/COPYING.MIT + meta-emenlow/README + meta-emenlow/README.sources + meta-emenlow/binary/ + meta-emenlow/conf/ + meta-emenlow/conf/layer.conf + meta-emenlow/conf/machine/ + meta-emenlow/conf/machine/emenlow-noemgd.conf + meta-emenlow/recipes-bsp/ + meta-emenlow/recipes-bsp/formfactor/ + meta-emenlow/recipes-bsp/formfactor/formfactor/ + meta-emenlow/recipes-bsp/formfactor/formfactor_0.0.bbappend + meta-emenlow/recipes-bsp/formfactor/formfactor/emenlow-noemgd/ + meta-emenlow/recipes-bsp/formfactor/formfactor/emenlow-noemgd/machconfig + meta-emenlow/recipes-graphics/ + meta-emenlow/recipes-graphics/xorg-xserver + meta-emenlow/recipes-graphics/xorg-xserver/xserver-xf86-config + meta-emenlow/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend + meta-emenlow/recipes-graphics/xorg-xserver/xserver-xf86-config/emenlow-noemgd + meta-emenlow/recipes-graphics/xorg-xserver/xserver-xf86-config/emenlow-noemgd/xorg.config + meta-emenlow/recipes-kernel/ + meta-emenlow/recipes-kernel/linux/ + meta-emenlow/recipes-kernel/linux/linux-yocto-dev.bbappend + meta-emenlow/recipes-kernel/linux/linux-yocto_3.14.bbappend </literallayout> </para> @@ -241,7 +241,7 @@ <para> These optional files satisfy licensing requirements for the BSP. The type or types of files here can vary depending on the licensing requirements. - For example, in the Crown Bay BSP all licensing requirements are handled with the + For example, in the eMenlow BSP all licensing requirements are handled with the <filename>COPYING.MIT</filename> file. </para> @@ -285,12 +285,21 @@ </para> <para> - This file provides information on where to locate the BSP source files. - For example, information provides where to find the sources that comprise - the images shipped with the BSP. - Information is also included to help you find the + This file provides information on where to locate the BSP + source files used to build the images (if any) that reside in + <filename>meta-<replaceable>bsp_name</replaceable>/binary</filename>. + Images in the <filename>binary</filename> would be images + released with the BSP. + The information in the <filename>README.sources</filename> + file also helps you find the <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> used to generate the images that ship with the BSP. + <note> + If the BSP's <filename>binary</filename> directory is + missing or the directory has no images, an existing + <filename>README.sources</filename> file is + meaningless. + </note> </para> </section> @@ -304,21 +313,26 @@ </para> <para> - This optional area contains useful pre-built kernels and user-space filesystem - images appropriate to the target system. - This directory typically contains graphical (e.g. Sato) and minimal live images - when the BSP tarball has been created and made available in the + This optional area contains useful pre-built kernels and + user-space filesystem images released with the BSP that are + appropriate to the target system. + This directory typically contains graphical (e.g. Sato) and + minimal live images when the BSP tarball has been created and + made available in the <ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink> website. - You can use these kernels and images to get a system running and quickly get started - on development tasks. + You can use these kernels and images to get a system running + and quickly get started on development tasks. </para> <para> - The exact types of binaries present are highly hardware-dependent. - 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. + The exact types of binaries present are highly + hardware-dependent. + The <filename>README</filename> file should be present in the + BSP Layer and it will explain how to use the images with the + target hardware. + Additionally, the <filename>README.sources</filename> file + should be present to locate the sources used to build the + images and provide information on the Metadata. </para> </section> @@ -351,19 +365,30 @@ 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> <para> To illustrate the string substitutions, here are the corresponding statements - from the Crown Bay <filename>conf/layer.conf</filename> file: + from the eEmenlow <filename>conf/layer.conf</filename> file: <literallayout class='monospaced'> - BBFILE_COLLECTIONS += "crownbay" - BBFILE_PATTERN_crownbay = "^${LAYERDIR}/" - BBFILE_PRIORITY_crownbay = "6" + # We have a conf and classes directory, add to BBPATH + BBPATH .= ":${LAYERDIR}" + + # We have recipes-* directories, add to BBFILES + BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ + ${LAYERDIR}/recipes-*/*/*.bbappend" + + BBFILE_COLLECTIONS += "emenlow" + BBFILE_PATTERN_emenlow := "^${LAYERDIR}/" + BBFILE_PRIORITY_emenlow = "6" + + LAYERDEPENDS_emenlow = "intel" </literallayout> </para> @@ -408,11 +433,10 @@ </para> <para> - This <filename>crownbay.conf</filename> file could also include - a hardware "tuning" file that is commonly used to - define the package architecture and specify - optimization flags, which are carefully chosen to give best - performance on a given processor. + This configuration file could also include a hardware "tuning" + file that is commonly used to define the package architecture + and specify optimization flags, which are carefully chosen + to give best performance on a given processor. </para> <para> @@ -424,13 +448,15 @@ </para> <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 + To use an include file, you simply include them in the + machine configuration file. + For example, the eEmenlow BSP + <filename>emenlow-noemgd.conf</filename> contains the following statements: <literallayout class='monospaced'> require conf/machine/include/intel-core2-32-common.inc + require conf/machine/include/intel-common-pkgarch.inc require conf/machine/include/meta-intel.inc - require conf/machine/include/meta-intel-emgd.inc </literallayout> </para> </section> @@ -445,20 +471,23 @@ </para> <para> - This optional directory contains miscellaneous recipe files for the BSP. + This optional directory contains miscellaneous recipe files for + the BSP. Most notably would be the formfactor files. - For example, in the Crown Bay BSP there is the + For example, in the eMenlow BSP there is the <filename>formfactor_0.0.bbappend</filename> file, which is an 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: + Furthermore, there are machine-specific settings used during + the build that are defined by the + <filename>machconfig</filename> file further down in the + directory. + In the eMenlow 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 + # Assume a USB mouse and keyboard are connected + HAVE_TOUCHSCREEN=0 + HAVE_KEYBOARD=1 </literallayout> </para> @@ -484,14 +513,19 @@ <para> 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): + All files that are needed for the BSP to support a display are + kept here. + 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> @@ -501,7 +535,7 @@ <para> You can find these files in the BSP Layer at: <literallayout class='monospaced'> - meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux/linux-yocto_*.bbappend + meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux/linux-yocto*.bbappend </literallayout> </para> @@ -517,28 +551,28 @@ 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 + Suppose you are using the <filename>linux-yocto_3.14.bb</filename> recipe to build the kernel. In other words, you have selected the kernel in your <replaceable>bsp_name</replaceable><filename>.conf</filename> file by adding these types of statements: <literallayout class='monospaced'> PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" - PREFERRED_VERSION_linux-yocto ?= "3.10%" + PREFERRED_VERSION_linux-yocto ?= "3.14%" </literallayout> <note> When the preferred provider is assumed by default, the <filename>PREFERRED_PROVIDER</filename> statement does not appear in the <replaceable>bsp_name</replaceable><filename>.conf</filename> file. </note> - You would use the <filename>linux-yocto_3.10.bbappend</filename> file to append + You would use the <filename>linux-yocto_3.14.bbappend</filename> file to append specific BSP settings to the kernel, thus configuring the kernel for your particular BSP. </para> <para> - As an example, look at the existing Crown Bay BSP. + As an example, look at the existing eMenlow BSP. The append file used is: <literallayout class='monospaced'> - meta-crownbay/recipes-kernel/linux/linux-yocto_3.10.bbappend + meta-emenlow/recipes-kernel/linux/linux-yocto_3.14.bbappend </literallayout> The following listing shows the file. Be aware that the actual commit ID strings in this example listing might be different @@ -547,50 +581,37 @@ <literallayout class='monospaced'> FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" + COMPATIBLE_MACHINE_emenlow-noemgd = "emenlow-noemgd" + KMACHINE_emenlow-noemgd = "emenlow" + KBRANCH_emenlow-noemgd = "standard/base" + KERNEL_FEATURES_append_emenlow-noemgd = " features/drm-gma500/drm-gma500.scc" - 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_emenlow-noemgd = "3.14.19" + SRCREV_machine_emenlow-noemgd = "902f34d36102a4b2008b776ecae686f80d307e12" + SRCREV_meta_emenlow-noemgd = "28e39741b8b3018334021d981369d3fd61f18f5b" </literallayout> - This append file contains statements used to support the Crown Bay BSP. + This append file contains statements used to support the + eMenlow BSP. The file defines machines using the <ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink> variable and uses the - <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink> variable to - ensure the machine name used by the OpenEmbedded build system maps to the - machine name used by the Linux Yocto kernel. + <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink> + variable to ensure the machine name used by the OpenEmbedded + build system maps to the machine name used by the Linux Yocto + kernel. The file also uses the optional - <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink> variable - to ensure the build process uses the <filename>standard/crownbay</filename> - kernel branch. + <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink> + variable to ensure the build process uses the + <filename>standard/emenlow</filename> kernel branch. 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. Intel GMA-500 DRM Driver 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. + <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 + eMenlow BSP. </para> <para> @@ -747,7 +768,7 @@ recipes. The recipes themselves should follow the general guidelines for recipes used in the Yocto Project found in the - "<ulink url='https://wiki.yoctoproject.org/wiki/Recipe_%26_Patch_Style_Guide'>Yocto Recipe and Patch Style Guide</ulink>". + "<ulink url='http://openembedded.org/wiki/Styleguide'>OpenEmbedded Style Guide</ulink>". </para></listitem> <listitem><para><emphasis>License File:</emphasis> You must include a license file in the @@ -910,8 +931,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 +948,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 +963,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 @@ -1242,12 +1280,13 @@ <literallayout class='monospaced'> $ yocto-bsp list karch Architectures available: + qemu + mips64 powerpc - i386 x86_64 arm - qemu mips + i386 </literallayout> </para> @@ -1281,38 +1320,35 @@ $ yocto-bsp create myarm qemu Checking basic git connectivity... Done. - Which qemu architecture would you like to use? [default: i386] - 1) i386 (32-bit) - 2) x86_64 (64-bit) - 3) ARM (32-bit) - 4) PowerPC (32-bit) - 5) MIPS (32-bit) + 1) i386 (32-bit) + 2) x86_64 (64-bit) + 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.19) 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.19.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 - 13) standard/qemuppc - 14) standard/routerstationpro - 15) standard/sys940x + 1) standard/arm-versatile-926ejs + 2) standard/base + 3) standard/beagleboard + 4) standard/beaglebone + 5) standard/ck + 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 1 Would you like SMP support? (y/n) [default: y] Does your BSP have a touchscreen? (y/n) [default: n] Does your BSP have a keyboard? (y/n) [default: y] - New qemu BSP created in meta-myarm </literallayout> Take a closer look at the example now: @@ -1322,7 +1358,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.19 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> @@ -1400,13 +1436,10 @@ Recall that the easiest way to see exactly what sub-commands are available is to use the <filename>yocto-kernel</filename> built-in help as follows: <literallayout class='monospaced'> - $ yocto-kernel + $ yocto-kernel --help Usage: - Modify and list Yocto BSP kernel config items and patches. - usage: yocto-kernel [--version] [--help] COMMAND [ARGS] - Current 'yocto-kernel' commands are: config list List the modifiable set of bare kernel config options for a BSP config add Add or modify bare kernel config options for a BSP @@ -1421,11 +1454,7 @@ feature describe Describe a particular feature feature create Create a new BSP-local feature feature destroy Remove a BSP-local feature - See 'yocto-kernel help COMMAND' for more information on a specific command. - - - Options: --version show program's version number and exit -h, --help show this help message and exit @@ -1440,11 +1469,11 @@ <literallayout class='monospaced'> $ yocto-kernel patch add myarm ~/test.patch Added patches: - test.patch + test.patch $ yocto-kernel patch add myarm ~/yocto-testmod.patch Added patches: - yocto-testmod.patch + yocto-testmod.patch </literallayout> <note>Although the previous example adds patches one at a time, it is possible to add multiple patches at the same time.</note> @@ -1457,8 +1486,8 @@ <literallayout class='monospaced'> $ yocto-kernel patch list myarm The current set of machine-specific patches for myarm is: - 1) test.patch - 2) yocto-testmod.patch + 1) test.patch + 2) yocto-testmod.patch </literallayout> </para> @@ -1469,11 +1498,11 @@ <literallayout class='monospaced'> $ yocto-kernel patch rm myarm Specify the patches to remove: - 1) test.patch - 2) yocto-testmod.patch + 1) test.patch + 2) yocto-testmod.patch 1 Removed patches: - test.patch + test.patch </literallayout> </para> @@ -1483,7 +1512,7 @@ <literallayout class='monospaced'> $ yocto-kernel patch list myarm The current set of machine-specific patches for myarm is: - 1) yocto-testmod.patch + 1) yocto-testmod.patch </literallayout> </para> @@ -1494,15 +1523,17 @@ <filename>myarm</filename> BSP: <literallayout class='monospaced'> $ yocto-kernel config add myarm CONFIG_MISC_DEVICES=y - Added items: - CONFIG_MISC_DEVICES=y + Added item: + CONFIG_MISC_DEVICES=y $ yocto-kernel config add myarm CONFIG_YOCTO_TESTMOD=y - Added items: - CONFIG_YOCTO_TESTMOD=y + Added item: + CONFIG_YOCTO_TESTMOD=y </literallayout> - <note>Although the previous example adds config items one at a time, it is possible - to add multiple config items at the same time.</note> + <note> + Although the previous example adds config items one at a time, it is possible + to add multiple config items at the same time. + </note> </para> <para> diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index 524c607855..7a28176ce0 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -273,29 +273,17 @@ the included file, use the path relative to the original layer directory to refer to the file. For example, use - <filename>require recipes-core/somepackage/somefile.inc</filename> - instead of <filename>require somefile.inc</filename>. + <filename>require recipes-core/</filename><replaceable>package</replaceable><filename>/</filename><replaceable>file</replaceable><filename>.inc</filename> + instead of <filename>require </filename><replaceable>file</replaceable><filename>.inc</filename>. If you're finding you have to overlay the include file, it could indicate a deficiency in the include file in the layer to which it originally belongs. - If this is the case, you need to address that deficiency - instead of overlaying the include file. - </para> - - <para> - For example, consider how support plug-ins for the Qt 4 - database are configured. - The Source Directory does not have MySQL or PostgreSQL. - However, OpenEmbedded's layer <filename>meta-oe</filename> - does. - Consequently, <filename>meta-oe</filename> uses - append files to modify the - <filename>QT_SQL_DRIVER_FLAGS</filename> variable to - enable the appropriate plug-ins. - This variable was added to the <filename>qt4.inc</filename> - include file in the Source Directory specifically to allow - the <filename>meta-oe</filename> layer to be able to control - which plug-ins are built. + If this is the case, you should try to address that + deficiency instead of overlaying the include file. + For example, you could address this by getting the + maintainer of the include file to add a variable or + variables to make it easy to override the parts needing + to be overridden. </para> </section> @@ -460,11 +448,6 @@ $HOME/poky/meta-yocto-bsp \ $HOME/poky/meta-mylayer \ " - - BBLAYERS_NON_REMOVABLE ?= " \ - $HOME/poky/meta \ - $HOME/poky/meta-yocto \ - " </literallayout> </para> @@ -567,8 +550,8 @@ <para> Following is the append file, which is named <filename>formfactor_0.0.bbappend</filename> and is from the - Crown Bay BSP Layer named - <filename>meta-intel/meta-crownbay</filename>. + Emenlow BSP Layer named + <filename>meta-intel/meta-emenlow</filename>. The file is in <filename>recipes-bsp/formfactor</filename>: <literallayout class='monospaced'> FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" @@ -594,7 +577,7 @@ which resolves to a directory named <filename>formfactor</filename> in the same directory in which the append file resides (i.e. - <filename>meta-intel/meta-crownbay/recipes-bsp/formfactor/formfactor</filename>. + <filename>meta-intel/meta-emenlow/recipes-bsp/formfactor/formfactor</filename>. This implies that you must have the supporting directory structure set up that will contain any files or patches you will be including from the layer. @@ -611,16 +594,18 @@ BitBake automatically defines the <filename>THISDIR</filename> variable. You should never set this variable yourself. - Using "_prepend" ensures your path will - be searched prior to other paths in the final list. + Using "_prepend" as part of the + <filename>FILESEXTRAPATHS</filename> ensures your path + will be searched prior to other paths in the final + list. </para> <para> Also, not all append files add extra files. Many append files simply exist to add build options (e.g. <filename>systemd</filename>). - For these cases, it is not necessary to use the - "_prepend" part of the statement. + For these cases, your append file would not even + use the <filename>FILESEXTRAPATHS</filename> statement. </para> </note> </para> @@ -705,6 +690,12 @@ Lists dependency relationships between recipes that cross layer boundaries. </para></listitem> + <listitem><para><filename><emphasis>add-layer:</emphasis></filename> + Adds a layer to <filename>bblayers.conf</filename>. + </para></listitem> + <listitem><para><filename><emphasis>remove-layer:</emphasis></filename> + Removes a layer from <filename>bblayers.conf</filename> + </para></listitem> <listitem><para><filename><emphasis>flatten:</emphasis></filename> Flattens the layer configuration into a separate output directory. @@ -745,13 +736,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: @@ -759,7 +750,7 @@ ... DESCRIPTION = "Customized utility" ... - EXTRA_OECONF = "‐‐enable-something ‐‐enable-somethingelse" + EXTRA_OECONF = "--enable-something --enable-somethingelse" ... </literallayout></para></listitem> </itemizedlist></para></listitem> @@ -883,11 +874,6 @@ /usr/local/src/yocto/meta-yocto-bsp \ /usr/local/src/yocto/meta-mylayer \ " - - BBLAYERS_NON_REMOVABLE ?= " \ - /usr/local/src/yocto/meta \ - /usr/local/src/yocto/meta-yocto \ - " </literallayout> Adding the layer to this file enables the build system to locate the layer during the build. @@ -990,11 +976,20 @@ <para> To understand how these features work, the best reference is <filename>meta/classes/core-image.bbclass</filename>. + This class lists out the available + <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink> + of which most map to package groups while some, such as + <filename>debug-tweaks</filename> and + <filename>read-only-rootfs</filename>, resolve as general + configuration settings. + </para> + + <para> In summary, the file looks at the contents of the <filename>IMAGE_FEATURES</filename> variable and then maps - those contents into a set of package groups. + or configures the feature accordingly. Based on this information, the build system automatically - adds the appropriate packages to the + adds the appropriate packages or configurations to the <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink> variable. Effectively, you are enabling extra features by extending the @@ -1071,7 +1066,7 @@ <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'>IMAGE_INSTALL</ulink></filename> variable. You must use the OpenEmbedded notation and not the Debian notation for the names - (e.g. <filename>eglibc-dev</filename> instead of <filename>libc6-dev</filename>). + (e.g. <filename>glibc-dev</filename> instead of <filename>libc6-dev</filename>). </para> <para> @@ -1094,18 +1089,27 @@ an image is to create a custom package group recipe that is used to build the image or images. A good example of a package group recipe is - <filename>meta/recipes-core/packagegroups/packagegroup-core-boot.bb</filename>. - The + <filename>meta/recipes-core/packagegroups/packagegroup-base.bb</filename>. + </para> + + <para> + If you examine that recipe, you see that the <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'>PACKAGES</ulink></filename> - variable lists the package group packages you wish to produce. - <filename>inherit packagegroup</filename> sets appropriate - default values and automatically adds <filename>-dev</filename>, - <filename>-dbg</filename>, and <filename>-ptest</filename> - complementary packages for every package specified in - <filename>PACKAGES</filename>. - Note that the inherit line should be towards - the top of the recipe, certainly before you set - <filename>PACKAGES</filename>. + variable lists the package group packages to produce. + The <filename>inherit packagegroup</filename> statement + sets appropriate default values and automatically adds + <filename>-dev</filename>, <filename>-dbg</filename>, and + <filename>-ptest</filename> complementary packages for each + package specified in the <filename>PACKAGES</filename> + statement. + <note> + The <filename>inherit packages</filename> should be + located near the top of the recipe, certainly before + the <filename>PACKAGES</filename> statement. + </note> + </para> + + <para> For each package you specify in <filename>PACKAGES</filename>, you can use <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'>RDEPENDS</ulink></filename> @@ -1113,7 +1117,13 @@ <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'>RRECOMMENDS</ulink></filename> entries to provide a list of packages the parent task package should contain. - Following is an example: + You can see examples of these further down in the + <filename>packagegroup-base.bb</filename> recipe. + </para> + + <para> + Here is a short, fabricated example showing the same basic + pieces: <literallayout class='monospaced'> DESCRIPTION = "My Custom Package Groups" @@ -1132,8 +1142,7 @@ RDEPENDS_packagegroup-custom-tools = "\ oprofile \ oprofileui-server \ - lttng-control \ - lttng-viewer" + lttng-tools" RRECOMMENDS_packagegroup-custom-tools = "\ kernel-module-oprofile" @@ -1151,6 +1160,63 @@ For other forms of image dependencies see the other areas of this section. </para> </section> + + <section id='usingpoky-extend-customimage-image-name'> + <title>Customizing an Image Hostname</title> + + <para> + By default, the configured hostname (i.e. + <filename>/etc/hostname</filename>) in an image is the + same as the machine name. + For example, if + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> + equals "qemux86", the configured hostname written to + <filename>/etc/hostname</filename> is "qemux86". + </para> + + <para> + You can customize this name by altering the value of the + "hostname" variable in the + <filename>base-files</filename> recipe using either + an append file or a configuration file. + Use the following in an append file: + <literallayout class='monospaced'> + hostname="myhostname" + </literallayout> + Use the following in a configuration file: + <literallayout class='monospaced'> + hostname_pn-base-files = "myhostname" + </literallayout> + </para> + + <para> + Changing the default value of the variable "hostname" can be + useful in certain situations. + For example, suppose you need to do extensive testing on an + image and you would like to easily identify the image + under test from existing images with typical default + hostnames. + In this situation, you could change the default hostname to + "testme", which results in all the images using the name + "testme". + Once testing is complete and you do not need to rebuild the + image for test any longer, you can easily reset the default + hostname. + </para> + + <para> + Another point of interest is that if you unset the variable, + the image will have no default hostname in the filesystem. + Here is an example that unsets the variable in a + configuration file: + <literallayout class='monospaced'> + hostname_pn-base-files = "" + </literallayout> + Having no default hostname in the filesystem is suitable for + environments that use dynamic hostnames such as virtual + machines. + </para> + </section> </section> <section id='new-recipe-writing-a-new-recipe'> @@ -1182,61 +1248,167 @@ </para> </section> - <section id='new-recipe-locate-a-base-recipe'> - <title>Locate a Base Recipe</title> + <section id='new-recipe-locate-or-automatically-create-a-base-recipe'> + <title>Locate or Automatically Create a Base Recipe</title> <para> - Before writing a recipe from scratch, it is often useful to - discover whether someone else has already written one that - meets (or comes close to meeting) your needs. - The Yocto Project and OpenEmbedded communities maintain many - recipes that might be candidates for what you are doing. - You can find a good central index of these recipes in the - <ulink url='http://layers.openembedded.org'>OpenEmbedded metadata index</ulink>. + You can always write a recipe from scratch. + However, two choices exist that can help you quickly get a + start on a new recipe: + <itemizedlist> + <listitem><para><emphasis><filename>recipetool</filename>:</emphasis> + A tool provided by the Yocto Project that automates + creation of a base recipe based on the source + files. + </para></listitem> + <listitem><para><emphasis>Existing Recipes:</emphasis> + Location and modification of an existing recipe that is + similar in function to the recipe you need. + </para></listitem> + </itemizedlist> </para> - <para> - Working from an existing recipe or a skeleton recipe is the - best way to get started. - Here are some points on both methods: - <itemizedlist> - <listitem><para><emphasis>Locate and modify a recipe that - is close to what you want to do:</emphasis> - This method works when you are familiar with the - current recipe space. - The method does not work so well for those new to - the Yocto Project or writing recipes.</para> - <para>Some risks associated with this method are - using a recipe that has areas totally unrelated to - what you are trying to accomplish with your recipe, - not recognizing areas of the recipe that you might - have to add from scratch, and so forth. - All these risks stem from unfamiliarity with the - existing recipe space.</para></listitem> - <listitem><para><emphasis>Use and modify the following - skeleton recipe:</emphasis> - <literallayout class='monospaced'> - SUMMARY = "" + <section id='new-recipe-creating-the-base-recipe-using-recipetool'> + <title>Creating the Base Recipe Using <filename>recipetool</filename></title> + + <para> + <filename>recipetool</filename> automates creation of + a base recipe given a set of source code files. + As long as you can extract or point to the source files, + the tool will construct a recipe and automatically + configure all pre-build information into the recipe. + For example, suppose you have an application that builds + using Autotools. + Creating the base recipe using + <filename>recipetool</filename> results in a recipe + that has the pre-build dependencies, license requirements, + and checksums configured. + </para> + + <para> + To run the tool, you just need to be in your + <link linkend='build-directory'>Build Directory</link> + and have sourced the build environment setup script + (i.e. + <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>oe-init-build-env</filename></ulink> + or + <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>). + Here is the basic <filename>recipetool</filename> syntax: + <note> + Running <filename>recipetool -h</filename> or + <filename>recipetool create -h</filename> produces the + Python-generated help, which presented differently + than what follows here. + </note> + <literallayout class='monospaced'> + recipetool -h + recipetool create [-h] + recipetool [-d] [-q] [--color auto | always | never ] create -o <replaceable>OUTFILE</replaceable> [-m] [-x <replaceable>EXTERNALSRC</replaceable>] <replaceable>source</replaceable> + + -d Enables debug output. + -q Outputs only errors (quiet mode). + --color Colorizes the output automatically, always, or never. + -h Displays Python generated syntax for recipetool. + create Causes recipetool to create a base recipe. The create + command is further defined with these options: + + -o <replaceable>OUTFILE</replaceable> Specifies the full path and filename for the generated + recipe. + -m Causes the recipe to be machine-specific rather than + architecture-specific (default). + -x <replaceable>EXTERNALSRC</replaceable> Fetches and extracts source files from <replaceable>source</replaceable> + and places them in <replaceable>EXTERNALSRC</replaceable>. + <replaceable>source</replaceable> must be a URL. + -h Displays Python-generated syntax for create. + <replaceable>source</replaceable> Specifies the source code on which to base the + recipe. + </literallayout> + </para> + + <para> + Running <filename>recipetool create -o</filename> <replaceable>OUTFILE</replaceable> + creates the base recipe and locates it properly in the + layer that contains your source files. + Following are some syntax examples: + </para> + + <para> + Use this syntax to generate a recipe based on <replaceable>source</replaceable>. + Once generated, the recipe resides in the existing source + code layer: + <literallayout class='monospaced'> + recipetool create -o <replaceable>OUTFILE</replaceable> <replaceable>source</replaceable> + </literallayout> + Use this syntax to generate a recipe using code that you + extract from <replaceable>source</replaceable>. + The extracted code is placed in its own layer defined + by <replaceable>EXTERNALSRC</replaceable>. + <literallayout class='monospaced'> + recipetool create -o <replaceable>OUTFILE</replaceable> -x <replaceable>EXTERNALSRC</replaceable> <replaceable>source</replaceable> + </literallayout> + Use this syntax to generate a recipe based on <replaceable>source</replaceable>. + The options direct <filename>recipetool</filename> to + run in "quiet mode" and to generate debugging information. + Once generated, the recipe resides in the existing source + code layer: + <literallayout class='monospaced'> + recipetool create -o <replaceable>OUTFILE</replaceable> <replaceable>source</replaceable> + </literallayout> + </para> + </section> + + <section id='new-recipe-locating-and-using-a-similar-recipe'> + <title>Locating and Using a Similar Recipe</title> + + <para> + Before writing a recipe from scratch, it is often useful to + discover whether someone else has already written one that + meets (or comes close to meeting) your needs. + The Yocto Project and OpenEmbedded communities maintain many + recipes that might be candidates for what you are doing. + You can find a good central index of these recipes in the + <ulink url='http://layers.openembedded.org'>OpenEmbedded metadata index</ulink>. + </para> + + <para> + Working from an existing recipe or a skeleton recipe is the + best way to get started. + Here are some points on both methods: + <itemizedlist> + <listitem><para><emphasis>Locate and modify a recipe that + is close to what you want to do:</emphasis> + This method works when you are familiar with the + current recipe space. + The method does not work so well for those new to + the Yocto Project or writing recipes.</para> + <para>Some risks associated with this method are + using a recipe that has areas totally unrelated to + what you are trying to accomplish with your recipe, + not recognizing areas of the recipe that you might + have to add from scratch, and so forth. + All these risks stem from unfamiliarity with the + existing recipe space.</para></listitem> + <listitem><para><emphasis>Use and modify the following + skeleton recipe:</emphasis> + If for some reason you do not want to use + <filename>recipetool</filename> and you cannot + find an existing recipe that is close to meeting + your needs, you can use the following structure to + provide the fundamental areas of a new recipe. + <literallayout class='monospaced'> + DESCRIPTION = "" HOMEPAGE = "" LICENSE = "" - + SECTION = "" + DEPENDS = "" LIC_FILES_CHKSUM = "" SRC_URI = "" - SRC_URI[md5sum] = "" - SRC_URI[sha256sum] = "" - - S = "${WORKDIR}/${PN}-${PV}" - - inherit <replaceable>stuff</replaceable> - </literallayout> - Modifying this recipe is the recommended method for - creating a new recipe. - The recipe provides the fundamental areas that you need - to include, exclude, or alter to fit your needs. - </para></listitem> - </itemizedlist> - </para> + </literallayout> + </para></listitem> + </itemizedlist> + </para> + </section> </section> <section id='new-recipe-storing-and-naming-the-recipe'> @@ -1810,8 +1982,9 @@ <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. + when you attempt to build the recipe, or you provide an + incorrect checksum, the build will produce an error for each + missing or incorrect 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 @@ -1858,8 +2031,11 @@ <para> The previous example also specifies a patch file. - Patch files are files whose names end in - <filename>.patch</filename> or <filename>.diff</filename>. + Patch files are files whose names usually end in + <filename>.patch</filename> or <filename>.diff</filename> but + can end with compressed suffixes such as + <filename>diff.gz</filename> and + <filename>patch.bz2</filename>, for example. The build system automatically applies patches as described in the "<link linkend='new-recipe-patching-code'>Patching Code</link>" section. @@ -1905,7 +2081,9 @@ fetched. Any files mentioned in <filename>SRC_URI</filename> whose names end in <filename>.patch</filename> or - <filename>.diff</filename> are treated as patches. + <filename>.diff</filename> or compressed versions of these + suffixes (e.g. <filename>diff.gz</filename> are treated as + patches. The <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-patch'><filename>do_patch</filename></ulink> task automatically applies these patches. @@ -1929,7 +2107,9 @@ using <filename>file://</filename>, you should place patch files in a directory next to the recipe either named the same as the base name of the recipe - (<ulink url='&YOCTO_DOCS_REF_URL;#var-BPN'><filename>BPN</filename></ulink>), + (<ulink url='&YOCTO_DOCS_REF_URL;#var-BP'><filename>BP</filename></ulink> + and + <ulink url='&YOCTO_DOCS_REF_URL;#var-BPN'><filename>BPN</filename></ulink>) or "files". </para> </section> @@ -2142,7 +2322,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> @@ -2165,7 +2345,7 @@ 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> @@ -2630,7 +2810,6 @@ A post-installation function has the following structure: <literallayout class='monospaced'> pkg_postinst_PACKAGENAME() { - #!/bin/sh -e # Commands to carry out } </literallayout> @@ -2653,7 +2832,6 @@ structure in the post-installation script: <literallayout class='monospaced'> pkg_postinst_PACKAGENAME() { - #!/bin/sh -e if [ x"$D" = "x" ]; then # Actions to carry out on the device go here else @@ -2889,11 +3067,10 @@ <literallayout class='monospaced'> require xorg-lib-common.inc - SUMMARY = "X11 Pixmap library" - LICENSE = "X-BSD" - LIC_FILES_CHKSUM = "file://COPYING;md5=3e07763d16963c3af12db271a31abaa5" + SUMMARY = "Xpm: X Pixmap extension library" + LICENSE = "BSD" + LIC_FILES_CHKSUM = "file://COPYING;md5=51f4270b012ecd4ab1a164f5f4ed6cf7" DEPENDS += "libxext libsm libxt" - PR = "r3" PE = "1" XORG_PN = "libXpm" @@ -3027,7 +3204,7 @@ <note> Although well within the capabilities of the Yocto Project, adding a totally new architecture might require - changes to <filename>gcc/eglibc</filename> and to the site + changes to <filename>gcc/glibc</filename> and to the site information, which is beyond the scope of this manual. </note> </para> @@ -3611,12 +3788,6 @@ 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 @@ -3629,6 +3800,12 @@ in the form generated by the build system. </para></listitem> <listitem><para> + You must build several native tools: + <literallayout class='monospaced'> + $ bitbake parted-native dosfstools-native mtools-native + </literallayout> + </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> @@ -3650,7 +3827,7 @@ or by entering the command with a help argument as follows: <literallayout class='monospaced'> $ wic -h - $ wic ‐‐help + $ wic --help </literallayout> </para> @@ -3666,7 +3843,7 @@ <para> You can also get detailed help on a number of topics from the help system. - The output of <filename>wic ‐‐help</filename> + 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 @@ -3736,38 +3913,38 @@ 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> + -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> + -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> + -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> + -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> + -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> + -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> + -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 + -s, --skip-build-check Skips the build check. - -D, ‐‐debug + -D, --debug Output debug information. </literallayout> <note> @@ -3977,13 +4154,13 @@ </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>". + 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 + 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. @@ -4070,11 +4247,11 @@ somewhere other than the default <filename>/var/tmp/wic</filename> directory: <literallayout class='monospaced'> - $ wic create ~/test.wks -o /home/trz/testwic ‐‐rootfs-dir \ + $ 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 + --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)... @@ -4117,7 +4294,7 @@ partitions. The plugins provide a mechanism for mapping values specified in <filename>.wks</filename> files using the - <filename>‐‐source</filename> keyword to a + <filename>--source</filename> keyword to a particular plugin implementation that populates a corresponding partition. </para> @@ -4146,11 +4323,11 @@ 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 + <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 ... + part /boot --source bootimg-pcbios ... </literallayout> The methods defined as class members of the plugin having the matching <filename>bootimg-pcbios.name</filename> @@ -4160,7 +4337,7 @@ <para> To be more concrete, here is the plugin definition that matches a - <filename>‐‐source bootimg-pcbios</filename> usage, + <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 @@ -4182,7 +4359,7 @@ 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. + <filename>--source</filename> plugins. Any methods not implemented by a <filename>SourcePlugin</filename> subclass inherit the implementations present in the @@ -4314,13 +4491,13 @@ <para> Following are the supported options: <itemizedlist> - <listitem><para><emphasis><filename>‐‐size</filename>:</emphasis> + <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> + <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 @@ -4332,7 +4509,7 @@ "<link linkend='openembedded-kickstart-plugins'>Plugins</link>" section.</para> <para>If you use - <filename>‐‐source rootfs</filename>, + <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 @@ -4342,14 +4519,14 @@ option. The filesystem type used to create the partition is driven by the value of the - <filename>‐‐fstype</filename> option + <filename>--fstype</filename> option specified for the partition. See the entry on - <filename>‐‐fstype</filename> that + <filename>--fstype</filename> that follows for more information. </para> <para>If you use - <filename>‐‐source <replaceable>plugin-name</replaceable></filename>, + <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 @@ -4362,10 +4539,10 @@ 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> + <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> + <listitem><para><emphasis><filename>--fstype</filename>:</emphasis> Sets the file system type for the partition. Valid values are: <itemizedlist> @@ -4382,7 +4559,7 @@ <listitem><para><filename>swap</filename> </para></listitem> </itemizedlist></para></listitem> - <listitem><para><emphasis><filename>‐‐fsoptions</filename>:</emphasis> + <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 @@ -4392,15 +4569,15 @@ If not specified, the default string is "defaults". </para></listitem> - <listitem><para><emphasis><filename>‐‐label label</filename>:</emphasis> + <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> + <listitem><para><emphasis><filename>--active</filename>:</emphasis> Marks the partition as active.</para></listitem> - <listitem><para><emphasis><filename>‐‐align (in KBytes)</filename>:</emphasis> + <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> @@ -4417,17 +4594,17 @@ <note> Bootloader functionality and boot partitions are implemented by the various - <filename>‐‐source</filename> + <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> + <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> + <listitem><para><emphasis><filename>--append</filename>:</emphasis> Specifies kernel parameters. These parameters will be added to the syslinux <filename>APPEND</filename> or @@ -4579,8 +4756,10 @@ placed where the OpenEmbedded build system can find and apply them. Syntactically, the configuration statement is identical to what would appear in the <filename>.config</filename> file, which is in the - <link linkend='build-directory'>Build Directory</link> in - <filename>tmp/work/<arch>-poky-linux/linux-yocto-<release-specific-string>/linux-<arch>-<build-type></filename>. + <link linkend='build-directory'>Build Directory</link>: + <literallayout class='monospaced'> + tmp/work/<replaceable>arch</replaceable>-poky-linux/linux-yocto-<replaceable>release_specific_string</replaceable>/linux-<replaceable>arch</replaceable>-<replaceable>build_type</replaceable> + </literallayout> </para> <para> @@ -4807,7 +4986,7 @@ <literallayout class='monospaced'> ${S}/linux </literallayout> - See the "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>" + See the "<link linkend='finding-the-temporary-source-code'>Finding Temporary Source Code</link>" section and the <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink> variable for more information about where source is kept during a build. @@ -4826,8 +5005,8 @@ <para> Two methods exist by which you can create the patch: - <link linkend='using-a-git-workflow'>Git workflow</link> and - <link linkend='using-a-quilt-workflow'>Quilt workflow</link>. + <link linkend='using-devtool-in-your-workflow'><filename>devtool</filename></link> and + <link linkend='using-a-quilt-workflow'>Quilt</link>. For kernel patches, the Git workflow is more appropriate. This section assumes the Git workflow and shows the steps specific to this example. @@ -4983,11 +5162,6 @@ $HOME/poky/meta-yocto-bsp \ $HOME/poky/meta-mylayer \ " - - BBLAYERS_NON_REMOVABLE ?= " \ - $HOME/poky/meta \ - $HOME/poky/meta-yocto \ - " </literallayout></para></listitem> </itemizedlist> </para> @@ -5089,8 +5263,7 @@ by Jake Edge </para></listitem> <listitem><para><emphasis> - "<ulink url='https://www.nccgroup.com/media/18475/exploiting_security_gateways_via_their_web_interfaces.pdf'>They ought to know better: Exploiting Security -Gateways via their Web Interfaces</ulink>"</emphasis> + "<ulink url='https://www.nccgroup.com/media/18475/exploiting_security_gateways_via_their_web_interfaces.pdf'>They ought to know better: Exploiting Security Gateways via their Web Interfaces</ulink>"</emphasis> by Ben Williams </para></listitem> </itemizedlist> @@ -5911,10 +6084,10 @@ Gateways via their Web Interfaces</ulink>"</emphasis> described here combined with experimentation and iteration. Here are a couple of areas to experiment with: <itemizedlist> - <listitem><para><filename>eglibc</filename>: + <listitem><para><filename>glibc</filename>: In general, follow this process: <orderedlist> - <listitem><para>Remove <filename>eglibc</filename> + <listitem><para>Remove <filename>glibc</filename> features from <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink> that you think you do not need.</para></listitem> @@ -5928,7 +6101,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> support wide character support as is done for <filename>ncurses</filename>. Or, if support for those characters is needed, - determine what <filename>eglibc</filename> + determine what <filename>glibc</filename> features provide the support and restore the configuration. </para></listitem> @@ -5937,7 +6110,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> </orderedlist></para></listitem> <listitem><para><filename>busybox</filename>: For BusyBox, use a process similar as described for - <filename>eglibc</filename>. + <filename>glibc</filename>. A difference is you will need to boot the resulting system to see if you are able to do everything you expect from the running system. @@ -5973,6 +6146,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> @@ -5986,9 +6345,6 @@ Gateways via their Web Interfaces</ulink>"</emphasis> <link linkend='incrementing-a-package-revision-number'>Incrementing a package revision number</link> </para></listitem> <listitem><para> - <link linkend='usingpoky-configuring-DISTRO_PN_ALIAS'>Handling a package name alias</link> - </para></listitem> - <listitem><para> <link linkend='handling-optional-module-packaging'>Handling optional module packaging</link> </para></listitem> <listitem><para> @@ -6173,7 +6529,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 <replaceable>ip</replaceable> ‐‐port <replaceable>port</replaceable> ‐‐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 @@ -6274,53 +6630,6 @@ Gateways via their Web Interfaces</ulink>"</emphasis> </section> </section> - <section id="usingpoky-configuring-DISTRO_PN_ALIAS"> - <title>Handling a Package Name Alias</title> - <para> - Sometimes a package name you are using might exist under - an alias or as a similarly named package in a different - distribution. - The OpenEmbedded build system implements a - <filename>do_distro_check</filename> - task that automatically connects to major distributions - and checks for these situations. - If the package exists under a different name in a different - distribution, you get a <filename>distro_check</filename> - mismatch. - You can resolve this problem by defining a per-distro recipe - name alias using the - <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_PN_ALIAS'>DISTRO_PN_ALIAS</ulink></filename> - variable. - </para> - - <para> - Following is an example that shows how you specify the <filename>DISTRO_PN_ALIAS</filename> - variable: - <literallayout class='monospaced'> - DISTRO_PN_ALIAS_pn-PACKAGENAME = "distro1=package_name_alias1 \ - distro2=package_name_alias2 \ - distro3=package_name_alias3 \ - ..." - </literallayout> - </para> - - <para> - If you have more than one distribution alias, separate them with a space. - Note that the build system currently automatically checks the - Fedora, OpenSUSE, Debian, Ubuntu, - and Mandriva distributions for source package recipes without having to specify them - using the <filename>DISTRO_PN_ALIAS</filename> variable. - For example, the following command generates a report that lists the Linux distributions - that include the sources for each of the recipes. - <literallayout class='monospaced'> - $ bitbake world -f -c distro_check - </literallayout> - The results are stored in the <filename>build/tmp/log/distro_check-${DATETIME}.results</filename> - file found in the - <link linkend='source-directory'>Source Directory</link>. - </para> - </section> - <section id='handling-optional-module-packaging'> <title>Handling Optional Module Packaging</title> @@ -6872,9 +7181,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: @@ -7375,6 +7684,114 @@ Gateways via their Web Interfaces</ulink>"</emphasis> </section> </section> + <section id="selecting-dev-manager"> + <title>Selecting a Device Manager</title> + + <para> + The Yocto Project provides multiple ways to manage the device + manager (<filename>/dev</filename>): + <itemizedlist> + <listitem><para><emphasis>Persistent and Pre-Populated<filename>/dev</filename>:</emphasis> + For this case, the <filename>/dev</filename> directory + is persistent and the required device nodes are created + during the build. + </para></listitem> + <listitem><para><emphasis>Use <filename>devtmpfs</filename> with a Device Manager:</emphasis> + For this case, the <filename>/dev</filename> directory + is provided by the kernel as an in-memory file system and + is automatically populated by the kernel at runtime. + Additional configuration of device nodes is done in user + space by a device manager like + <filename>udev</filename> or + <filename>busybox-mdev</filename>. + </para></listitem> + </itemizedlist> + </para> + + <section id="static-dev-management"> + <title>Using Persistent and Pre-Populated<filename>/dev</filename></title> + + <para> + To use the static method for device population, you need to + set the + <ulink url='&YOCTO_DOCS_REF_URL;#var-USE_DEVFS'><filename>USE_DEVFS</filename></ulink> + variable to "0" as follows: + <literallayout class='monospaced'> + USE_DEVFS = "0" + </literallayout> + </para> + + <para> + The content of the resulting <filename>/dev</filename> + directory is defined in a Device Table file. + The + <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_DEVICE_TABLES'><filename>IMAGE_DEVICE_TABLES</filename></ulink> + variable defines the Device Table to use and should be set + in the machine or distro configuration file. + Alternatively, you can set this variable in your + <filename>local.conf</filename> configuration file. + </para> + + <para> + If you do not define the + <filename>IMAGE_DEVICE_TABLES</filename> variable, the default + <filename>device_table-minimal.txt</filename> is used: + <literallayout class='monospaced'> + IMAGE_DEVICE_TABLES = "device_table-mymachine.txt" + </literallayout> + </para> + + <para> + The population is handled by the <filename>makedevs</filename> + utility during image creation: + </para> + </section> + + <section id="devtmpfs-dev-management"> + <title>Using <filename>devtmpfs</filename> and a Device Manager</title> + + <para> + To use the dynamic method for device population, you need to + use (or be sure to set) the + <ulink url='&YOCTO_DOCS_REF_URL;#var-USE_DEVFS'><filename>USE_DEVFS</filename></ulink> + variable to "1", which is the default: + <literallayout class='monospaced'> + USE_DEVFS = "1" + </literallayout> + With this setting, the resulting <filename>/dev</filename> + directory is populated by the kernel using + <filename>devtmpfs</filename>. + Make sure the corresponding kernel configuration variable + <filename>CONFIG_DEVTMPFS</filename> is set when building + you build a Linux kernel. + </para> + + <para> + All devices created by <filename>devtmpfs</filename> will be + owned by <filename>root</filename> and have permissions + <filename>0600</filename>. + </para> + + <para> + To have more control over the device nodes, you can use a + device manager like <filename>udev</filename> or + <filename>busybox-mdev</filename>. + You choose the device manager by defining the + <filename>VIRTUAL-RUNTIME_dev_manager</filename> variable + in your machine or distro configuration file. + Alternatively, you can set this variable in your + <filename>local.conf</filename> configuration file: + <literallayout class='monospaced'> + VIRTUAL-RUNTIME_dev_manager = "udev" + + # Some alternative values + # VIRTUAL-RUNTIME_dev_manager = "busybox-mdev" + # VIRTUAL-RUNTIME_dev_manager = "systemd" + </literallayout> + </para> + </section> + </section> + <section id="platdev-appdev-srcrev"> <title>Using an External SCM</title> @@ -7397,7 +7814,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCPV'><filename>SRCPV</filename></ulink>. Here is an example: <literallayout class='monospaced'> - PV = "1.2.3+git${SRCPV} + PV = "1.2.3+git${SRCPV}" </literallayout> Then, you can add the following to your <filename>local.conf</filename>: @@ -8001,7 +8418,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> 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> + <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_SERIALCONTROL_CMD'><filename>TEST_SERIALCONTROL_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. @@ -8216,13 +8633,13 @@ Gateways via their Web Interfaces</ulink>"</emphasis> 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 + "--deploy-dir <replaceable>path</replaceable>" as follows: <literallayout class='monospaced'> - ./runexported.py ‐‐deploy-dir /new/path/on/this/machine testdata.json + ./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>. + as well as described using <filename>--help</filename>. </para> </section> @@ -8304,7 +8721,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> "ps" (busybox). </para></listitem> <listitem><para><emphasis><filename>tc</filename>:</emphasis> - The called text context, which gives access to the + The called test context, which gives access to the following attributes: <itemizedlist> <listitem><para><emphasis><filename>d</filename>:</emphasis> @@ -8682,7 +9099,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 @@ -8723,7 +9140,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/ @@ -8798,7 +9215,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/...... . . . @@ -8830,7 +9247,7 @@ Gateways via their Web Interfaces</ulink>"</emphasis> File Makefile.am added to patch patches/parallelmake.patch </literallayout> For more information on using Quilt, see the - "<link linkend='using-a-quilt-workflow'>Using a Quilt Workflow</link>" + "<link linkend='using-a-quilt-workflow'>Using Quilt in Your Workflow</link>" section. </para> @@ -8921,217 +9338,6 @@ Gateways via their Web Interfaces</ulink>"</emphasis> </section> </section> - <section id="examining-builds-using-toaster"> - <title>Examining Builds Using the Toaster API</title> - - <para> - Toaster is an Application Programming Interface (API) and - web-based interface to the OpenEmbedded build system, which uses - BitBake. - Both interfaces are based on a Representational State Transfer - (REST) API that queries for and returns build information using - <filename>GET</filename> and <filename>JSON</filename>. - These types of search operations retrieve sets of objects from - a datastore used to collect build information. - The results contain all the data for the objects being returned. - You can order the results of the search by key and the search - parameters are consistent for all object types. - </para> - - <para> - Using the interfaces you can do the following: - <itemizedlist> - <listitem><para>See information about the tasks executed - and reused during the build.</para></listitem> - <listitem><para>See what is built (recipes and - packages) and what packages were installed into the final - image.</para></listitem> - <listitem><para>See performance-related information such - as build time, CPU usage, and disk I/O.</para></listitem> - <listitem><para>Examine error, warning and trace messages - to aid in debugging.</para></listitem> - </itemizedlist> - </para> - - <note> - <para>This release of Toaster provides you with information - about a BitBake run. - The tool does not allow you to configure and launch a build. - However, future development includes plans to integrate the - configuration and build launching capabilities of - <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink>. - </para> - <para>For more information on using Hob to build an image, - see the - "<link linkend='image-development-using-hob'>Image Development Using Hob</link>" - section.</para> - </note> - - <para> - The remainder of this section describes what you need to have in - place to use Toaster, how to start it, use it, and stop it. - For additional information on installing and running Toaster, see the - "<ulink url='https://wiki.yoctoproject.org/wiki/Toaster#Installation_and_Running'>Installation and Running</ulink>" - section of the "Toaster" wiki page. - For complete information on the API and its search operation - URI, parameters, and responses, see the - <ulink url='https://wiki.yoctoproject.org/wiki/REST_API_Contracts'>REST API Contracts</ulink> - Wiki page. - </para> - - <section id='starting-toaster'> - <title>Starting Toaster</title> - - <para> - Getting set up to use and start Toaster is simple. - First, be sure you have met the following requirements: - <itemizedlist> - <listitem><para>You have set up your - <link linkend='source-directory'>Source Directory</link> - by cloning the upstream <filename>poky</filename> - repository. - See the - <link linkend='local-yp-release'>Yocto Project Release</link> - item for information on how to set up the Source - Directory.</para></listitem> - <listitem><para>Be sure your build machine has - <ulink url='http://en.wikipedia.org/wiki/Django_%28web_framework%29'>Django</ulink> - version 1.5 installed.</para></listitem> - <listitem><para>Make sure that port 8000 and 8200 are - free (i.e. they have no servers on them). - </para></listitem> - </itemizedlist> - </para> - - <para> - Once you have met the requirements, follow these steps to - start Toaster running in the background of your shell: - <orderedlist> - <listitem><para><emphasis>Set up your build environment:</emphasis> - 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></listitem> - <listitem><para><emphasis>Start Toaster:</emphasis> - Start the Toaster service using this - command from within your - <link linkend='build-directory'>Build Directory</link>: - <literallayout class='monospaced'> - $ source toaster start - </literallayout></para></listitem> - <note> - The Toaster must be started and running in order - for it to collect data. - </note> - </orderedlist> - </para> - - <para> - When Toaster starts, it creates some additional files in your - Build Directory. - Deleting these files will cause you to lose data or interrupt - Toaster: - <itemizedlist> - <listitem><para><emphasis><filename>toaster.sqlite</filename>:</emphasis> - Toaster's database file.</para></listitem> - <listitem><para><emphasis><filename>toaster_web.log</filename>:</emphasis> - The log file of the web server.</para></listitem> - <listitem><para><emphasis><filename>toaster_ui.log</filename>:</emphasis> - The log file of the user interface component. - </para></listitem> - <listitem><para><emphasis><filename>toastermain.pid</filename>:</emphasis> - The PID of the web server.</para></listitem> - <listitem><para><emphasis><filename>toasterui.pid</filename>:</emphasis> - The PID of the DSI data bridge.</para></listitem> - <listitem><para><emphasis><filename>bitbake-cookerdaemon.log</filename>:</emphasis> - The BitBake server's log file.</para></listitem> - </itemizedlist> - </para> - </section> - - <section id='using-toaster'> - <title>Using Toaster</title> - - <para> - Once Toaster is running, it logs information for any BitBake - run from your Build Directory. - This logging is automatic. - All you need to do is access and use the information. - </para> - - <para> - You access the information one of two ways: - <itemizedlist> - <listitem><para>Open a Browser and enter - <filename>http://localhost:8000</filename> - for the URL. - </para></listitem> - <listitem><para>Use the <filename>xdg-open</filename> - tool from the shell and pass it the same URL. - </para></listitem> - </itemizedlist> - Either method opens the home page for the Toaster interface. - </para> - - <note><title>Notes</title> - <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> - - <section id='examining-toaster-data'> - <title>Examining Toaster Data</title> - - <para> - The Toaster database is persistent regardless of whether you - start or stop the service. - </para> - - <para> - Toaster's interface shows you a list of builds - (successful and unsuccessful) for which it has data. - You can click on any build to see related information. - This information includes configuration details, information - about tasks, all recipes and packages built and their - dependencies, packages and their directory structure as - installed in your final image, - execution time, CPU usage and disk I/O per task. - </para> - - <para> - For details on the interface, see the - <ulink url='https://www.yoctoproject.org/documentation/toaster-manual'>Toaster Manual</ulink>. - </para> - </section> - - <section id='stopping-toaster'> - <title>Stopping Toaster</title> - - <para> - Stop the Toaster service with the following command - from with the - <link linkend='build-directory'>Build Directory</link>: - <literallayout class='monospaced'> - $ source toaster stop - </literallayout> - The service stops but the Toaster database remains persistent. - </para> - </section> - </section> - <section id="platdev-oprofile"> <title>Profiling with OProfile</title> @@ -9193,14 +9399,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> @@ -9213,7 +9419,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> @@ -9276,7 +9482,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> @@ -9366,14 +9572,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> @@ -9608,11 +9814,6 @@ Gateways via their Web Interfaces</ulink>"</emphasis> ##OEROOT##/meta-yocto-bsp \ ##OEROOT##/meta-mylayer \ " - - BBLAYERS_NON_REMOVABLE ?= " \ - ##OEROOT##/meta \ - ##OEROOT##/meta-yocto \ - " </literallayout> Creating and providing an archive of the <link linkend='metadata'>Metadata</link> layers @@ -9678,28 +9879,36 @@ Gateways via their Web Interfaces</ulink>"</emphasis> </literallayout> Enabling error reporting causes the build process to collect the errors and store them in a file as previously described. - When the build system encounters an error, it includes a command - as part of the console output. + When the build system encounters an error, it includes a + command as part of the console output. You can run the command to send the error file to the server. - For example, the following command sends the errors to an upstream - server: + For example, the following command sends the errors to an + upstream server: + <literallayout class='monospaced'> + $ send-error-report /home/brandusa/project/poky/build/tmp/log/error-report/error_report_201403141617.txt + </literallayout> + In the previous example, the errors are sent to a public + database available at + <ulink url='http://errors.yoctoproject.org'></ulink>, which is + used by the entire community. + If you specify a particular server, you can send the errors + to a different database. + Use the following command for more information on available + options: <literallayout class='monospaced'> - send-error-report /home/brandusa/project/poky/build/tmp/log/error-report/error_report_201403141617.txt [server] + $ send-error-report --help </literallayout> - In the above example, the <filename>server</filename> parameter is - optional. - By default, the errors are sent to a database used by the entire - community. - If you specify a particular server, you can send them to a different - database. </para> <para> - When sending the error file, you receive a link that corresponds - to your entry in the database. + When sending the error file, you are prompted to review the + data being sent as well as to provide a name and optional + email address. + Once you satisfy these prompts, the command returns a link + from the server that corresponds to your entry in the database. For example, here is a typical link: <literallayout class='monospaced'> - http://localhost:8000/Errors/Search/1/158 + http://errors.yoctoproject.org/Errors/Details/9522/ </literallayout> Following the link takes you to a web interface where you can browse, query the errors, and view statistics. 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-eclipse-customization.xsl b/documentation/dev-manual/dev-manual-eclipse-customization.xsl index 8ac4c18f25..f4e21d6678 100644 --- a/documentation/dev-manual/dev-manual-eclipse-customization.xsl +++ b/documentation/dev-manual/dev-manual-eclipse-customization.xsl @@ -6,7 +6,7 @@ version="1.0"> <xsl:import - href="http://docbook.sourceforge.net/release/xsl/current/eclipse/eclipse3.xsl" /> + href="http://docbook.sourceforge.net/release/xsl/1.76.1/eclipse/eclipse3.xsl" /> <xsl:param name="chunker.output.indent" select="'yes'"/> <xsl:param name="chunk.quietly" select="1"/> diff --git a/documentation/dev-manual/dev-manual-intro.xml b/documentation/dev-manual/dev-manual-intro.xml index 21fba29670..e350882a38 100644 --- a/documentation/dev-manual/dev-manual-intro.xml +++ b/documentation/dev-manual/dev-manual-intro.xml @@ -5,7 +5,7 @@ <chapter id='dev-manual-intro'> <title>The Yocto Project Development Manual</title> - <section id='intro'> + <section id='dev-intro'> <title>Introduction</title> <para> @@ -147,6 +147,12 @@ profiling schemes along with their applications (as appropriate) to each tool. </para></listitem> <listitem><para><emphasis> + <ulink url='&YOCTO_DOCS_TOAST_URL;'>Toaster User Manual</ulink>:</emphasis> + This manual introduces and describes how to set up and use + Toaster, which is a web interface to the Yocto Project's + <link linkend='build-system-term'>OpenEmbedded Build System</link>. + </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 diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml index 43c31b8405..fd0d156494 100644 --- a/documentation/dev-manual/dev-manual-model.xml +++ b/documentation/dev-manual/dev-manual-model.xml @@ -12,39 +12,54 @@ Yocto Project: <itemizedlist> <listitem><para><emphasis>System Development:</emphasis> - System Development covers Board Support Package (BSP) development and kernel - modification or configuration. + System Development covers Board Support Package (BSP) development + and kernel modification or configuration. For an example on how to create a BSP, see the "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>" - section in the Yocto Project Board Support Package (BSP) Developer's Guide. - For more complete information on how to work with the kernel, see the + section in the Yocto Project Board Support Package (BSP) + Developer's Guide. + For more complete information on how to work with the kernel, + see the <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>. </para></listitem> <listitem><para><emphasis>User Application Development:</emphasis> - User Application Development covers development of applications that you intend - to run on target hardware. - For information on how to set up your host development system for user-space - application development, see the + User Application Development covers development of applications + that you intend to run on target hardware. + For information on how to set up your host development system for + user-space application development, see the <ulink url='&YOCTO_DOCS_ADT_URL;'>Yocto Project Application Developer's Guide</ulink>. - For a simple example of user-space application development using the - <trademark class='trade'>Eclipse</trademark> IDE, see the + For a simple example of user-space application development using + the <trademark class='trade'>Eclipse</trademark> IDE, see the "<link linkend='application-development-workflow'>Application Development Workflow</link>" section. </para></listitem> <listitem><para><emphasis>Temporary Source Code Modification:</emphasis> - Direct modification of temporary source code is a convenient development model - to quickly iterate and develop towards a solution. - Once you implement the solution, you should of course take steps to - get the changes upstream and applied in the affected recipes.</para></listitem> + Direct modification of temporary source code is a convenient + development model to quickly iterate and develop towards a + solution. + Once you implement the solution, you should of course take + steps to get the changes upstream and applied in the affected + recipes. + </para></listitem> + <listitem><para><emphasis>Image Development using Toaster:</emphasis> + You can use <ulink url='&YOCTO_HOME_URL;/Tools-resources/projects/toaster'>Toaster</ulink> + to build custom operating system images within the build + environment. + Toaster provides an efficient interface to the OpenEmbedded build + that allows you to start builds and examine build statistics. + </para></listitem> <listitem><para><emphasis>Image Development using Hob:</emphasis> - You can use the <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink> to build - custom operating system images within the build environment. - Hob provides an efficient interface to the OpenEmbedded build system.</para></listitem> + You can use the <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink> + to build custom operating system images within the build + environment. + Hob provides an efficient interface to the OpenEmbedded build system. + </para></listitem> <listitem><para><emphasis>Using a Development Shell:</emphasis> - You can use a <filename>devshell</filename> to efficiently debug commands or simply - edit packages. - Working inside a development shell is a quick way to set up the OpenEmbedded build - environment to work on parts of a project.</para></listitem> + You can use a <filename>devshell</filename> to efficiently debug + commands or simply edit packages. + Working inside a development shell is a quick way to set up the + OpenEmbedded build environment to work on parts of a project. + </para></listitem> </itemizedlist> </para> @@ -231,9 +246,10 @@ You can also find supplemental information in the <ulink url='&YOCTO_DOCS_BSP_URL;'> Yocto Project Board Support Package (BSP) Developer's Guide</ulink>. - Finally, there is a wiki page write up of the example also located - <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'> - here</ulink> that you might find helpful. + Finally, there is helpful material and links on this + <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'>wiki page</ulink>. + Although a bit dated, you might find the information on the wiki + helpful. </para> </section> @@ -286,9 +302,9 @@ 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. + <filename>linux-yocto-3.10</filename></emphasis> - An + additional, unsupported Yocto Project kernel used with + the Yocto Project Release 1.5. This kernel is based on the Linux 3.10 released kernel. </para></listitem> <listitem><para><emphasis> @@ -299,11 +315,17 @@ </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. + additional, unsupported 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-3.19</filename></emphasis> - The + stable Yocto Project kernel to use with the Yocto + Project Release 1.8. + This kernel is based on the Linux 3.19 released kernel. + </para></listitem> + <listitem><para><emphasis> <filename>linux-yocto-dev</filename></emphasis> - A development kernel based on the latest upstream release candidate available. @@ -327,12 +349,12 @@ <para> Within the figure, the "Kernel.org Branch Point" represents the point in the tree where a supported base kernel is modified from the Linux kernel. - For example, this could be the branch point for the <filename>linux-yocto-3.4</filename> + For example, this could be the branch point for the <filename>linux-yocto-3.19</filename> kernel. Thus, everything further to the right in the structure is based on the - <filename>linux-yocto-3.4</filename> kernel. + <filename>linux-yocto-3.19</filename> kernel. Branch points to the right in the figure represent where the - <filename>linux-yocto-3.4</filename> kernel is modified for specific hardware + <filename>linux-yocto-3.19</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 targeted device. @@ -646,8 +668,8 @@ The Eclipse IDE is a popular development environment and it fully supports development using the Yocto Project. <note> - This release of the Yocto Project supports both the Kepler - and Juno versions of the Eclipse IDE. + This release of the Yocto Project supports both the Luna + and Kepler versions of the Eclipse IDE. Thus, the following information provides setup information for both versions. </note> @@ -700,19 +722,20 @@ <title>Installing the Eclipse IDE</title> <para> - It is recommended that you have the Kepler 4.3.2 version of - the Eclipse IDE installed on your development system. - However, if you currently have the Juno 4.2 version + It is recommended that you have the Luna SR2 (4.4.2) + version of the Eclipse IDE installed on your development + system. + However, if you currently have the Kepler 4.3.2 version installed and you do not want to upgrade the IDE, you can - configure Juno to work with the Yocto Project. + configure Kepler to work with the Yocto Project. </para> <para> - If you do not have the Kepler 4.3.2 Eclipse IDE installed, - you can find the tarball at + If you do not have the Luna SR2 (4.4.2) Eclipse IDE + installed, you can find the tarball at <ulink url='&ECLIPSE_MAIN_URL;'></ulink>. - From that site, choose the Eclipse Standard 4.3.2 version - particular to your development host. + From that site, choose the appropriate download from the + "Eclipse IDE for C/C++ Developers". This version contains the Eclipse Platform, the Java Development Tools (JDT), and the Plug-in Development Environment. @@ -726,7 +749,7 @@ using the default name <filename>eclipse</filename>: <literallayout class='monospaced'> $ cd ~ - $ tar -xzvf ~/Downloads/eclipse-standard-kepler-SR2-linux-gtk-x86_64.tar.gz + $ tar -xzvf ~/Downloads/eclipse-cpp-luna-SR2-linux-gtk-x86_64.tar.gz </literallayout> </para> </section> @@ -749,24 +772,37 @@ select "Install New Software" from the "Help" pull-down menu.</para></listitem> <listitem><para>Select - <filename>Kepler - &ECLIPSE_KEPLER_URL;</filename> + <filename>Luna - &ECLIPSE_LUNA_URL;</filename> from the "Work with:" pull-down menu. <note> - For Juno, select - <filename>Juno - &ECLIPSE_JUNO_URL;</filename> + For Kepler, select + <filename>Kepler - &ECLIPSE_KEPLER_URL;</filename> </note> </para></listitem> <listitem><para>Expand the box next to "Linux Tools" and select the - <filename>LTTng - Linux Tracing Toolkit</filename> - boxes.</para></listitem> + <filename>Linux Tools LTTng Tracer Control</filename>, + <filename>Linux Tools LTTng Userspace Analysis</filename>, + and + <filename>LTTng Kernel Analysis</filename> boxes. + If these selections do not appear in the list, + that means the items are already installed. + <note> + For Kepler, select + <filename>LTTng - Linux Tracing Toolkit</filename> + box. + </note> + </para></listitem> <listitem><para>Expand the box next to "Mobile and - Device Development" and select the following boxes: + Device Development" and select the following boxes. + Again, if any of the following items are not + available for selection, that means the items are + already installed: <itemizedlist> <listitem><para><filename>C/C++ Remote Launch (Requires RSE Remote System Explorer)</filename></para></listitem> <listitem><para><filename>Remote System Explorer End-user Runtime</filename></para></listitem> <listitem><para><filename>Remote System Explorer User Actions</filename></para></listitem> - <listitem><para><filename>Target Management Terminal</filename></para></listitem> + <listitem><para><filename>Target Management Terminal (Core SDK)</filename></para></listitem> <listitem><para><filename>TCF Remote System Explorer add-in</filename></para></listitem> <listitem><para><filename>TCF Target Explorer</filename></para></listitem> </itemizedlist></para></listitem> @@ -774,7 +810,10 @@ Languages" and select the <filename>C/C++ Autotools Support</filename> and <filename>C/C++ Development Tools</filename> - boxes.</para></listitem> + boxes. + For Luna, these items do not appear on the list + as they are already installed. + </para></listitem> <listitem><para>Complete the installation and restart the Eclipse IDE.</para></listitem> </orderedlist> @@ -806,12 +845,12 @@ <listitem><para>Click "Add..." in the "Work with:" area.</para></listitem> <listitem><para>Enter - <filename>&ECLIPSE_DL_PLUGIN_URL;/kepler</filename> + <filename>&ECLIPSE_DL_PLUGIN_URL;/luna</filename> in the URL field and provide a meaningful name in the "Name" field. <note> - If you are using Juno, use - <filename>&ECLIPSE_DL_PLUGIN_URL;/juno</filename> + If you are using Kepler, use + <filename>&ECLIPSE_DL_PLUGIN_URL;/kepler</filename> in the URL field. </note></para></listitem> <listitem><para>Click "OK" to have the entry added @@ -829,6 +868,11 @@ <listitem><para>Complete the remaining software installation steps and then restart the Eclipse IDE to finish the installation of the plug-in. + <note> + You can click "OK" when prompted about + installing software that contains unsigned + content. + </note> </para></listitem> </orderedlist> </para> @@ -848,82 +892,95 @@ <listitem><para>Use the Oracle JDK. If you don't have that, go to <ulink url='http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html'></ulink> - and download the appropriate tarball - for your development system and + and download the latest appropriate + Java SE Development Kit tarball for + your development system and extract it into your home directory. </para></listitem> <listitem><para>In the shell you are going to do your work, export the location of - the Oracle Java as follows: + the Oracle Java. + The previous step creates a new folder + for the extracted software. + You need to use the following + <filename>export</filename> command + and provide the specific location: <literallayout class='monospaced'> - export PATH=~/jdk1.7.0_40/bin:$PATH - </literallayout></para></listitem> - </orderedlist></para></listitem> + export PATH=~/<replaceable>extracted_jdk_location</replaceable>/bin:$PATH + </literallayout> + </para></listitem> + </orderedlist> + </para></listitem> <listitem><para>In the same shell, create a Git repository with: <literallayout class='monospaced'> $ cd ~ - $ git clone git://git.yoctoproject.org/eclipse-poky-kepler + $ git clone git://git.yoctoproject.org/eclipse-poky + </literallayout> + </para></listitem> + <listitem><para>Be sure to checkout the correct + tag. + For example, if you are using Luna, do the + following: + <literallayout class='monospaced'> + $ git checkout luna/yocto-1.8 </literallayout> + This puts you in a detached HEAD state, which + is fine since you are only going to be building + and not developing. <note> - If you are using Juno, the repository is - located at - <filename>git://git.yoctoproject.org/eclipse-poky-juno</filename>. + If you are building kepler, checkout the + <filename>kepler/yocto-1.8</filename> + branch. </note> - For this example, the repository is named - <filename>~/eclipse-poky-kepler</filename>. </para></listitem> - <listitem><para>Change to the directory where you - set up the Git repository: - <literallayout class='monospaced'> - $ cd ~/eclipse-poky-kepler - </literallayout></para></listitem> - <listitem><para>Be sure you are in the right branch - for your Git repository. - For this release set the branch to - <filename>&DISTRO_NAME;</filename>: - <literallayout class='monospaced'> - $ git checkout &DISTRO_NAME; - </literallayout></para></listitem> <listitem><para>Change to the <filename>scripts</filename> directory within the Git repository: <literallayout class='monospaced'> $ cd scripts - </literallayout></para></listitem> + </literallayout> + </para></listitem> <listitem><para>Set up the local build environment by running the setup script: <literallayout class='monospaced'> $ ./setup.sh - </literallayout></para></listitem> + </literallayout> + </para></listitem> <listitem><para>When the script finishes execution, it prompts you with instructions on how to run the <filename>build.sh</filename> script, which is also in the <filename>scripts</filename> - directory of - the Git repository created earlier. + directory of the Git repository created + earlier. </para></listitem> - <listitem><para>Run the <filename>build.sh</filename> script - as directed. - Be sure to provide the name of the Git branch - along with the Yocto Project release you are - using. + <listitem><para>Run the <filename>build.sh</filename> + script as directed. + Be sure to provide the tag name, documentation + branch, and a release name. Here is an example that uses the - <filename>&DISTRO_NAME;</filename> branch: + <filename>luna/yocto-1.8</filename> tag, the + <filename>master</filename> documentation + branch, and + <filename>&DISTRO_NAME;</filename> for the + release name: <literallayout class='monospaced'> - $ ECLIPSE_HOME=/home/scottrif/eclipse-poky-kepler/scripts/eclipse ./build.sh &DISTRO_NAME; &DISTRO_NAME; + $ ECLIPSE_HOME=/home/scottrif/eclipse-poky/scripts/eclipse ./build.sh luna/yocto-1.8 master &DISTRO_NAME; 2>&1 | tee -a build.log </literallayout> After running the script, the file - <filename>org.yocto.sdk-<release>-<date>-archive.zip</filename> - is in the current directory.</para></listitem> + <filename>org.yocto.sdk-</filename><replaceable>release</replaceable><filename>-</filename><replaceable>date</replaceable><filename>-archive.zip</filename> + is in the current directory. + </para></listitem> <listitem><para>If necessary, start the Eclipse IDE and be sure you are in the Workbench. </para></listitem> - <listitem><para>Select "Install New Software" from the "Help" pull-down menu. + <listitem><para>Select "Install New Software" from + the "Help" pull-down menu. </para></listitem> <listitem><para>Click "Add".</para></listitem> <listitem><para>Provide anything you want in the - "Name" field.</para></listitem> + "Name" field. + </para></listitem> <listitem><para>Click "Archive" and browse to the ZIP file you built in step eight. This ZIP file should not be "unzipped", and must @@ -931,13 +988,24 @@ created by running the <filename>build.sh</filename> script. </para></listitem> - <listitem><para>Click through the "Okay" buttons. + <listitem><para>Click the "OK" button. + </para></listitem> + <listitem><para>Check the boxes that appear in + the installation window to install the + <filename>Yocto Project ADT Plug-in</filename>, + <filename>Yocto Project Bitbake Commander Plug-in</filename>, + and the + <filename>Yocto Project Documentation plug-in</filename>. + </para></listitem> + <listitem><para>Finish the installation by clicking + through the appropriate buttons. + You can click "OK" when prompted about + installing software that contains unsigned + content. </para></listitem> - <listitem><para>Check the boxes - in the installation window and complete - the installation.</para></listitem> <listitem><para>Restart the Eclipse IDE if - necessary.</para></listitem> + necessary. + </para></listitem> </orderedlist> </para> @@ -966,9 +1034,10 @@ Eclipse IDE: <itemizedlist> <listitem><para>Choose "Preferences" from the - "Windows" menu to display the Preferences Dialog. + "Window" menu to display the Preferences Dialog. </para></listitem> - <listitem><para>Click "Yocto Project ADT". + <listitem><para>Click "Yocto Project ADT" to display + the configuration screen. </para></listitem> </itemizedlist> </para> @@ -1044,10 +1113,13 @@ the target hardware resides. If you used the ADT Installer script and accepted the default installation directory, - then the location is - <filename>/opt/poky/&DISTRO;</filename>. + then the location in your home directory + in a folder named + <filename>test-yocto/</filename><replaceable>target_arch</replaceable>. Additionally, when you use the ADT Installer - script, the same location is used for the QEMU + script, the + <filename>/opt/poky/&DISTRO;/sysroots</filename> + location is used for the QEMU user-space tools and the NFS boot process. </para> <para>If you used either of the other two @@ -1172,7 +1244,7 @@ </para></listitem> <listitem><para>Double click <filename>C Project</filename> to create the project.</para></listitem> - <listitem><para>Expand <filename>Yocto Project ADT Project</filename>. + <listitem><para>Expand <filename>Yocto Project ADT Autotools Project</filename>. </para></listitem> <listitem><para>Select <filename>Hello World ANSI C Autotools Project</filename>. This is an Autotools-based project based on a Yocto @@ -1225,14 +1297,9 @@ </para></listitem> <listitem><para>Make your configurations for the project and click "OK". - If you are running the Juno version of Eclipse, you can - skip down to the next section where you build the - project. - If you are not working with Juno, you need to reconfigure the - project as described in the next step. </para></listitem> - <listitem><para>Select "Reconfigure Project" from the - "Project" menu. + <listitem><para>Right-click in the navigation pane and + select "Reconfigure Project" from the pop-up menu. This selection reconfigures the project by running <filename>autogen.sh</filename> in the workspace for your project. @@ -1253,9 +1320,7 @@ <title>Building the Project</title> <para> - To build the project in Juno, right click on the project in - the navigator pane and select "Build Project". - If you are not running Juno, select "Build Project" from the + To build the project select "Build Project" from the "Project" menu. The console should update and you can note the cross-compiler you are using. @@ -1279,7 +1344,8 @@ Your image should appear as a selectable menu item. </para></listitem> <listitem><para>Select your image from the menu to launch - the emulator in a new window.</para></listitem> + the emulator in a new window. + </para></listitem> <listitem><para>If needed, enter your host root password in the shell window at the prompt. This sets up a <filename>Tap 0</filename> connection @@ -1288,9 +1354,10 @@ <listitem><para>Wait for QEMU to launch.</para></listitem> <listitem><para>Once QEMU launches, you can begin operating within that environment. - For example, you could determine the IP Address - for the user-space NFS by using the - <filename>ifconfig</filename> command.</para></listitem> + One useful task at this point would be to determine the + IP Address for the user-space NFS by using the + <filename>ifconfig</filename> command. + </para></listitem> </orderedlist> </para> </section> @@ -1317,7 +1384,7 @@ Use the "Remote Absolute File Path for C/C++Application:" field. For example, enter - <filename>/usr/bin/<programname></filename>. + <filename>/usr/bin/<replaceable>programname</replaceable></filename>. </para></listitem> <listitem><para>Click on the "Debugger" tab to see the cross-tool debugger you are using.</para></listitem> @@ -1334,7 +1401,7 @@ <listitem><para>Use the drop-down menu now in the "Connection" field and pick the IP Address you entered. </para></listitem> - <listitem><para>Click "Run" to bring up a login screen + <listitem><para>Click "Debug" to bring up a login screen and login.</para></listitem> <listitem><para>Accept the debug perspective. </para></listitem> @@ -1351,7 +1418,7 @@ These tools are aids in developing and debugging applications and images. You can run these user-space tools from within the Eclipse - IDE through the "YoctoTools" menu. + IDE through the "YoctoProjectTools" menu. </para> <para> @@ -1392,7 +1459,7 @@ installed by default on the <filename>core-image-sato-sdk</filename> image.</note> </para></listitem> - <listitem><para><emphasis><filename>Lttng2.0 ust trace import</filename>:</emphasis> + <listitem><para><emphasis><filename>Lttng2.0 trace import</filename>:</emphasis> Selecting this tool transfers the remote target's <filename>Lttng</filename> tracing data back to the local host machine and uses the Lttng Eclipse plug-in @@ -1409,13 +1476,15 @@ This tool no longer has any upstream support.</note> </para> <para>Before you use the - <filename>Lttng2.0 ust trace import</filename> tool, + <filename>Lttng2.0 trace import</filename> tool, you need to setup the Lttng Eclipse plug-in and create a Tracing project. Do the following: <orderedlist> <listitem><para>Select "Open Perspective" from the - "Window" menu and then select "Tracing". + "Window" menu and then select "Other..." to + bring up a menu of other perspectives. + Choose "Tracing". </para></listitem> <listitem><para>Click "OK" to change the Eclipse perspective into the Tracing perspective. @@ -1424,11 +1493,14 @@ selecting "Project" from the "File -> New" menu. </para></listitem> <listitem><para>Choose "Tracing Project" from the - "Tracing" menu. + "Tracing" menu and click "Next". + </para></listitem> + <listitem><para>Provide a name for your tracing + project and click "Finish". </para></listitem> <listitem><para>Generate your tracing data on the remote target.</para></listitem> - <listitem><para>Select "Lttng2.0 ust trace import" + <listitem><para>Select "Lttng2.0 trace import" from the "Yocto Project Tools" menu to start the data import process.</para></listitem> <listitem><para>Specify your remote connection name. @@ -1476,129 +1548,33 @@ section in the Yocto Project Profiling and Tracing Manual. </para></listitem> + <listitem><para><emphasis><filename>SystemTap</filename>:</emphasis> + Systemtap is a tool that lets you create and reuse + scripts to examine the activities of a live Linux + system. + You can easily extract, filter, and summarize data + that helps you diagnose complex performance or + functional problems. + For more information on setting up and using + <filename>SystemTap</filename>, see the + <ulink url='https://sourceware.org/systemtap/documentation.html'>SystemTap Documentation</ulink>. + </para></listitem> + <listitem><para><emphasis><filename>yocto-bsp</filename>:</emphasis> + The <filename>yocto-bsp</filename> tool lets you + quickly set up a Board Support Package (BSP) layer. + The tool requires a Metadata location, build location, + BSP name, BSP output location, and a kernel + architecture. + For more information on the + <filename>yocto-bsp</filename> tool outside of Eclipse, + see the + "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a new BSP Layer Using the yocto-bsp Script</ulink>" + section in the Yocto Project Board Support Package + (BSP) Developer's Guide. + </para></listitem> </itemizedlist> </para> </section> - - <section id='customizing-an-image-using-a-bitbake-commander-project-and-hob'> - <title>Customizing an Image Using a BitBake Commander Project and Hob</title> - - <para> - Within the Eclipse IDE, you can create a Yocto BitBake Commander - project, edit the <link linkend='metadata'>Metadata</link>, and - then use - <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink> to build a customized image all within one IDE. - </para> - - <section id='creating-the-yocto-bitbake-commander-project'> - <title>Creating the Yocto BitBake Commander Project</title> - - <para> - To create a Yocto BitBake Commander project, follow these - steps: - <orderedlist> - <listitem><para>Select "Other" from the - "Window -> Open Perspective" menu - and then choose "Bitbake Commander". - </para></listitem> - <listitem><para>Click "OK" to change the perspective to - Bitbake Commander.</para></listitem> - <listitem><para>Select "Project" from the "File -> New" - menu to create a new Yocto - Bitbake Commander project.</para></listitem> - <listitem><para>Choose "New Yocto Project" from the - "Yocto Project Bitbake Commander" menu and click - "Next".</para></listitem> - <listitem><para>Enter the Project Name and choose the - Project Location. - The Yocto project's Metadata files will be put under - the directory - <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> - command to get the project's Metadata files. - <note> - Do not specify your BitBake Commander project - location as your Eclipse workspace. - Doing so causes an error indicating that the - current project overlaps the location of - another project. - This error occurs even if no such project exits. - </note></para></listitem> - <listitem><para>Select <filename>Finish</filename> to - create the project.</para></listitem> - </orderedlist> - </para> - </section> - - <section id='editing-the-metadata'> - <title>Editing the Metadata</title> - - <para> - After you create the Yocto Bitbake Commander project, you - can modify the <link linkend='metadata'>Metadata</link> - files by opening them in the project. - When editing recipe files (<filename>.bb</filename> files), - you can view BitBake variable values and information by - hovering the mouse pointer over the variable name and - waiting a few seconds. - </para> - - <para> - To edit the Metadata, follow these steps: - <orderedlist> - <listitem><para>Select your Yocto Bitbake Commander - project.</para></listitem> - <listitem><para>Select "BitBake Recipe" from the - "File -> New -> Yocto BitBake Commander" menu - to open a new recipe wizard.</para></listitem> - <listitem><para>Point to your source by filling in the - "SRC_URL" field. - For example, you can add a recipe to your - <link linkend='source-directory'>Source Directory</link> - by defining "SRC_URL" as follows: - <literallayout class='monospaced'> - ftp://ftp.gnu.org/gnu/m4/m4-1.4.9.tar.gz - </literallayout></para></listitem> - <listitem><para>Click "Populate" to calculate the - archive md5, sha256, license checksum values and to - auto-generate the recipe filename.</para></listitem> - <listitem><para>Fill in the "Description" field. - </para></listitem> - <listitem><para>Be sure values for all required - fields exist.</para></listitem> - <listitem><para>Click "Finish".</para></listitem> - </orderedlist> - </para> - </section> - - <section id='biding-and-customizing-the-image-using-hob'> - <title>Building and Customizing the Image Using Hob</title> - - <para> - To build and customize the image using Hob from within the - Eclipse IDE, follow these steps: - <orderedlist> - <listitem><para>Select your Yocto Bitbake Commander - project.</para></listitem> - <listitem><para>Select "Launch Hob" from the "Project" - menu.</para></listitem> - <listitem><para>Enter the - <link linkend='build-directory'>Build Directory</link> - where you want to put your final images. - </para></listitem> - <listitem><para>Click "OK" to launch Hob. - </para></listitem> - <listitem><para>Use Hob to customize and build your own - images. - For information on Hob, see the - <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob Project Page</ulink> - on the Yocto Project website.</para></listitem> - </orderedlist> - </para> - </section> - </section> </section> <section id='workflow-using-stand-alone-cross-development-toolchains'> @@ -1666,123 +1642,677 @@ </section> </section> -<section id="modifying-temporary-source-code"> - <title>Modifying Temporary Source Code</title> +<section id="dev-modifying-source-code"> + <title>Modifying Source Code</title> <para> - You might - find it helpful during development to modify the temporary source code used by recipes - to build packages. - For example, suppose you are developing a patch and you need to experiment a bit - to figure out your solution. - After you have initially built the package, you can iteratively tweak the - source code, which is located in the - <link linkend='build-directory'>Build Directory</link>, and then - you can force a re-compile and quickly test your altered code. - Once you settle on a solution, you can then preserve your changes in the form of - patches. - You can accomplish these steps all within either a - <ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink> or - <link linkend='git'>Git</link> workflow. + A common development workflow consists of modifying project source + files that are external to the Yocto Project and then integrating + that project's build output into an image built using the + OpenEmbedded build system. + Given this scenario, development engineers typically want to stick + to their familiar project development tools and methods, which allows + them to just focus on the project. </para> - <section id='finding-the-temporary-source-code'> - <title>Finding the Temporary Source Code</title> + <para> + Several workflows exist that allow you to develop, build, and test + code that is going to be integrated into an image built using the + OpenEmbedded build system. + This section describes two: + <itemizedlist> + <listitem><para><emphasis><filename>devtool</filename>:</emphasis> + A set of tools to aid in working on the source code built by + the OpenEmbedded build system. + Section + "<link linkend='using-devtool-in-your-workflow'>Using <filename>devtool</filename> in Your Workflow</link>" + describes this workflow. + If you want more information that showcases the workflow, click + <ulink url='https://drive.google.com/a/linaro.org/file/d/0B3KGzY5fW7laTDVxUXo3UDRvd2s/view'>here</ulink> + for an excellent presentation by Trevor Woerner that + provides detailed background information and a complete + working tutorial. + </para></listitem> + <listitem><para><emphasis><ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink>:</emphasis> + A powerful tool that allows you to capture source + code changes without having a clean source tree. + While Quilt is not the preferred workflow of the two, this + section includes it for users that are committed to using + the tool. + See the + "<link linkend='using-a-quilt-workflow'>Using Quilt in Your Workflow</link>" + section for more information. + </para></listitem> + </itemizedlist> + </para> + + <section id='using-devtool-in-your-workflow'> + <title>Using <filename>devtool</filename> in Your Workflow</title> <para> - During a build, the unpacked temporary source code used by recipes - to build packages is available in the Build Directory as - defined by the - <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename> variable. - Below is the default value for the <filename>S</filename> variable as defined in the - <filename>meta/conf/bitbake.conf</filename> configuration file in the - <link linkend='source-directory'>Source Directory</link>: - <literallayout class='monospaced'> - S = "${WORKDIR}/${BP}" - </literallayout> - You should be aware that many recipes override the <filename>S</filename> variable. - For example, recipes that fetch their source from Git usually set - <filename>S</filename> to <filename>${WORKDIR}/git</filename>. + As mentioned earlier, <filename>devtool</filename> helps + you easily develop projects whose build output must be part of + an image built using the OpenEmbedded build system. + The remainder of this section presents the workflow you would + use that includes <filename>devtool</filename>. + <footnote> + <para> + Kudos and thanks to + <ulink url='mailto:twoerner@gmail.com'>Trevor Woerner</ulink> + whose + "<ulink url='https://drive.google.com/file/d/0B3KGzY5fW7laTDVxUXo3UDRvd2s/view'>Yocto Project Developer Workflow Tutorial</ulink>" + paper contributed nicely towards the development of this + section. + </para> + </footnote> <note> - The - <ulink url='&YOCTO_DOCS_REF_URL;#var-BP'><filename>BP</filename></ulink> - represents the base recipe name, which consists of the name and version: - <literallayout class='monospaced'> - BP = "${BPN}-${PV}" - </literallayout> + The workflow considers the entire build process for the + image and not just modification of the external source + code. </note> </para> - <para> - The path to the work directory for the recipe - (<ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>) - is defined as follows: - <literallayout class='monospaced'> - ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR} - </literallayout> - The actual directory depends on several things: - <itemizedlist> - <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>: - The top-level build output directory</listitem> - <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></ulink>: - The target system identifier</listitem> - <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>: - The recipe name</listitem> - <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTENDPE'><filename>EXTENDPE</filename></ulink>: - The epoch - (if - <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink> - is not specified, which is usually the case for most - recipes, then <filename>EXTENDPE</filename> is blank)</listitem> - <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>: - The recipe version</listitem> - <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>: - The recipe revision</listitem> - </itemizedlist> - </para> + <section id='establish-the-reference-image'> + <title>Establish the Reference Image</title> - <para> - As an example, assume a Source Directory top-level folder - name <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.bb</filename>. - In this case, the work directory the build system uses to - build the package would be as follows: - <literallayout class='monospaced'> - poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0 - </literallayout> - </para> + <para> + The steps to clone the <filename>poky</filename> Git + repository, build out an image, and test it using QEMU + are well documented as follows: + <itemizedlist> + <listitem><para> + For information on how to set up a local copy of the + <filename>poky</filename> repository and on how to + build a Yocto Project image, see the + "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" + section in the Yocto Project Quick Start. + </para></listitem> + <listitem><para> + For information on how to test an image using QEMU, see + the + "<link linkend='dev-manual-qemu'>Using the Quick EMUlator (QEMU)</link>" + section. + </para></listitem> + </itemizedlist> + </para> + + <para> + Before you start making modifications to your project's + source code, you should be sure you have the appropriate + local repositories and have a base image built using + BitBake that you can run on QEMU. + </para> + </section> + + <section id='update-your-external-source'> + <title>Update Your External Source</title> + + <para> + Part of the development flow using + <filename>devtool</filename> of course involves updating + your source files. + Several opportunities exist in the workflow to extract and + work on the files. + For now, just realize that you need to be able to have + access to and edit files. + One obvious solution is to initially extract the code into an + isolated area in preparation for modification. + </para> + + <para> + Another option is to use the + <filename>devtool modify</filename> command. + This command makes use of a "workspace" layer where much of + the transitional work occurs, which is needed for setting up + Metadata used by the OpenEmbedded build system that lets you + build your software. + Options (i.e. "-x") exist using <filename>devtool</filename> + that enable you to use the tool to extract source code. + </para> + </section> + + <section id='use-devtool-to-integrate-your-code-with-the-image'> + <title>Use <filename>devtool add</filename> to Integrate Your Code with the Image</title> + + <para> + The <filename>devtool add</filename> command automatically + generates the needed Metadata that allows the OpenEmbedded + build system to build your code into the image. + <note> + If a package or packages produced by the recipe on which + you are working are not already in + <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink> + for the image, you must add them. + The <filename>devtool add</filename> command does not + add them for you. + </note> + Use the following command form: + <literallayout class='monospaced'> + $ devtool add <replaceable>your-project-name</replaceable> <replaceable>path-to-source</replaceable> + </literallayout> + Running <filename>devtool add</filename> modifies the + <filename>bblayers.conf</filename> that the + OpenEmbedded build system uses to build an image. + For more information on the <filename>bblayers.conf</filename>, + see the + "<ulink url='&YOCTO_DOCS_REF_URL;#structure-build-conf-bblayers.conf'><filename>build/conf/bblayers.conf</filename></ulink>" + section in the Yocto Project Reference Manual. + </para> + + <para> + Running <filename>devtool add</filename> adds a new workspace + layer to the <filename>bblayers.conf</filename> file that + is based on your project's location: + <literallayout class='monospaced'> + <replaceable>path-to-source</replaceable>/<replaceable>build-directory</replaceable>/<replaceable>workspace-layer</replaceable> + </literallayout> + By default, the name of the workspace layer is "workspace". + </para> + + <para> + For details on the workspace layer created in the + <replaceable>build-directory</replaceable>, + see the + "<link linkend='devtool-adding-a-new-recipe-to-the-workspace'>Adding a New Recipe to the Workspace Layer</link>" + section. + </para> + +<!-- + <para> + Of course, each layer must have a + <filename>layer.conf</filename> configuration file. + <filename>devtool</filename> also creates this configuration + file: + <literallayout class='monospaced'> + $ cat workspace/conf/layer.conf + # ### workspace layer autogenerated by devtool ### + BBPATH =. "${LAYERDIR}:" + BBFILES += "${LAYERDIR}/recipes/*/*.bb \ + ${LAYERDIR}/appends/*.bbappend" + BBFILE_COLLECTIONS += "workspacelayer" + BBFILE_PATTERN_workspacelayer = "^${LAYERDIR}/" + BBFILE_PATTERN_IGNORE_EMPTY_workspacelayer = "1" + BBFILE_PRIORITY_workspacelayer = "99" + </literallayout> + </para> +--> + + <para> + Running <filename>devtool add</filename> automatically + generates your recipe: + <literallayout class='monospaced'> + $ cat workspace/recipes/<replaceable>your-project-name</replaceable>/<replaceable>your-project-name</replaceable>.bb + # Recipe created by recipetool + # This is the basis of a recipe and may need further editing in order to be fully functional. + # (Feel free to remove these comments when editing.) + # + # Unable to find any files that looked like license statements. Check the accompanying + # documentation and source headers and set LICENSE and LIC_FILES_CHKSUM accordingly. + LICENSE = "CLOSED" + LIC_FILES_CHKSUM = "" + + # No information for SRC_URI yet (only an external source tree was + # specified) + SRC_URI = "" + + DEPENDS = "libx11" + # NOTE: if this software is not capable of being built in a separate build directory + # from the source, you should replace autotools with autotools-brokensep in the + # inherit line + inherit autotools + + # Specify any options you want to pass to the configure script using EXTRA_OECONF: + EXTRA_OECONF = "" + </literallayout> + </para> + + <para> + Lastly, the <filename>devtool add</filename> command creates the + <filename>.bbappend</filename> file: + <literallayout class='monospaced'> + $ cat workspace/appends/<replaceable>your-project-name</replaceable>.bbappend + inherit externalsrc + EXTERNALSRC = "/<replaceable>path-to-source</replaceable>/<replaceable>your-project-name</replaceable>" + + # initial_rev: <replaceable>commit-ID</replaceable> + </literallayout> + </para> + </section> + + <section id='build-your-project'> + <title>Build Your Project</title> + + <para> + You can use BitBake or <filename>devtool build</filename> to + build your modified project. + </para> + + <para> + To use BitBake, use the following: + <literallayout class='monospaced'> + $ bitbake <replaceable>your-project-name</replaceable> + </literallayout> + Alternatively, you can use + <filename>devtool build</filename>, which is equivalent to + <filename>bitbake -c populate_sysroot</filename>. + For example: + <literallayout class='monospaced'> + $ devtool build <replaceable>your-project-name</replaceable> + </literallayout> + </para> + </section> + + <section id='dev-build-the-image'> + <title>Build the Image</title> + + <para> + The final step before testing is to rebuild the base image + with your project changes as part of the image. + Simply run BitBake again on your image. + Here is an example: + <literallayout class='monospaced'> + $ bitbake <replaceable>image</replaceable> + </literallayout> + </para> + </section> + + <section id='dev-testing-the-image'> + <title>Testing the Image</title> + + <para> + Once you have the image, you can test it using QEMU. + Here is an example assuming "qemux86": + <literallayout class='monospaced'> + $ runqemu qemux86 <replaceable>image</replaceable> + </literallayout> + For information on how to test an image using QEMU, see the + "<link linkend='dev-manual-qemu'>Using the Quick EMUlator (QEMU)</link>" + section. + </para> + </section> + </section> + + <section id='devtool-quick-reference'> + <title><filename>devtool</filename> Quick Reference</title> <para> - Now that you know where to locate the directory that has the temporary source code, - you can use a Quilt or Git workflow to make your edits, test the changes, - and preserve the changes in the form of patches. + <filename>devtool</filename> has more functionality than simply + adding a new recipe and the supporting Metadata to a temporary + workspace layer. + This section provides a short reference on + <filename>devtool</filename> for most of the commands. </para> + + <section id='devtool-getting-help'> + <title>Getting Help</title> + + <para> + The easiest way to get help with the + <filename>devtool</filename> command is using the + <filename>--help</filename> option: + <literallayout class='monospaced'> + $ devtool --help + usage: devtool [-h] [--basepath BASEPATH] [-d] [-q] [--color COLOR] + <subcommand> ... + + OpenEmbedded development tool + + optional arguments: + -h, --help show this help message and exit + --basepath BASEPATH Base directory of SDK / build directory + -d, --debug Enable debug output + -q, --quiet Print only errors + --color COLOR Colorize output (where COLOR is auto, always, never) + + subcommands: + <subcommand> + create-workspace Set up a workspace + deploy-target Deploy recipe output files to live target machine + undeploy-target Undeploy recipe output files in live target machine + add Add a new recipe + modify Modify the source for an existing recipe + extract Extract the source for an existing recipe + update-recipe Apply changes from external source tree to recipe + status Show workspace status + build Build a recipe + reset Remove a recipe from your workspace + + Use devtool <subcommand> --help to get help on a specific command + </literallayout> + </para> + + <para> + As directed in the general help output, you can get more + syntax on a specific command by providing the command + name and using <filename>--help</filename>: + <literallayout class='monospaced'> + $ devtool add --help + usage: devtool add [-h] [--same-dir] [--version VERSION] recipename srctree + + Adds a new recipe + + positional arguments: + recipename Name for new recipe to add + srctree Path to external source tree + + optional arguments: + -h, --help show this help message and exit + --same-dir, -s Build in same directory as source (default: False) + --version VERSION, -V VERSION + Version to use within recipe (PV) (default: None) + </literallayout> + </para> + </section> + + <section id='devtool-adding-a-new-recipe-to-the-workspace'> + <title>Adding a New Recipe to the Workspace Layer</title> + + <para> + Use the <filename>devtool add</filename> command to add a new recipe + to the workspace layer. + The recipe you add should not exist - + <filename>devtool</filename> creates it for you. + The source files the recipe uses should exist in an external + area. + </para> + + <para> + The following example creates and adds a new recipe named + <filename>jackson-2.0</filename> to the workspace layer. + The source code built by the recipes resides in + <filename>/home/scottrif/sources/jackson</filename>: + <literallayout class='monospaced'> + $ devtool add jackson-2.0 /home/scottrif/sources/jackson + </literallayout> + <note> + For complete syntax, use the + <filename>devtool add --help</filename> command. + </note> + </para> + + <para> + If you add a recipe and the workspace layer does not exist, + the command creates the layer and populates it as follows: + </para> + + <para> + <imagedata fileref="figures/build-workspace-directory.png" + width="6in" depth="4in" align="center" scale="100" /> + </para> + + <para> + <literallayout class='monospaced'> + README - Provides information on what is in workspace layer and how to + manage it. + + appends - A directory that contains *.bbappend files, which point to + external source. + + conf - A configuration directory that contains the layer.conf file. + + recipes - A directory containing recipes. This directory contains a + folder for each directory added whose name matches that of the + added recipe. devtool places the <replaceable>recipe</replaceable>.bb file + within that sub-directory. + </literallayout> + </para> + + <para> + Running <filename>devtool add</filename> when the + workspace layer exists causes the tool to add the recipe + and append files into the existing workspace layer. + The <filename>.bbappend</filename> file is created to point + to the external source tree. + </para> + </section> + + <section id='devtool-creating-the-workspace'> + <title>Creating the Workspace Layer</title> + + <para> + Use the <filename>devtool create-workspace</filename> command to + create a new workspace layer in your + <link linkend='build-directory'>Build Directory</link>. + When you create a new workspace layer, it is populated with the + <filename>README</filename> file and the + <filename>conf</filename> directory only. + </para> + + <para> + The following example creates a new workspace layer in your + current working and by default names the workspace layer + "workspace": + <literallayout class='monospaced'> + $ devtool create-workspace + </literallayout> + <note> + For complete syntax, use the + <filename>devtool create-workspace --help</filename> command. + </note> + </para> + + <para> + You can create a workspace layer anywhere by supplying + a pathname with the command. + The following command creates a new workspace layer named + "new-workspace": + <literallayout class='monospaced'> + $ devtool create-workspace /home/scottrif/new-workspace + </literallayout> + </para> + </section> + + <section id='devtool-modifying-a-recipe'> + <title>Modifying a Recipe</title> + + <para> + Use the <filename>devtool modify</filename> command to begin + modifying the source of an existing recipe. + This command is very similar to the + <link linkend='devtool-adding-a-new-recipe-to-the-workspace'><filename>add</filename></link> + command except that it does not physically create the + recipe in the workspace layer because the recipe already + exists in an another layer. + </para> + + <para> + The <filename>devtool modify</filename> command extracts the + source for a recipe, sets it up as a Git repository if the + source had not already been fetched from Git, checks out a + branch for development, and applies any patches from the recipe + as commits on top. + You can use the following command to checkout the source + files: + <literallayout class='monospaced'> + $ devtool modify -x <replaceable>recipe</replaceable> <replaceable>path-to-source</replaceable> + </literallayout> + Using the above command form, the default development branch + would be "devtool". + </para> + + <para> + If you want to name a development branch, use the + <filename>-b</filename> option with the + <filename>-x</filename> option: + <literallayout class='monospaced'> + $ devtool modify -x -b <replaceable>branch</replaceable> <replaceable>recipe</replaceable> <replaceable>path-to-source</replaceable> + </literallayout> + <note> + For complete syntax, use the + <filename>devtool modify --help</filename> command. + </note> + </para> + </section> + + <section id='devtool-resetting-a-recipe'> + <title>Resetting a Recipe</title> + + <para> + Use the <filename>devtool reset</filename> command to remove a + recipe and its configuration (e.g. the corresponding + <filename>.bbappend</filename> file) from the workspace layer. + Realize that this command deletes the recipe and the + append file. + The command does not physically move them for you. + Consequently, you must be sure to physically relocate your + updated recipe and the append file outside of the workspace + layer before running the <filename>devtool reset</filename> + command. + </para> + + <para> + If the <filename>devtool reset</filename> command detects that + the recipe or the append files have been modified, the + command preserves the modified files in a separate "attic" + subdirectory under the workspace layer. + <note> + For complete syntax, use the + <filename>devtool reset --help</filename> command. + </note> + </para> + </section> + + <section id='devtool-updating-a-recipe'> + <title>Updating a Recipe</title> + + <para> + Use the <filename>devtool update-recipe</filename> command to + update your recipe with patches that reflect changes you make + to the source files. + For example, if you know you are going to work on some + code, you could first use the + <link linkend='devtool-modifying-a-recipe'><filename>devtool modify</filename></link> + command to extract the code and set up the workspace. + After which, you could modify, compile, and test the code. + When you are satisfied with the results you can then + run the <filename>devtool update-recipe</filename> to create the + patches and update the recipe: + <literallayout class='monospaced'> + $ devtool update-recipe <replaceable>recipe</replaceable> + </literallayout> + <note> + For complete syntax, use the + <filename>devtool update-recipe --help</filename> command. + </note> + </para> + </section> + + <section id='devtool-building-your-software'> + <title>Building Your Software</title> + + <para> + Use the <filename>devtool build</filename> command to cause the + OpenEmbedded build system to build your software based + on the recipe file. + The <filename>devtool build</filename> command is equivalent to + <filename>bitbake -c populate_sysroot</filename>. + Here is an example: + <literallayout class='monospaced'> + $ devtool build <replaceable>recipe</replaceable> + </literallayout> + <note> + For complete syntax, use the + <filename>devtool update-recipe --help</filename> command. + </note> + Building your software using <filename>devtool build</filename> + is identical to using BitBake to build the software. + </para> + </section> + + <section id='devtool-deploying-your-software-on-the-target-machine'> + <title>Deploying Your Software on the Target Machine</title> + + <para> + Use the <filename>devtool deploy-target</filename> command to + deploy the recipe's build output to the live target machine: + <literallayout class='monospaced'> + $ devtool deploy-target <replaceable>recipe</replaceable> <replaceable>target</replaceable> + </literallayout> + The <replaceable>target</replaceable> is the address of the + target machine, which must be running an SSH server (i.e. + <filename>user@hostname[:destdir]</filename>). + </para> + + <para> + This command deploys all files installed during the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink> + task. + Furthermore, you do not need to have package management enabled + within the target machine. + If you do, the package manager is bypassed. + <note><title>Notes</title> + <para> + The <filename>deploy-target</filename> + functionality is for development only. + You should never use it to update an image that will be + used in production. + </para> + + <para> + For complete syntax, use the + <filename>devtool deploy-target --help</filename> + command. + </para> + </note> + </para> + </section> + + <section id='devtool-removing-your-software-from-the-target-machine'> + <title>Removing Your Software from the Target Machine</title> + + <para> + Use the <filename>devtool undeploy-target</filename> command to + remove deployed build output from the target machine. + For the <filename>devtool undeploy-target</filename> command to + work, you must have previously used the + <link linkend='devtool-deploying-your-software-on-the-target-machine'><filename>devtool deploy-target</filename></link> + command. + <literallayout class='monospaced'> + $ devtool undeploy-target <replaceable>recipe</replaceable> <replaceable>target</replaceable> + </literallayout> + The <replaceable>target</replaceable> is the address of the + target machine, which must be running an SSH server (i.e. + <filename>user@hostname</filename>). + <note> + For complete syntax, use the + <filename>devtool undeploy-target --help</filename> command. + </note> + </para> + </section> </section> <section id="using-a-quilt-workflow"> - <title>Using a Quilt Workflow</title> + <title>Using Quilt in Your Workflow</title> <para> <ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink> - is a powerful tool that allows you to capture source code changes without having - a clean source tree. - This section outlines the typical workflow you can use to modify temporary source code, - test changes, and then preserve the changes in the form of a patch all using Quilt. + is a powerful tool that allows you to capture source code changes + without having a clean source tree. + This section outlines the typical workflow you can use to modify + source code, test changes, and then preserve the changes in the + form of a patch all using Quilt. + <note><title>Tip</title> + With regard to preserving changes to source files if you + clean a recipe or have <filename>rm_work</filename> enabled, + the workflow described in the + "<link linkend='using-devtool-in-your-workflow'>Using <filename>devtool</filename> in Your Workflow</link>" + section is a safer development flow than than the flow that + uses Quilt. + </note> </para> <para> Follow these general steps: <orderedlist> <listitem><para><emphasis>Find the Source Code:</emphasis> - The temporary source code used by the OpenEmbedded build system is kept in the - Build Directory. + Temporary source code used by the OpenEmbedded build system + is kept in the + <link linkend='build-directory'>Build Directory</link>. See the - "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>" - section to learn how to locate the directory that has the temporary source code for a - particular package.</para></listitem> + "<link linkend='finding-the-temporary-source-code'>Finding Temporary Source Code</link>" + section to learn how to locate the directory that has the + temporary source code for a particular package. + </para></listitem> <listitem><para><emphasis>Change Your Working Directory:</emphasis> You need to be in the directory that has the temporary source code. That directory is defined by the @@ -1803,15 +2333,16 @@ </literallayout> </para></listitem> <listitem><para><emphasis>Edit the Files:</emphasis> - Make your changes in the temporary source code to the files you added - to the patch.</para></listitem> + Make your changes in the source code to the files you added + to the patch. + </para></listitem> <listitem><para><emphasis>Test Your Changes:</emphasis> Once you have modified the source code, the easiest way to your changes is by calling the <filename>do_compile</filename> task as shown in the following example: <literallayout class='monospaced'> - $ bitbake -c compile -f <replaceable>name_of_package</replaceable> + $ bitbake -c compile -f <replaceable>package</replaceable> </literallayout> The <filename>-f</filename> or <filename>--force</filename> option forces the specified task to execute. @@ -1823,9 +2354,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 <replaceable>name_of_package</replaceable></filename> + <filename>bitbake -c clean <replaceable>package</replaceable></filename> and - <filename>bitbake -c cleanall <replaceable>name_of_package</replaceable></filename>). + <filename>bitbake -c cleanall <replaceable>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>" @@ -1856,142 +2387,119 @@ <literallayout class='monospaced'> SRC_URI += "file://my_changes.patch" </literallayout></para></listitem> - <listitem><para><emphasis>Increment the Recipe Revision Number:</emphasis> - Finally, don't forget to 'bump' the - <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink></filename> - value in the recipe since the resulting packages have changed.</para></listitem> </orderedlist> - </para> </section> + </para> + </section> + + <section id='finding-the-temporary-source-code'> + <title>Finding Temporary Source Code</title> - <section id='using-a-git-workflow'> - <title>Using a Git Workflow</title> <para> - Git is an even more powerful tool that allows you to capture source code changes without having - a clean source tree. - This section outlines the typical workflow you can use to modify temporary source code, - test changes, and then preserve the changes in the form of a patch all using Git. - For general information on Git as it is used in the Yocto Project, see the - "<link linkend='git'>Git</link>" section. + You might find it helpful during development to modify the + temporary source code used by recipes to build packages. + For example, suppose you are developing a patch and you need to + experiment a bit to figure out your solution. + After you have initially built the package, you can iteratively + tweak the source code, which is located in the + <link linkend='build-directory'>Build Directory</link>, and then + you can force a re-compile and quickly test your altered code. + Once you settle on a solution, you can then preserve your changes + in the form of patches. + If you are using Quilt for development, see the + "<link linkend='using-a-quilt-workflow'>Using Quilt in Your Workflow</link>" + section for more information. </para> - <note> - This workflow uses Git only for its ability to manage local changes to the source code - and produce patches independent of any version control system used with the Yocto Project. - </note> + <para> + During a build, the unpacked temporary source code used by recipes + to build packages is available in the Build Directory as + defined by the + <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename> variable. + Below is the default value for the <filename>S</filename> variable as defined in the + <filename>meta/conf/bitbake.conf</filename> configuration file in the + <link linkend='source-directory'>Source Directory</link>: + <literallayout class='monospaced'> + S = "${WORKDIR}/${BP}" + </literallayout> + You should be aware that many recipes override the <filename>S</filename> variable. + For example, recipes that fetch their source from Git usually set + <filename>S</filename> to <filename>${WORKDIR}/git</filename>. + <note> + The + <ulink url='&YOCTO_DOCS_REF_URL;#var-BP'><filename>BP</filename></ulink> + represents the base recipe name, which consists of the name and version: + <literallayout class='monospaced'> + BP = "${BPN}-${PV}" + </literallayout> + </note> + </para> <para> - Follow these general steps: - <orderedlist> - <listitem><para><emphasis>Find the Source Code:</emphasis> - The temporary source code used by the OpenEmbedded build system is kept in the - Build Directory. - See the - "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>" - section to learn how to locate the directory that has the temporary source code for a - particular package.</para></listitem> - <listitem><para><emphasis>Change Your Working Directory:</emphasis> - You need to be in the directory that has the temporary source code. - That directory is defined by the - <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink> - variable.</para></listitem> - <listitem><para><emphasis>If needed, initialize a Git Repository:</emphasis> - If the recipe you are working with does not use a Git fetcher, - you need to set up a Git repository as follows: - <literallayout class='monospaced'> - $ git init - $ git add * - $ git commit -m "initial revision" - </literallayout> - The above Git commands initialize a Git repository that is based on the - files in your current working directory, stage all the files, and commit - the files. - At this point, your Git repository is aware of all the source code files. - Any edits you now make to files can be committed later and will be tracked by - Git.</para></listitem> - <listitem><para><emphasis>Edit the Files:</emphasis> - Make your changes to the temporary source code.</para></listitem> - <listitem><para><emphasis>Test Your Changes:</emphasis> - Once you have modified the source code, the easiest way - to test your changes is by calling the - <filename>do_compile</filename> task as shown in the - following example: - <literallayout class='monospaced'> - $ 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. - If you find problems with your code, you can just keep editing and - re-testing iteratively until things work as expected. - <note>All the modifications you make to the temporary source code - disappear once you <filename>-c clean</filename>, <filename>-c cleansstate</filename>, - or <filename>-c cleanall</filename> with BitBake for the package. - 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>" - section of the Yocto Project Quick Start. - </note></para></listitem> - <listitem><para><emphasis>See the List of Files You Changed:</emphasis> - Use the <filename>git status</filename> command to see what files you have actually edited. - The ability to have Git track the files you have changed is an advantage that this - workflow has over the Quilt workflow. - Here is the Git command to list your changed files: - <literallayout class='monospaced'> - $ git status - </literallayout></para></listitem> - <listitem><para><emphasis>Stage the Modified Files:</emphasis> - Use the <filename>git add</filename> command to stage the changed files so they - can be committed as follows: - <literallayout class='monospaced'> - $ git add file1.c file2.c file3.c - </literallayout></para></listitem> - <listitem><para><emphasis>Commit the Staged Files and View Your Changes:</emphasis> - Use the <filename>git commit</filename> command to commit the changes to the - local repository. - 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 "<replaceable>commit-summary-message</replaceable>" - $ git log - </literallayout> - <note>The name of the patch file created in the next step is based on your - <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: - <literallayout class='monospaced'> - $ git format-patch -1 - </literallayout> - Specifying "-1" causes Git to generate the - patch file for the most recent commit.</para> - <para>At this point, the patch file has all your edits made - to the <filename>file1.c</filename>, <filename>file2.c</filename>, and - <filename>file3.c</filename> files. - You can find the resulting patch file in the current directory and it - is named according to the <filename>git commit</filename> summary line. - The patch file ends with <filename>.patch</filename>.</para></listitem> - <listitem><para><emphasis>Copy the Patch File:</emphasis> - For simplicity, copy the patch file into a directory named <filename>files</filename>, - which you can create in the same directory that holds the recipe - (<filename>.bb</filename>) file or the - append (<filename>.bbappend</filename>) file. - Placing the patch here guarantees that the OpenEmbedded build system will find - the patch. - Next, add the patch into the - <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename> - of the recipe. - Here is an example: - <literallayout class='monospaced'> - 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 - <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink></filename> - value in the recipe since the resulting packages have changed.</para></listitem> - </orderedlist> + The path to the work directory for the recipe + (<ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>) + is defined as follows: + <literallayout class='monospaced'> + ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR} + </literallayout> + The actual directory depends on several things: + <itemizedlist> + <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>: + The top-level build output directory</listitem> + <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></ulink>: + The target system identifier</listitem> + <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>: + The recipe name</listitem> + <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTENDPE'><filename>EXTENDPE</filename></ulink>: + The epoch - (if + <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink> + is not specified, which is usually the case for most + recipes, then <filename>EXTENDPE</filename> is blank)</listitem> + <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>: + The recipe version</listitem> + <listitem><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>: + The recipe revision</listitem> + </itemizedlist> + </para> + + <para> + 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.bb</filename>. + In this case, the work directory the build system uses to + build the package would be as follows: + <literallayout class='monospaced'> + poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0 + </literallayout> + </para> + + <para> + Now that you know where to locate the directory that has the + temporary source code, you can use a Quilt as described in section + "<link linkend='using-a-quilt-workflow'>Using Quilt in Your Workflow</link>" + to make your edits, test the changes, and preserve the changes in + the form of patches. </para> </section> </section> +<section id='image-development-using-toaster'> + <title>Image Development Using Toaster</title> + + <para> + Toaster is a web interface to the Yocto Project's OpenEmbedded build + system. + You can initiate builds using Toaster as well as examine the results + and statistics of builds. + See the + <ulink url='&YOCTO_DOCS_TOAST_URL;#toaster-manual-intro'>Toaster User Manual</ulink> + for information on how to set up and use Toaster to build images. + </para> +</section> + <section id='image-development-using-hob'> <title>Image Development Using Hob</title> @@ -2107,6 +2615,3 @@ </section> </chapter> -<!-- -vim: expandtab tw=80 ts=4 ---> diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml index 2385187f4d..2c5fa683e0 100644 --- a/documentation/dev-manual/dev-manual-newbie.xml +++ b/documentation/dev-manual/dev-manual-newbie.xml @@ -588,13 +588,6 @@ Directory. </note> </para></listitem> - <listitem><para id='build-system-term'><emphasis>Build System:</emphasis> - In the context of the Yocto Project, - this term refers to the OpenEmbedded build system used by the project. - This build system is based on the project known as "Poky." - For some historical information about Poky, see the - <link linkend='poky'>Poky</link> term. - </para></listitem> <listitem><para><emphasis>Classes:</emphasis> Files that provide for logic encapsulation and inheritance so that commonly used patterns can be defined once and then easily used in multiple recipes. @@ -690,6 +683,23 @@ with OpenEmbedded (OE) that is shared between OE and the Yocto Project. This Metadata is found in the <filename>meta</filename> directory of the <link linkend='source-directory'>Source Directory</link>.</para></listitem> + <listitem><para id='build-system-term'><emphasis>OpenEmbedded Build System:</emphasis> + The build system specific to the Yocto Project. + The OpenEmbedded build system is based on another project known + as "Poky", which uses + <link linkend='bitbake-term'>BitBake</link> as the task + executor. + Throughout the Yocto Project documentation set, the + OpenEmbedded build system is sometimes referred to simply + as "the build system". + If other build systems, such as a host or target build system + are referenced, the documentation clearly states the + difference. + <note> + For some historical information about Poky, see the + <link linkend='poky'>Poky</link> term. + </note> + </para></listitem> <listitem><para><emphasis>Package:</emphasis> In the context of the Yocto Project, this term refers to a recipe's packaged output produced by BitBake (i.e. a @@ -720,18 +730,29 @@ A package group is really just another recipe. Because package group files are recipes, they end with the <filename>.bb</filename> filename extension.</para></listitem> - <listitem><para id='poky'><emphasis>Poky:</emphasis> The term "poky" can mean several things. - In its most general sense, it is an open-source project that was initially developed - by OpenedHand. With OpenedHand, poky was developed off of the existing OpenEmbedded - build system becoming a build system for embedded images. - After Intel Corporation acquired OpenedHand, the project poky became the basis for - the Yocto Project's build system.</para> - <para> - Within the Yocto Project source repositories, <filename>poky</filename> - exists as a separate Git repository - that can be cloned to yield a local copy on the host system. - Thus, "poky" can refer to the local copy of the Source Directory used to develop within - the Yocto Project.</para></listitem> + <listitem><para id='poky'><emphasis>Poky:</emphasis> + The term "poky" can mean several things. + In its most general sense, it is an open-source + project that was initially developed by OpenedHand. + With OpenedHand, poky was developed off of the existing + OpenEmbedded build system becoming a commercially + supportable build system for embedded Linux. + After Intel Corporation acquired OpenedHand, the + project poky became the basis for the Yocto Project's + build system.</para> + <para>Within the Yocto Project source repositories, + <filename>poky</filename> exists as a separate Git + repository you can clone to yield a local copy on your + host system. + Thus, "poky" can refer to the local copy of the Source + Directory used for development within the Yocto + Project.</para> + <para>Finally, "poky" can refer to the default + <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink> + (i.e. distribution) created when you use the Yocto + Project in conjunction with the + <filename>poky</filename> repository to build an image. + </para></listitem> <listitem><para><emphasis>Recipe:</emphasis> A set of instructions for building packages. A recipe describes where you get source code, which patches @@ -961,10 +982,10 @@ not files. Git uses "branches" to organize different development efforts. For example, the <filename>poky</filename> repository has - <filename>denzil</filename>, <filename>danny</filename>, - <filename>dylan</filename>, <filename>dora</filename>, - <filename>daisy</filename>, and <filename>master</filename> branches - among others. + several branches that include the current + <filename>&DISTRO_NAME;</filename> branch, the + <filename>master</filename> branch, and many branches for past + Yocto Project releases. You can see all the branches by going to <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and clicking on the @@ -1028,9 +1049,10 @@ </para> <para> - Some key tags are <filename>dylan-9.0.0</filename>, - <filename>dora-10.0.0</filename>, <filename>daisy-11.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> @@ -1074,7 +1096,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> @@ -1325,8 +1349,8 @@ Following is the general procedure for submitting a new bug using the Yocto Project Bugzilla. You can find more information on defect management, bug tracking, and feature request - processes all accomplished through the Yocto Project Bugzilla on the wiki page - <ulink url='&YOCTO_WIKI_URL;/wiki/Bugzilla_Configuration_and_Bug_Tracking'>here</ulink>. + processes all accomplished through the Yocto Project Bugzilla on the + <ulink url='&YOCTO_WIKI_URL;/wiki/Bugzilla_Configuration_and_Bug_Tracking'>wiki page</ulink>. <orderedlist> <listitem><para>Always use the Yocto Project implementation of Bugzilla to submit a bug.</para></listitem> @@ -1584,7 +1608,7 @@ <para> You can find general Git information on how to push a change upstream in the - <ulink url='http://book.git-scm.com/3_distributed_workflows.html'>Git Community Book</ulink>. + <ulink url='http://git-scm.com/book/en/v2/Distributed-Git-Distributed-Workflows'>Git Community Book</ulink>. </para> </section> diff --git a/documentation/dev-manual/dev-manual-qemu.xml b/documentation/dev-manual/dev-manual-qemu.xml index 739fd7104b..4d95fbdd9f 100644 --- a/documentation/dev-manual/dev-manual-qemu.xml +++ b/documentation/dev-manual/dev-manual-qemu.xml @@ -110,7 +110,7 @@ <itemizedlist> <listitem><para><replaceable>QEMUARCH</replaceable>: The QEMU machine architecture, which must be "qemux86", - "qemux86-64", "qemuarm", "qemumips", "qemumipsel", + "qemux86_64", "qemuarm", "qemumips", "qemumipsel", “qemumips64", "qemush4", "qemuppc", "qemumicroblaze", or "qemuzynq". </para></listitem> diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml index 61434ff72c..36a3593c19 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> @@ -72,7 +72,7 @@ You should also have about 50 Gbytes of free disk space for building images. </para></listitem> <listitem><para><emphasis>Packages:</emphasis> The OpenEmbedded build system - requires that certain packages exist on your development system (e.g. Python 2.6 or 2.7). + requires that certain packages exist on your development system (e.g. Python 2.7). See "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" section in the Yocto Project Quick Start and the "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>" @@ -138,29 +138,31 @@ For simplicity, it is recommended that you create these structures outside of the Source Directory, which is usually named <filename>poky</filename>.</para> <para>As an example, the following transcript shows how to create the bare clone - of the <filename>linux-yocto-3.10</filename> kernel and then create a copy of + of the <filename>linux-yocto-3.19</filename> kernel and then create a copy of that clone. <note>When you have a local Yocto Project kernel Git repository, you can reference that repository rather than the upstream Git repository as part of the <filename>clone</filename> command. Doing so can speed up the process.</note></para> <para>In the following example, the bare clone is named - <filename>linux-yocto-3.10.git</filename>, while the - copy is named <filename>my-linux-yocto-3.10-work</filename>: + <filename>linux-yocto-3.19.git</filename>, while the + copy is named <filename>my-linux-yocto-3.19-work</filename>: <literallayout class='monospaced'> - $ git clone --bare git://git.yoctoproject.org/linux-yocto-3.10 linux-yocto-3.10.git - Cloning into bare repository 'linux-yocto-3.10.git'... - remote: Counting objects: 3364487, done. - remote: Compressing objects: 100% (507178/507178), done. - remote: Total 3364487 (delta 2827715), reused 3364481 (delta 2827709) - Receiving objects: 100% (3364487/3364487), 722.95 MiB | 423 KiB/s, done. - Resolving deltas: 100% (2827715/2827715), done. + $ git clone --bare git://git.yoctoproject.org/linux-yocto-3.19 linux-yocto-3.19.git + Cloning into bare repository 'linux-yocto-3.19.git'... + remote: Counting objects: 3983256, done. + remote: Compressing objects: 100% (605006/605006), done. + remote: Total 3983256 (delta 3352832), reused 3974503 (delta 3344079) + Receiving objects: 100% (3983256/3983256), 843.66 MiB | 1.07 MiB/s, done. + Resolving deltas: 100% (3352832/3352832), done. + Checking connectivity... done. </literallayout></para> <para>Now create a clone of the bare clone just created: <literallayout class='monospaced'> - $ git clone linux-yocto-3.10.git my-linux-yocto-3.10-work - Cloning into 'my-linux-yocto-3.10-work'... + $ git clone linux-yocto-3.19.git my-linux-yocto-3.19-work + Cloning into 'my-linux-yocto-3.19-work'... done. + Checking out files: 100% (48440/48440), done. </literallayout></para></listitem> <listitem id='meta-yocto-kernel-extras-repo'><para><emphasis> The <filename>meta-yocto-kernel-extras</filename> Git Repository</emphasis>: @@ -209,7 +211,7 @@ <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>" @@ -297,10 +299,9 @@ This file defines many aspects of the build environment including the target machine architecture through the <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'>MACHINE</ulink></filename> variable, - the development machine's processor use through the - <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</ulink></filename> and - <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'>PARALLEL_MAKE</ulink></filename> variables, and - a centralized tarball download directory through the + the packaging format used during the build + (<ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>), + and a centralized tarball download directory through the <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'>DL_DIR</ulink></filename> variable.</para></listitem> <listitem><para> Build the image using the <filename>bitbake</filename> command. diff --git a/documentation/dev-manual/dev-manual.xml b/documentation/dev-manual/dev-manual.xml index 22518d8b33..067fcb72ff 100644 --- a/documentation/dev-manual/dev-manual.xml +++ b/documentation/dev-manual/dev-manual.xml @@ -72,9 +72,9 @@ <revremark>Released with the Yocto Project 1.7 Release.</revremark> </revision> <revision> - <revnumber>1.7.1</revnumber> - <date>January 2015</date> - <revremark>Released with the Yocto Project 1.7.1 Release.</revremark> + <revnumber>1.8</revnumber> + <date>April 2015</date> + <revremark>Released with the Yocto Project 1.8 Release.</revremark> </revision> </revhistory> diff --git a/documentation/dev-manual/figures/build-workspace-directory.png b/documentation/dev-manual/figures/build-workspace-directory.png Binary files differnew file mode 100644 index 0000000000..f561f8fee6 --- /dev/null +++ b/documentation/dev-manual/figures/build-workspace-directory.png diff --git a/documentation/dev-manual/figures/kernel-overview-2-generic.png b/documentation/dev-manual/figures/kernel-overview-2-generic.png Binary files differindex 889ff1bf0d..cb970eae7c 100644 --- a/documentation/dev-manual/figures/kernel-overview-2-generic.png +++ b/documentation/dev-manual/figures/kernel-overview-2-generic.png diff --git a/documentation/kernel-dev/kernel-dev-advanced.xml b/documentation/kernel-dev/kernel-dev-advanced.xml index 283f483112..4fdb853f92 100644 --- a/documentation/kernel-dev/kernel-dev-advanced.xml +++ b/documentation/kernel-dev/kernel-dev-advanced.xml @@ -24,9 +24,9 @@ <title>Using Kernel Metadata in a Recipe</title> <para> - The kernel sources in the Yocto Project contain kernel Metadata, which is - located in the <filename>meta</filename> branches of the kernel source - Git repositories. + The kernel sources in the Yocto Project contain kernel Metadata, which + is located in the <filename>meta</filename> branches of the kernel + source Git repositories. This Metadata defines Board Support Packages (BSPs) that correspond to definitions in linux-yocto recipes for the same BSPs. A BSP consists of an aggregation of kernel policy and hardware-specific @@ -48,37 +48,44 @@ This variable is typically set to the same value as the <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> variable, which is used by - <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink> - (e.g. "edgerouter" or "fri2"). + <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>. + However, in some cases, the variable might instead refer to the + underlying platform of the <filename>MACHINE</filename>. + </para> + + <para> Multiple BSPs can reuse the same <filename>KMACHINE</filename> name if they are built using the same BSP description. - The "fri2" and "fri2-noemgd" BSP combination - in the <filename>meta-intel</filename> + The "ep108-zynqmp" and "qemuzynqmp" BSP combination + in the <filename>meta-xilinx</filename> layer is a good example of two BSPs using the same - <filename>KMACHINE</filename> value (i.e. "fri2"). + <filename>KMACHINE</filename> value (i.e. "zynqmp"). See the <link linkend='bsp-descriptions'>BSP Descriptions</link> section for more information. </para> <para> + Every linux-yocto style recipe must also indicate the Linux kernel + source repository branch used to build the Linux kernel. + The <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink> + variable must be set to indicate the branch. + <note> + You can use the <filename>KBRANCH</filename> value to define an + alternate branch typically with a machine override as shown here + from the <filename>meta-emenlow</filename> layer: + <literallayout class='monospaced'> + KBRANCH_emenlow-noemgd = "standard/base" + </literallayout> + </note> + </para> + + <para> The linux-yocto style recipes can optionally define the following variables: <literallayout class='monospaced'> - <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'>KBRANCH</ulink> <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'>KERNEL_FEATURES</ulink> - <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH_DEFAULT'>KBRANCH_DEFAULT</ulink> <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'>LINUX_KERNEL_TYPE</ulink> </literallayout> - <filename>KBRANCH_DEFAULT</filename> defines the Linux kernel source - repository's default branch to use to build the Linux kernel. - The value is used as the default for <filename>KBRANCH</filename>, which - can define an alternate branch typically with a machine override as - follows: - <literallayout class='monospaced'> - KBRANCH_fri2 = "standard/fri2" - </literallayout> - Unless you specify otherwise, <filename>KBRANCH_DEFAULT</filename> - initializes to "master". </para> <para> @@ -94,7 +101,7 @@ build out the sources and configuration. The linux-yocto recipes define "standard", "tiny", and "preempt-rt" kernel types. - See the <link linkend='kernel-types'>Kernel Types</link> section + See the "<link linkend='kernel-types'>Kernel Types</link>" section for more information on kernel types. </para> @@ -109,11 +116,11 @@ the following: <literallayout class='monospaced'> WARNING: Can't find any BSP hardware or required configuration fragments. - WARNING: Looked at meta/cfg/broken/fri2-broken/hdw_frags.txt and - meta/cfg/broken/fri2-broken/required_frags.txt in directory: - meta/cfg/broken/fri2-broken + WARNING: Looked at meta/cfg/broken/emenlow-broken/hdw_frags.txt and + meta/cfg/broken/emenlow-broken/required_frags.txt in directory: + meta/cfg/broken/emenlow-broken </literallayout> - In this example, <filename>KMACHINE</filename> was set to "fri2-broken" + In this example, <filename>KMACHINE</filename> was set to "emenlow-broken" and <filename>LINUX_KERNEL_TYPE</filename> was set to "broken". </para> @@ -131,21 +138,22 @@ to include features (configuration fragments, patches, or both) that are not already included by the <filename>KMACHINE</filename> and <filename>LINUX_KERNEL_TYPE</filename> variable combination. - For example, to include a feature specified as "features/netfilter.scc", + For example, to include a feature specified as + "features/netfilter/netfilter.scc", specify: <literallayout class='monospaced'> - KERNEL_FEATURES += "features/netfilter.scc" + KERNEL_FEATURES += "features/netfilter/netfilter.scc" </literallayout> To include a feature called "cfg/sound.scc" just for the <filename>qemux86</filename> machine, specify: <literallayout class='monospaced'> - KERNEL_FEATURES_append_qemux86 = "cfg/sound.scc" + KERNEL_FEATURES_append_qemux86 = " cfg/sound.scc" </literallayout> The value of the entries in <filename>KERNEL_FEATURES</filename> are dependent on their location within the kernel Metadata itself. - The examples here are taken from the - <filename>linux-yocto-3.4</filename> repository where "features" - and "cfg" are subdirectories within the + The examples here are taken from the <filename>meta</filename> + branch of the <filename>linux-yocto-3.19</filename> repository. + Within that branch, "features" and "cfg" are subdirectories of the <filename>meta/cfg/kernel-cache</filename> directory. For more information, see the "<link linkend='kernel-metadata-syntax'>Kernel Metadata Syntax</link>" section. @@ -440,22 +448,27 @@ feature. This feature consists of one or more Linux kernel configuration parameters in a configuration fragment file - (<filename>.cfg</filename>) and an <filename>.scc</filename> file + (<filename>.cfg</filename>) and a <filename>.scc</filename> file that describes the fragment. </para> <para> The Symmetric Multi-Processing (SMP) fragment included in the - <filename>linux-yocto-3.4</filename> Git repository + <filename>linux-yocto-3.19</filename> Git repository consists of the following two files: <literallayout class='monospaced'> cfg/smp.scc: define KFEATURE_DESCRIPTION "Enable SMP" + define KFEATURE_COMPATIBILITY all + kconf hardware smp.cfg cfg/smp.cfg: CONFIG_SMP=y CONFIG_SCHED_SMT=y + # Increase default NR_CPUS from 8 to 64 so that platform with + # more than 8 processors can be all activated at boot time + CONFIG_NR_CPUS=64 </literallayout> You can find information on configuration fragment files in the "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-config-fragments'>Creating Configuration Fragments</ulink>" @@ -582,7 +595,7 @@ </para> <para> - As an example, the <filename>linux-yocto-3.4</filename> + As an example, the <filename>linux-yocto-3.19</filename> tree defines three kernel types: "standard", "tiny", and "preempt-rt": <itemizedlist> @@ -669,15 +682,15 @@ The hardware-specific portion is typically defined independently, and then aggregated with each supported kernel type. - Consider this simple BSP description that supports the "mybsp" - machine: + Consider this simple BSP description that supports the + <replaceable>mybsp</replaceable> machine: <literallayout class='monospaced'> - mybsp.scc: - define KMACHINE mybsp + <replaceable>mybsp</replaceable>.scc: + define KMACHINE <replaceable>mybsp</replaceable> define KTYPE standard define KARCH i386 - kconf mybsp.cfg + kconf <replaceable>mybsp</replaceable>.cfg </literallayout> Every BSP description should define the <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>, @@ -722,13 +735,13 @@ a single <filename>.cfg</filename> file. Consider the following: <literallayout class='monospaced'> - mybsp.scc: + <replaceable>mybsp</replaceable>.scc: define KMACHINE mybsp define KTYPE standard define KARCH i386 include standard.scc - include mybsp-hw.scc + include <replaceable>mybsp</replaceable>-hw.scc </literallayout> </para> @@ -736,8 +749,10 @@ In the above example, <filename>standard.scc</filename> aggregates all the configuration fragments, patches, and features that make up your standard kernel policy whereas - <filename>mybsp-hw.scc</filename> aggregates all those necessary - to support the hardware available on the "mybsp" machine. + <replaceable>mybsp</replaceable><filename>-hw.scc</filename> + aggregates all those necessary + to support the hardware available on the + <replaceable>mybsp</replaceable> machine. For information on how to break a complete <filename>.config</filename> file into the various configuration fragments, see the @@ -749,99 +764,98 @@ Many real-world examples are more complex. Like any other <filename>.scc</filename> file, BSP descriptions can aggregate features. - Consider the Fish River Island 2 (fri2) - BSP definition from the <filename>linux-yocto-3.4</filename> + Consider the Minnow BSP definition from the + <filename>linux-yocto-3.19</filename> Git repository: <literallayout class='monospaced'> - fri2.scc: - kconf hardware fri2.cfg - + minnow.scc: include cfg/x86.scc include features/eg20t/eg20t.scc include cfg/dmaengine.scc - include features/ericsson-3g/f5521gw.scc include features/power/intel.scc include cfg/efi.scc include features/usb/ehci-hcd.scc include features/usb/ohci-hcd.scc - include features/iwlwifi/iwlwifi.scc + include features/usb/usb-gadgets.scc + include features/usb/touchscreen-composite.scc + include cfg/timer/hpet.scc + include cfg/timer/rtc.scc + include features/leds/leds.scc + include features/spi/spidev.scc + include features/i2c/i2cdev.scc + + # Earlyprintk and port debug requires 8250 + kconf hardware cfg/8250.cfg + + kconf hardware minnow.cfg + kconf hardware minnow-dev.cfg </literallayout> </para> <para> - The <filename>fri2.scc</filename> description file includes + The <filename>minnow.scc</filename> description file includes a hardware configuration fragment - (<filename>fri2.cfg</filename>) specific to the Fish River - Island 2 BSP as well as several more general configuration + (<filename>minnow.cfg</filename>) specific to the Minnow + BSP as well as several more general configuration fragments and features enabling hardware found on the machine. This description file is then included in each of the three - "fri2" description files for the supported kernel types + "minnow" description files for the supported kernel types (i.e. "standard", "preempt-rt", and "tiny"). - Consider the "fri2" description for the "standard" kernel + Consider the "minnow" description for the "standard" kernel type: <literallayout class='monospaced'> - fri2-standard.scc: - define KMACHINE fri2 + minnow-standard.scc: + define KMACHINE minnow define KTYPE standard define KARCH i386 - include ktypes/standard/standard.scc - branch fri2 - - git merge emgd-1.14 + include ktypes/standard - include fri2.scc + include minnow.scc - # Extra fri2 configs above the minimal defined in fri2.scc + # Extra minnow configs above the minimal defined in minnow.scc include cfg/efi-ext.scc - include features/drm-emgd/drm-emgd.scc - include cfg/vesafb.scc + include features/media/media-all.scc + include features/sound/snd_hda_intel.scc - # default policy for standard kernels + # The following should really be in standard.scc + # USB live-image support include cfg/usb-mass-storage.scc + include cfg/boot-live.scc + + # Basic profiling + include features/latencytop/latencytop.scc + include features/profiling/profiling.scc + + # Requested drivers that don't have an existing scc + kconf hardware minnow-drivers-extra.cfg </literallayout> The <filename>include</filename> command midway through the file - includes the <filename>fri2.scc</filename> description that + includes the <filename>minnow.scc</filename> description that defines all hardware enablements for the BSP that is common to all kernel types. Using this command significantly reduces duplication. </para> <para> - This "fri2" standard description introduces a few more variables - and commands that are worth further discussion. - Notice the <filename>branch fri2</filename> command, which creates - a machine-specific branch into which source changes are applied. - With this branch set up, the <filename>git merge</filename> command - uses Git to merge in a feature branch named "emgd-1.14". - You could also handle this with the <filename>patch</filename> - command. - However, for commonly used features such as this, feature branches - are a convenient mechanism. - See the "<link linkend='feature-branches'>Feature Branches</link>" - section for more information. - </para> - - <para> - Now consider the "fri2" description for the "tiny" kernel type: + Now consider the "minnow" description for the "tiny" kernel type: <literallayout class='monospaced'> - fri2-tiny.scc: - define KMACHINE fri2 + minnow-tiny.scc: + define KMACHINE minnow define KTYPE tiny define KARCH i386 - include ktypes/tiny/tiny.scc - branch fri2 + include ktypes/tiny - include fri2.scc + include minnow.scc </literallayout> As you might expect, the "tiny" description includes quite a bit less. In fact, it includes only the minimal policy defined by the "tiny" kernel type and the hardware-specific configuration required for booting the machine along with the most basic functionality of - the system as defined in the base "fri2" description file. + the system as defined in the base "minnow" description file. </para> <para> diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml index 58cc98ddff..25a41d381d 100644 --- a/documentation/kernel-dev/kernel-dev-common.xml +++ b/documentation/kernel-dev/kernel-dev-common.xml @@ -84,11 +84,11 @@ You also name it accordingly based on the linux-yocto recipe you are using. For example, if you are modifying the - <filename>meta/recipes-kernel/linux/linux-yocto_3.4.bb</filename> + <filename>meta/recipes-kernel/linux/linux-yocto_3.19.bb</filename> recipe, the append file will typically be located as follows within your custom layer: <literallayout class='monospaced'> - <replaceable>your-layer</replaceable>/recipes-kernel/linux/linux-yocto_3.4.bbappend + <replaceable>your-layer</replaceable>/recipes-kernel/linux/linux-yocto_3.19.bbappend </literallayout> The append file should initially extend the <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink> @@ -133,16 +133,16 @@ <para> For example, you can apply a three-patch series by adding the - following lines to your linux-yocto <filename>.bbappend</filename> - file in your layer: + following lines to your linux-yocto + <filename>.bbappend</filename> file in your layer: <literallayout class='monospaced'> SRC_URI += "file://0001-first-change.patch" - SRC_URI += "file://0002-first-change.patch" - SRC_URI += "file://0003-first-change.patch" + SRC_URI += "file://0002-second-change.patch" + SRC_URI += "file://0003-third-change.patch" </literallayout> - The next time you run BitBake to build the Linux kernel, BitBake - detects the change in the recipe and fetches and applies the patches - before building the kernel. + The next time you run BitBake to build the Linux kernel, + BitBake detects the change in the recipe and fetches and + applies the patches before building the kernel. </para> <para> @@ -156,23 +156,27 @@ <title>Changing the Configuration</title> <para> - You can make wholesale or incremental changes to the Linux - kernel <filename>.config</filename> file by including a - <filename>defconfig</filename> and by specifying + You can make wholesale or incremental changes to the final + <filename>.config</filename> file used for the eventual + Linux kernel configuration by including a + <filename>defconfig</filename> file and by specifying configuration fragments in the - <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>. + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + to be applied to that file. </para> <para> - If you have a final Linux kernel <filename>.config</filename> - file you want to use, copy it to a directory named - <filename>files</filename>, which must be in - your layer's <filename>recipes-kernel/linux</filename> - directory, and name the file "defconfig". - Then, add the following lines to your linux-yocto + If you have a complete, working Linux kernel + <filename>.config</filename> + file you want to use for the configuration, as before, copy + that file to the appropriate <filename>${PN}</filename> + directory in your layer's + <filename>recipes-kernel/linux</filename> directory, + and rename the copied file to "defconfig". + Then, add the following lines to the linux-yocto <filename>.bbappend</filename> file in your layer: <literallayout class='monospaced'> - FILESEXTRAPATHS_prepend := "${THISDIR}/files:" + FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" SRC_URI += "file://defconfig" </literallayout> The <filename>SRC_URI</filename> tells the build system how to @@ -181,20 +185,20 @@ extends the <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink> variable (search directories) to include the - <filename>files</filename> directory you created for the + <filename>${PN}</filename> directory you created to hold the configuration changes. </para> <note> The build system applies the configurations from the - <filename>.config</filename> file before applying any + <filename>defconfig</filename> file before applying any subsequent configuration fragments. The final kernel configuration is a combination of the - configurations in the <filename>.config</filename> file and + configurations in the <filename>defconfig</filename> file and any configuration fragments you provide. You need to realize that if you have any configuration fragments, the build system applies these on top of and - after applying the existing <filename>.config</filename> + after applying the existing <filename>defconfig</filename> file configurations. </note> @@ -204,7 +208,7 @@ configuration fragment. For example, if you want to add support for a basic serial console, create a file named <filename>8250.cfg</filename> in - the <filename>files</filename> directory with the following + the <filename>${PN}</filename> directory with the following content (without indentation): <literallayout class='monospaced'> CONFIG_SERIAL_8250=y @@ -219,7 +223,7 @@ <filename>FILESPATH</filename> variable in your <filename>.bbappend</filename> file: <literallayout class='monospaced'> - FILESEXTRAPATHS_prepend := "${THISDIR}/files:" + FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" SRC_URI += "file://8250.cfg" </literallayout> The next time you run BitBake to build the Linux kernel, BitBake @@ -322,7 +326,7 @@ The resulting <filename>.config</filename> file is located in <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename> under the - <filename>linux-${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink><filename>}-${<ulink url='&YOCTO_DOCS_REF_URL;#var-KTYPE'><filename>KTYPE</filename></ulink>}-build</filename> directory. + <filename>linux-${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink><filename>}-${<ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink>}-build</filename> directory. You can use the entire <filename>.config</filename> file as the <filename>defconfig</filename> file as described in the "<link linkend='changing-the-configuration'>Changing the Configuration</link>" section. @@ -399,7 +403,7 @@ WARNING: There were 2 hardware options requested that do not have a corresponding value present in the final ".config" file. - This probably means you are not't getting the config you wanted. + This probably means you are not getting the config you wanted. The full list can be found in your kernel src dir at: meta/cfg/standard/mybsp/mismatch.cfg </literallayout> @@ -473,9 +477,9 @@ the <filename>compile</filename>. Once compilation is successful, you can inspect and test the resulting build (i.e. kernel, modules, and so forth) from - the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>: + the following build directory: <literallayout class='monospaced'> - ${WORKDIR}/linux-${MACHINE}-${KTYPE}-build + ${WORKDIR}/linux-${PACKAGE_ARCH}-${LINUX_KERNEL_TYPE}-build </literallayout> Alternatively, you can run the <filename>deploy</filename> command to place the kernel image in the @@ -552,8 +556,9 @@ <listitem><para>Copy the <filename>linux-yocto-custom.bb</filename> recipe to your layer and give it a meaningful name. The name should include the version of the Linux kernel you - are using (e.g. <filename>linux-yocto-myproject_3.5.bb</filename>, - where "3.5" is the base version of the Linux kernel + are using (e.g. + <filename>linux-yocto-myproject_3.19.bb</filename>, + where "3.19" is the base version of the Linux kernel with which you would be working).</para></listitem> <listitem><para>In the same directory inside your layer, create a matching directory @@ -574,7 +579,7 @@ </para></listitem> <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION'><filename>LINUX_VERSION</filename></ulink>: The Linux kernel version you are using (e.g. - "3.4").</para></listitem> + "3.19").</para></listitem> <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION_EXTENSION'><filename>LINUX_VERSION_EXTENSION</filename></ulink>: The Linux kernel <filename>CONFIG_LOCALVERSION</filename> that is compiled into the resulting kernel and visible @@ -600,7 +605,7 @@ The combined results are a string with the following form: <literallayout class='monospaced'> - 3.4.11+git1+68a635bf8dfb64b02263c1ac80c948647cc76d5f_1+218bd8d2022b9852c60d32f0d770931e3cf343e2 + 3.19.11+git1+68a635bf8dfb64b02263c1ac80c948647cc76d5f_1+218bd8d2022b9852c60d32f0d770931e3cf343e2 </literallayout> While lengthy, the extra verbosity in <filename>PV</filename> helps ensure you are using the exact @@ -834,13 +839,13 @@ To see a full range of the changes, use the <filename>git whatchanged</filename> command and specify a commit range for the branch - (<filename><commit>..<commit></filename>). + (<replaceable>commit</replaceable><filename>..</filename><replaceable>commit</replaceable>). </para> <para> Here is an example that looks at what has changed in the <filename>emenlow</filename> branch of the - <filename>linux-yocto-3.4</filename> kernel. + <filename>linux-yocto-3.19</filename> kernel. The lower commit range is the commit associated with the <filename>standard/base</filename> branch, while the upper commit range is the commit associated with the @@ -891,16 +896,16 @@ <para> Tags in the Yocto Project kernel tree divide changes for significant features or branches. - The <filename>git show <tag></filename> command shows - changes based on a tag. + The <filename>git show</filename> <replaceable>tag</replaceable> + command shows changes based on a tag. Here is an example that shows <filename>systemtap</filename> changes: <literallayout class='monospaced'> $ git show systemtap </literallayout> You can use the - <filename>git branch --contains <tag></filename> command - to show the branches that contain a particular feature. + <filename>git branch --contains</filename> <replaceable>tag</replaceable> + command to show the branches that contain a particular feature. This command shows the branches that contain the <filename>systemtap</filename> feature: <literallayout class='monospaced'> 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-eclipse-customization.xsl b/documentation/kernel-dev/kernel-dev-eclipse-customization.xsl index 7d1bb8dc08..cd5bf4ac66 100644 --- a/documentation/kernel-dev/kernel-dev-eclipse-customization.xsl +++ b/documentation/kernel-dev/kernel-dev-eclipse-customization.xsl @@ -6,7 +6,7 @@ version="1.0"> <xsl:import - href="http://docbook.sourceforge.net/release/xsl/current/eclipse/eclipse3.xsl" /> + href="http://docbook.sourceforge.net/release/xsl/1.76.1/eclipse/eclipse3.xsl" /> <xsl:param name="chunker.output.indent" select="'yes'"/> <xsl:param name="chunk.quietly" select="1"/> diff --git a/documentation/kernel-dev/kernel-dev-intro.xml b/documentation/kernel-dev/kernel-dev-intro.xml index 38ef36de5a..263e50098f 100644 --- a/documentation/kernel-dev/kernel-dev-intro.xml +++ b/documentation/kernel-dev/kernel-dev-intro.xml @@ -7,7 +7,7 @@ <!-- <para> - <emphasis>AR - Darrren Hart:</emphasis> See if the concepts in these + <emphasis>AR - Darren Hart:</emphasis> See if the concepts in these three bullets are adequately covered in somewhere in this manual: <itemizedlist> <listitem><para>Do we convey that our kernel Git repositories @@ -47,11 +47,13 @@ <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink> under the "Yocto Linux Kernel" heading. New recipes for the release track the latest upstream developments - and introduce newly supported platforms. + and introduce newly-supported platforms. Previous recipes in the release are refreshed and supported for at least one additional release. As they align, these previous releases are updated to include the - latest from the Long Term Support Initiative (LTSI) project. + latest from the + <ulink url='&YOCTO_HOME_URL;/organization/long-term-support-initiative-ltsi'>Long Term Support Initiative</ulink> + (LTSI) project. Also included is a linux-yocto development recipe (<filename>linux-yocto-dev.bb</filename>) should you want to work with the very latest in upstream Linux kernel development and @@ -119,7 +121,7 @@ <itemizedlist> <listitem><para><ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink> </para></listitem> - <listitem><para>The "<ulink url='&YOCTO_DOCS_DEV_URL;#modifying-temporary-source-code'>Modifying Temporary Source Code</ulink>" + <listitem><para>The "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-modifying-source-code'>Modifying Source Code</ulink>" section in the Yocto Project Development Manual </para></listitem> <listitem><para>The "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" section diff --git a/documentation/kernel-dev/kernel-dev-maint-appx.xml b/documentation/kernel-dev/kernel-dev-maint-appx.xml index a72dcff01b..6bb0cf6fd0 100644 --- a/documentation/kernel-dev/kernel-dev-maint-appx.xml +++ b/documentation/kernel-dev/kernel-dev-maint-appx.xml @@ -30,9 +30,9 @@ in the Yocto Project kernel in any clone of the Yocto Project kernel source repository Git tree. For example, the following command clones the Yocto Project baseline kernel that - branched off of <filename>linux.org</filename> version 3.4: + branched off of <filename>linux.org</filename> version 3.19: <literallayout class='monospaced'> - $ git clone git://git.yoctoproject.org/linux-yocto-3.4 + $ git clone git://git.yoctoproject.org/linux-yocto-3.19 </literallayout> For another example of how to set up a local Git repository of the Yocto Project kernel files, see the @@ -43,9 +43,9 @@ Once you have cloned the kernel Git repository on your local machine, you can switch to the <filename>meta</filename> branch within the repository. Here is an example that assumes the local Git repository for the kernel is in - a top-level directory named <filename>linux-yocto-3.4</filename>: + a top-level directory named <filename>linux-yocto-3.19</filename>: <literallayout class='monospaced'> - $ cd linux-yocto-3.4 + $ cd linux-yocto-3.19 $ git checkout -b meta origin/meta </literallayout> Once you have checked out and switched to the <filename>meta</filename> branch, @@ -135,7 +135,7 @@ <!-- <para> - <emphasis>AR - Darrren Hart:</emphasis> Some parts of this section + <emphasis>AR - Darren Hart:</emphasis> Some parts of this section need to be in the "<link linkend='using-an-iterative-development-process'>Using an Iterative Development Process</link>" section. diff --git a/documentation/kernel-dev/kernel-dev.xml b/documentation/kernel-dev/kernel-dev.xml index 12ecf78b7c..3d40045c00 100644 --- a/documentation/kernel-dev/kernel-dev.xml +++ b/documentation/kernel-dev/kernel-dev.xml @@ -57,9 +57,9 @@ <revremark>Released with the Yocto Project 1.7 Release.</revremark> </revision> <revision> - <revnumber>1.7.1</revnumber> - <date>January 2015</date> - <revremark>Released with the Yocto Project 1.7.1 Release.</revremark> + <revnumber>1.8</revnumber> + <date>April 2015</date> + <revremark>Released with the Yocto Project 1.8 Release.</revremark> </revision> </revhistory> diff --git a/documentation/mega-manual/figures/build-workspace-directory.png b/documentation/mega-manual/figures/build-workspace-directory.png Binary files differnew file mode 100644 index 0000000000..f561f8fee6 --- /dev/null +++ b/documentation/mega-manual/figures/build-workspace-directory.png diff --git a/documentation/mega-manual/figures/buildhistory.png b/documentation/mega-manual/figures/buildhistory.png Binary files differindex 9a77bde68b..bd5f8a4908 100644 --- a/documentation/mega-manual/figures/buildhistory.png +++ b/documentation/mega-manual/figures/buildhistory.png diff --git a/documentation/mega-manual/figures/define-generic.png b/documentation/mega-manual/figures/define-generic.png Binary files differnew file mode 100644 index 0000000000..bd22718a55 --- /dev/null +++ b/documentation/mega-manual/figures/define-generic.png diff --git a/documentation/mega-manual/figures/hosted-service.png b/documentation/mega-manual/figures/hosted-service.png Binary files differnew file mode 100644 index 0000000000..01fea7b245 --- /dev/null +++ b/documentation/mega-manual/figures/hosted-service.png diff --git a/documentation/mega-manual/figures/kernel-overview-2-generic.png b/documentation/mega-manual/figures/kernel-overview-2-generic.png Binary files differindex 889ff1bf0d..cb970eae7c 100644 --- a/documentation/mega-manual/figures/kernel-overview-2-generic.png +++ b/documentation/mega-manual/figures/kernel-overview-2-generic.png diff --git a/documentation/mega-manual/figures/mega-title.png b/documentation/mega-manual/figures/mega-title.png Binary files differnew file mode 100644 index 0000000000..cde0b89a44 --- /dev/null +++ b/documentation/mega-manual/figures/mega-title.png diff --git a/documentation/mega-manual/figures/package-feeds.png b/documentation/mega-manual/figures/package-feeds.png Binary files differindex 4bc311f3d6..37c9c32506 100644 --- a/documentation/mega-manual/figures/package-feeds.png +++ b/documentation/mega-manual/figures/package-feeds.png diff --git a/documentation/mega-manual/figures/simple-configuration.png b/documentation/mega-manual/figures/simple-configuration.png Binary files differnew file mode 100644 index 0000000000..e8fce2bf18 --- /dev/null +++ b/documentation/mega-manual/figures/simple-configuration.png diff --git a/documentation/mega-manual/figures/toaster-title.png b/documentation/mega-manual/figures/toaster-title.png Binary files differnew file mode 100644 index 0000000000..b7ea39cd8d --- /dev/null +++ b/documentation/mega-manual/figures/toaster-title.png diff --git a/documentation/mega-manual/mega-manual-customization.xsl b/documentation/mega-manual/mega-manual-customization.xsl index eb95240e64..1f7f9c1c7b 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 @@ -24,7 +24,7 @@ <xsl:include href="../template/formal.object.heading.xsl"/> <xsl:include href="../template/gloss-permalinks.xsl"/> - <xsl:param name="html.stylesheet" select="'ref-style.css'" /> + <xsl:param name="html.stylesheet" select="'mega-style.css'" /> <xsl:param name="chapter.autolabel" select="1" /> <xsl:param name="appendix.autolabel">A</xsl:param> <xsl:param name="section.autolabel" select="1" /> diff --git a/documentation/mega-manual/mega-manual.xml b/documentation/mega-manual/mega-manual.xml index 01af789aed..9bec799d7a 100644 --- a/documentation/mega-manual/mega-manual.xml +++ b/documentation/mega-manual/mega-manual.xml @@ -8,43 +8,216 @@ xmlns="http://docbook.org/ns/docbook" > + <bookinfo> + + <abstract> + The Yocto Project Mega-Manual is a concatenation of the published + Yocto Project HTML manuals for the given release. + The manual exists to help users efficiently search for strings + across the entire Yocto Project documentation set. + </abstract> + + <mediaobject> + <imageobject> + <imagedata fileref='figures/mega-title.png' + format='SVG' + align='left' scalefit='1' width='100%'/> + </imageobject> + </mediaobject> + + <title> + Yocto Project Mega-Manual + </title> + + <authorgroup> + <author> + <firstname>Scott</firstname> <surname>Rifenbark</surname> + <affiliation> + <orgname>Intel Corporation</orgname> + </affiliation> + <email>scott.m.rifenbark@intel.com</email> + </author> + </authorgroup> + + <revhistory> + <revision> + <revnumber>1.8</revnumber> + <date>April 2015</date> + <revremark>Released with the Yocto Project 1.8 Release.</revremark> + </revision> + </revhistory> + + <copyright> + <year>©RIGHT_YEAR;</year> + <holder>Linux Foundation</holder> + </copyright> + + <legalnotice> + <para> + Permission is granted to copy, distribute and/or modify this document under + the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England & Wales</ulink> as published by Creative Commons. + </para> + <note> + For the latest version of this manual associated with this + Yocto Project release, see the + <ulink url='&YOCTO_DOCS_MM_URL;'>Yocto Project Mega-Manual</ulink> + from the Yocto Project website. + </note> + + </legalnotice> + + </bookinfo> + +<!-- Includes yocto-project-qs --> + <xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../yocto-project-qs/yocto-project-qs.xml"/> -<para><imagedata fileref="figures/dev-title.png" width="100%" align="left" scalefit="1" /></para> +<!-- Includes dev-manual title image and then dev-manual chapters --> + + <para> + <imagedata fileref="figures/dev-title.png" width="100%" align="left" scalefit="1" /> + </para> <xi:include - xmlns:xi="http://www.w3.org/2003/XInclude" href="../dev-manual/dev-manual.xml"/> + xmlns:xi="http://www.w3.org/2003/XInclude" href="../dev-manual/dev-manual-intro.xml"/> + <xi:include + xmlns:xi="http://www.w3.org/2003/XInclude" href="../dev-manual/dev-manual-start.xml"/> + <xi:include + xmlns:xi="http://www.w3.org/2003/XInclude" href="../dev-manual/dev-manual-newbie.xml"/> + <xi:include + xmlns:xi="http://www.w3.org/2003/XInclude" href="../dev-manual/dev-manual-model.xml"/> + <xi:include + xmlns:xi="http://www.w3.org/2003/XInclude" href="../dev-manual/dev-manual-common-tasks.xml"/> + <xi:include + xmlns:xi="http://www.w3.org/2003/XInclude" href="../dev-manual/dev-manual-qemu.xml"/> + +<!-- Includes adt-manual title image and then adt-manual chapters --> -<para><imagedata fileref="figures/adt-title.png" width="100%" align="left" scalefit="1" /></para> + <para> + <imagedata fileref="figures/adt-title.png" width="100%" align="left" scalefit="1" /> + </para> <xi:include - xmlns:xi="http://www.w3.org/2003/XInclude" href="../adt-manual/adt-manual.xml"/> + xmlns:xi="http://www.w3.org/2003/XInclude" href="../adt-manual/adt-manual-intro.xml"/> + <xi:include + xmlns:xi="http://www.w3.org/2003/XInclude" href="../adt-manual/adt-intro.xml"/> + <xi:include + xmlns:xi="http://www.w3.org/2003/XInclude" href="../adt-manual/adt-prepare.xml"/> + <xi:include + xmlns:xi="http://www.w3.org/2003/XInclude" href="../adt-manual/adt-package.xml"/> + <xi:include + xmlns:xi="http://www.w3.org/2003/XInclude" href="../adt-manual/adt-command.xml"/> -<para><imagedata fileref="figures/bsp-title.png" width="100%" align="left" scalefit="1" /></para> +<!-- Includes bsp-guide title image and then bsp-guide chapters --> + + <para> + <imagedata fileref="figures/bsp-title.png" width="100%" align="left" scalefit="1" /> + </para> <xi:include - xmlns:xi="http://www.w3.org/2003/XInclude" href="../bsp-guide/bsp-guide.xml"/> + xmlns:xi="http://www.w3.org/2003/XInclude" href="../bsp-guide/bsp.xml"/> + +<!-- Includes kernel-dev title image and then kernel-dev chapters --> -<para><imagedata fileref="figures/kernel-dev-title.png" width="100%" align="left" scalefit="1" /></para> + <para> + <imagedata fileref="figures/kernel-dev-title.png" width="100%" align="left" scalefit="1" /> + </para> <xi:include - xmlns:xi="http://www.w3.org/2003/XInclude" href="../kernel-dev/kernel-dev.xml"/> + xmlns:xi="http://www.w3.org/2003/XInclude" href="../kernel-dev/kernel-dev-intro.xml"/> + <xi:include + xmlns:xi="http://www.w3.org/2003/XInclude" href="../kernel-dev/kernel-dev-common.xml"/> + <xi:include + xmlns:xi="http://www.w3.org/2003/XInclude" href="../kernel-dev/kernel-dev-advanced.xml"/> + <xi:include + xmlns:xi="http://www.w3.org/2003/XInclude" href="../kernel-dev/kernel-dev-concepts-appx.xml"/> + <xi:include + xmlns:xi="http://www.w3.org/2003/XInclude" href="../kernel-dev/kernel-dev-maint-appx.xml"/> -<para><imagedata fileref="figures/profile-title.png" width="100%" align="left" scalefit="1" /></para> +<!-- Includes profile-manual title image and then profile-manual chapters --> + <para> + <imagedata fileref="figures/profile-title.png" width="100%" align="left" scalefit="1" /> + </para> + + <xi:include + xmlns:xi="http://www.w3.org/2003/XInclude" href="../profile-manual/profile-manual-intro.xml"/> <xi:include - xmlns:xi="http://www.w3.org/2003/XInclude" href="../profile-manual/profile-manual.xml"/> + xmlns:xi="http://www.w3.org/2003/XInclude" href="../profile-manual/profile-manual-arch.xml"/> + <xi:include + xmlns:xi="http://www.w3.org/2003/XInclude" href="../profile-manual/profile-manual-usage.xml"/> + <xi:include + xmlns:xi="http://www.w3.org/2003/XInclude" href="../profile-manual/profile-manual-examples.xml"/> -<para><imagedata fileref="figures/poky-title.png" width="100%" align="left" scalefit="1" /></para> +<!-- Includes ref-manual title image and then ref-manual chapters --> + + <para> + <imagedata fileref="figures/poky-title.png" width="100%" align="left" scalefit="1" /> + </para> <xi:include - xmlns:xi="http://www.w3.org/2003/XInclude" href="../ref-manual/ref-manual.xml"/> + xmlns:xi="http://www.w3.org/2003/XInclude" href="../ref-manual/introduction.xml"/> -<!-- <index id='index'> - <title>Index</title> - </index> ---> + <xi:include + xmlns:xi="http://www.w3.org/2003/XInclude" href="../ref-manual/usingpoky.xml"/> + + <xi:include + xmlns:xi="http://www.w3.org/2003/XInclude" href="../ref-manual/closer-look.xml"/> + + <xi:include + xmlns:xi="http://www.w3.org/2003/XInclude" href="../ref-manual/technical-details.xml"/> + + <xi:include + xmlns:xi="http://www.w3.org/2003/XInclude" href="../ref-manual/migration.xml"/> + + <xi:include + xmlns:xi="http://www.w3.org/2003/XInclude" href="../ref-manual/ref-structure.xml"/> + + <xi:include + xmlns:xi="http://www.w3.org/2003/XInclude" href="../ref-manual/ref-classes.xml"/> + + <xi:include + xmlns:xi="http://www.w3.org/2003/XInclude" href="../ref-manual/ref-tasks.xml"/> + + <xi:include + xmlns:xi="http://www.w3.org/2003/XInclude" href="../ref-manual/ref-qa-checks.xml"/> + + <xi:include + xmlns:xi="http://www.w3.org/2003/XInclude" href="../ref-manual/ref-images.xml"/> + + <xi:include + xmlns:xi="http://www.w3.org/2003/XInclude" href="../ref-manual/ref-features.xml"/> + + <xi:include + xmlns:xi="http://www.w3.org/2003/XInclude" href="../ref-manual/ref-variables.xml"/> + + <xi:include + xmlns:xi="http://www.w3.org/2003/XInclude" href="../ref-manual/ref-varlocality.xml"/> + + <xi:include + xmlns:xi="http://www.w3.org/2003/XInclude" href="../ref-manual/faq.xml"/> + + <xi:include + xmlns:xi="http://www.w3.org/2003/XInclude" href="../ref-manual/resources.xml"/> + +<!-- Includes toaster-manual title image and then toaster-manual chapters --> + + <para> + <imagedata fileref="figures/toaster-title.png" width="100%" align="left" scalefit="1" /> + </para> + + <xi:include + xmlns:xi="http://www.w3.org/2003/XInclude" href="../toaster-manual/toaster-manual-intro.xml"/> + + <xi:include + xmlns:xi="http://www.w3.org/2003/XInclude" href="../toaster-manual/toaster-manual-start.xml"/> + + <xi:include + xmlns:xi="http://www.w3.org/2003/XInclude" href="../toaster-manual/toaster-manual-setup-and-use.xml"/> + + <xi:include + xmlns:xi="http://www.w3.org/2003/XInclude" href="../toaster-manual/toaster-manual-reference.xml"/> </book> diff --git a/documentation/mega-manual/mega-style.css b/documentation/mega-manual/mega-style.css index 45b77ac958..df71a20a02 100644 --- a/documentation/mega-manual/mega-style.css +++ b/documentation/mega-manual/mega-style.css @@ -118,12 +118,13 @@ h6 { background-color: transparent; background-repeat: no-repeat; padding-top: 256px; - background-position: top; + background-image: url("figures/mega-title.png"); + background-position: left top; margin-top: -256px; padding-right: 50px; - margin-left: 50px; - text-align: center; - width: 600px; + margin-left: 0px; + text-align: right; + width: 740px; } h3.author { diff --git a/documentation/poky.ent b/documentation/poky.ent index 3381a1ede2..9850c03bb0 100644 --- a/documentation/poky.ent +++ b/documentation/poky.ent @@ -1,9 +1,9 @@ -<!ENTITY DISTRO "1.7.1"> -<!ENTITY DISTRO_COMPRESSED "171"> -<!ENTITY DISTRO_NAME "dizzy"> -<!ENTITY YOCTO_DOC_VERSION "1.7.1"> -<!ENTITY POKYVERSION "12.0.1"> -<!ENTITY POKYVERSION_COMPRESSED "1201"> +<!ENTITY DISTRO "1.8"> +<!ENTITY DISTRO_COMPRESSED "18"> +<!ENTITY DISTRO_NAME "fido"> +<!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-2015"> <!ENTITY YOCTO_DL_URL "http://downloads.yoctoproject.org"> @@ -14,7 +14,7 @@ <!ENTITY YOCTO_AB_URL "http://autobuilder.yoctoproject.org"> <!ENTITY YOCTO_GIT_URL "http://git.yoctoproject.org"> <!ENTITY YOCTO_ADTREPO_URL "http://adtrepo.yoctoproject.org"> -<!ENTITY YOCTO_RELEASE_NOTES "&YOCTO_HOME_URL;/downloads/core/&DISTRO_NAME;&DISTRO_COMPRESSED;"> +<!ENTITY YOCTO_RELEASE_NOTES "&YOCTO_HOME_URL;/download/yocto-project-&DISTRO_COMPRESSED;-poky-&POKYVERSION_COMPRESSED;"> <!ENTITY OE_HOME_URL "http://www.openembedded.org"> <!ENTITY OE_LISTS_URL "http://lists.openembedded.org/mailman"> <!ENTITY OE_DOCS_URL "http://docs.openembedded.org"> @@ -26,16 +26,17 @@ <!ENTITY ECLIPSE_UPDATES_URL "&ECLIPSE_DL_URL;/tm/updates/3.3"> <!ENTITY ECLIPSE_INDIGO_URL "&ECLIPSE_DL_URL;/releases/indigo"> <!ENTITY ECLIPSE_JUNO_URL "&ECLIPSE_DL_URL;/releases/juno"> +<!ENTITY ECLIPSE_LUNA_URL "&ECLIPSE_DL_URL;/releases/luna"> <!ENTITY ECLIPSE_KEPLER_URL "&ECLIPSE_DL_URL;/releases/kepler"> -<!ENTITY ECLIPSE_INDIGO_CDT_URL "&ECLIPSE_DL_URL;tools/cdt/releases/indigo"> +<!ENTITY ECLIPSE_INDIGO_CDT_URL "&ECLIPSE_DL_URL;/tools/cdt/releases/indigo"> <!ENTITY YOCTO_DOCS_URL "&YOCTO_HOME_URL;/docs"> <!ENTITY YOCTO_SOURCES_URL "&YOCTO_HOME_URL;/sources/"> <!ENTITY YOCTO_AB_PORT_URL "&YOCTO_AB_URL;:8010"> -<!ENTITY YOCTO_AB_NIGHTLY_URL "&YOCTO_AB_URL;/nightly/"> +<!ENTITY YOCTO_AB_NIGHTLY_URL "&YOCTO_AB_URL;/pub/nightly/"> <!ENTITY YOCTO_POKY_URL "&YOCTO_DL_URL;/releases/poky/"> <!ENTITY YOCTO_RELEASE_DL_URL "&YOCTO_DL_URL;/releases/yocto/yocto-&DISTRO;"> <!ENTITY YOCTO_TOOLCHAIN_DL_URL "&YOCTO_RELEASE_DL_URL;/toolchain/"> -<!ENTITY YOCTO_ECLIPSE_DL_URL "&YOCTO_RELEASE_DL_URL;/eclipse-plugin/indigo;"> +<!ENTITY YOCTO_ECLIPSE_DL_URL "&YOCTO_RELEASE_DL_URL;/eclipse-plugin/"> <!ENTITY YOCTO_ADTINSTALLER_DL_URL "&YOCTO_RELEASE_DL_URL;/adt-installer"> <!ENTITY YOCTO_POKY_DL_URL "&YOCTO_RELEASE_DL_URL;/&YOCTO_POKY;.tar.bz2"> <!ENTITY YOCTO_MACHINES_DL_URL "&YOCTO_RELEASE_DL_URL;/machines"> @@ -50,7 +51,9 @@ <!ENTITY YOCTO_DOCS_KERNEL_URL "&YOCTO_DOCS_URL;/&YOCTO_DOC_VERSION;/kernel-manual/kernel-manual.html"> <!ENTITY YOCTO_DOCS_KERNEL_DEV_URL "&YOCTO_DOCS_URL;/&YOCTO_DOC_VERSION;/kernel-dev/kernel-dev.html"> <!ENTITY YOCTO_DOCS_PROF_URL "&YOCTO_DOCS_URL;/&YOCTO_DOC_VERSION;/profile-manual/profile-manual.html"> +<!ENTITY YOCTO_DOCS_MM_URL "&YOCTO_DOCS_URL;/&YOCTO_DOC_VERSION;/mega-manual/mega-manual.html"> <!ENTITY YOCTO_DOCS_BB_URL "&YOCTO_DOCS_URL;/&YOCTO_DOC_VERSION;/bitbake-user-manual/bitbake-user-manual.html"> +<!ENTITY YOCTO_DOCS_TOAST_URL "&YOCTO_DOCS_URL;/&YOCTO_DOC_VERSION;/toaster-manual/toaster-manual.html"> <!ENTITY YOCTO_ADTPATH_DIR "/opt/poky/&DISTRO;"> <!ENTITY YOCTO_POKY_TARBALL "&YOCTO_POKY;.tar.bz2"> <!ENTITY OE_INIT_PATH "&YOCTO_POKY;/oe-init-build-env"> @@ -61,6 +64,6 @@ diffutils diffstat git cpp gcc gcc-c++ glibc-devel texinfo chrpath \ 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 socat"> + diffstat makeinfo 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 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-eclipse-customization.xsl b/documentation/profile-manual/profile-manual-eclipse-customization.xsl index e4ff6e99ab..4917e7c0c0 100644 --- a/documentation/profile-manual/profile-manual-eclipse-customization.xsl +++ b/documentation/profile-manual/profile-manual-eclipse-customization.xsl @@ -6,7 +6,7 @@ version="1.0"> <xsl:import - href="http://docbook.sourceforge.net/release/xsl/current/eclipse/eclipse3.xsl" /> + href="http://docbook.sourceforge.net/release/xsl/1.76.1/eclipse/eclipse3.xsl" /> <xsl:param name="chunker.output.indent" select="'yes'"/> <xsl:param name="chunk.quietly" select="1"/> diff --git a/documentation/profile-manual/profile-manual-intro.xml b/documentation/profile-manual/profile-manual-intro.xml index 0d3f5a6099..cc47f5267b 100644 --- a/documentation/profile-manual/profile-manual-intro.xml +++ b/documentation/profile-manual/profile-manual-intro.xml @@ -5,7 +5,7 @@ <chapter id='profile-manual-intro'> <title>Yocto Project Profiling and Tracing Manual</title> - <section id='intro'> + <section id='profile-intro'> <title>Introduction</title> <para> diff --git a/documentation/profile-manual/profile-manual.xml b/documentation/profile-manual/profile-manual.xml index da2315f6e2..ed86987ecc 100644 --- a/documentation/profile-manual/profile-manual.xml +++ b/documentation/profile-manual/profile-manual.xml @@ -57,9 +57,9 @@ <revremark>Released with the Yocto Project 1.7 Release.</revremark> </revision> <revision> - <revnumber>1.7.1</revnumber> - <date>January 2015</date> - <revremark>Released with the Yocto Project 1.7.1 Release.</revremark> + <revnumber>1.8</revnumber> + <date>April 2015</date> + <revremark>Released with the Yocto Project 1.8 Release.</revremark> </revision> </revhistory> diff --git a/documentation/ref-manual/closer-look.xml b/documentation/ref-manual/closer-look.xml index c0c0d619a4..27f674ae2f 100644 --- a/documentation/ref-manual/closer-look.xml +++ b/documentation/ref-manual/closer-look.xml @@ -162,9 +162,10 @@ <itemizedlist> <listitem><para><emphasis>Parallelism Options:</emphasis> Controlled by the - <link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link> + <link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link>, + <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>, and - <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link> + <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_NUMBER_PARSE_THREADS'><filename>BB_NUMBER_PARSE_THREADS</filename></ulink> variables.</para></listitem> <listitem><para><emphasis>Target Machine Selection:</emphasis> Controlled by the @@ -216,12 +217,10 @@ For example, suppose you had several build environments and they shared some common features. You can set these default build properties here. - A good example is perhaps the level of parallelism you want - to use through the - <link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link> - and - <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link> - variables.</para> + A good example is perhaps the packaging format to use + through the + <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link> + variable.</para> <para>One useful scenario for using the <filename>conf/site.conf</filename> file is to extend your <link linkend='var-BBPATH'><filename>BBPATH</filename></link> @@ -641,7 +640,9 @@ <para> Package feeds are an intermediary step in the build process. - BitBake generates packages whose types are defined by the + The OpenEmbedded build system provides classes to generate + different package types, and you specify which classes to enable + through the <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link> variable. Before placing the packages into package feeds, @@ -652,22 +653,41 @@ </para> <para> - The package feed area resides in - <filename>tmp/deploy</filename> of the Build Directory. - Folders are created that correspond to the package type - (IPK, DEB, or RPM) created. - Further organization is derived through the value of the - <link linkend='var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></link> - variable for each package. - For example, packages can exist for the i586 or qemux86 - architectures. - The package files themselves reside within the appropriate - architecture folder. + The package feed area resides in the Build Directory. + The directory the build system uses to temporarily store packages + is determined by a combination of variables and the particular + package manager in use. + See the "Package Feeds" box in the illustration and note the + information to the right of that area. + In particular, the following defines where package files are + kept: + <itemizedlist> + <listitem><para><link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>: + Defined as <filename>tmp/deploy</filename> in the Build + Directory. + </para></listitem> + <listitem><para><filename>DEPLOY_DIR_*</filename>: + Depending on the package manager used, the package type + sub-folder. + Given RPM, IPK, or DEB packaging and tarball creation, the + <link linkend='var-DEPLOY_DIR_RPM'><filename>DEPLOY_DIR_RPM</filename></link>, + <link linkend='var-DEPLOY_DIR_IPK'><filename>DEPLOY_DIR_IPK</filename></link>, + <link linkend='var-DEPLOY_DIR_DEB'><filename>DEPLOY_DIR_DEB</filename></link>, + or + <link linkend='var-DEPLOY_DIR_TAR'><filename>DEPLOY_DIR_TAR</filename></link>, + variables are used, respectively. + </para></listitem> + <listitem><para><link linkend='var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></link>: + Defines architecture-specific sub-folders. + For example, packages could exist for the i586 or qemux86 + architectures. + </para></listitem> + </itemizedlist> </para> <para> BitBake uses the <filename>do_package_write_*</filename> tasks to - place generated packages into the package holding area (e.g. + generate packages and place them into the package holding area (e.g. <filename>do_package_write_ipk</filename> for IPK packages). See the "<link linkend='ref-tasks-package_write_deb'><filename>do_package_write_deb</filename></link>", @@ -676,6 +696,13 @@ and "<link linkend='ref-tasks-package_write_tar'><filename>do_package_write_tar</filename></link>" sections for additional information. + As an example, consider a scenario where an IPK packaging manager + is being used and package architecture support for both i586 + and qemux86 exist. + Packages for the i586 architecture are placed in + <filename>build/tmp/deploy/ipk/i586</filename>, while packages for + the qemux86 architecture are placed in + <filename>build/tmp/deploy/ipk/qemux86</filename>. </para> </section> diff --git a/documentation/ref-manual/faq.xml b/documentation/ref-manual/faq.xml index da6ce20eef..197d490745 100644 --- a/documentation/ref-manual/faq.xml +++ b/documentation/ref-manual/faq.xml @@ -173,23 +173,6 @@ <qandaentry> <question> <para> - What is GNOME Mobile and what is the difference between GNOME Mobile and GNOME? - </para> - </question> - <answer> - <para> - GNOME Mobile is a subset of the <ulink url='http://www.gnome.org'>GNOME</ulink> - platform targeted at mobile and embedded devices. - The main difference between GNOME Mobile and standard GNOME is that - desktop-orientated libraries have been removed, along with deprecated libraries, - creating a much smaller footprint. - </para> - </answer> - </qandaentry> - - <qandaentry> - <question> - <para> I see the error '<filename>chmod: XXXXX new permissions are r-xrwxrwx, not r-xr-xr-x</filename>'. What is wrong? </para> @@ -364,6 +347,41 @@ <qandaentry> <question> <para> + When I try to build a native recipe, the build fails with <filename>iconv.h</filename> problems. + </para> + </question> + <answer> + <para> + If you get an error message that indicates GNU + <filename>libiconv</filename> is not in use but + <filename>iconv.h</filename> has been included from + <filename>libiconv</filename>, you need to check to see if + you have a previously installed version of the header file + in <filename>/usr/local/include</filename>. + <literallayout class='monospaced'> + #error GNU libiconv not in use but included iconv.h is from libiconv + </literallayout> + If you find a previously installed file, you should either + uninstall it or temporarily rename it and try the build again. + </para> + + <para> + This issue is just a single manifestation of "system + leakage" issues caused when the OpenEbedded build system + finds and uses previously installed files during a native + build. + This type of issue might not be limited to + <filename>iconv.h</filename>. + Be sure that leakage cannot occur from + <filename>/usr/local/include</filename> and + <filename>/opt</filename> locations. + </para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para> What do we need to ship for license compliance? </para> </question> diff --git a/documentation/ref-manual/figures/buildhistory.png b/documentation/ref-manual/figures/buildhistory.png Binary files differindex 9a77bde68b..bd5f8a4908 100644 --- a/documentation/ref-manual/figures/buildhistory.png +++ b/documentation/ref-manual/figures/buildhistory.png diff --git a/documentation/ref-manual/figures/define-generic.png b/documentation/ref-manual/figures/define-generic.png Binary files differnew file mode 100644 index 0000000000..bd22718a55 --- /dev/null +++ b/documentation/ref-manual/figures/define-generic.png diff --git a/documentation/ref-manual/figures/package-feeds.png b/documentation/ref-manual/figures/package-feeds.png Binary files differindex 4bc311f3d6..37c9c32506 100644 --- a/documentation/ref-manual/figures/package-feeds.png +++ b/documentation/ref-manual/figures/package-feeds.png diff --git a/documentation/ref-manual/introduction.xml b/documentation/ref-manual/introduction.xml index f986f7c28e..cc3f6b075c 100644 --- a/documentation/ref-manual/introduction.xml +++ b/documentation/ref-manual/introduction.xml @@ -2,7 +2,7 @@ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > -<chapter id='intro'> +<chapter id='ref-manual-intro'> <title>Introduction</title> <section id='intro-welcome'> @@ -23,7 +23,7 @@ For Board Support Package (BSP) structure information, see the <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>. You can find information on tracing and profiling in the - <ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual'>Yocto Project Profiling and Tracing Manual</ulink>. + <ulink url='&YOCTO_DOCS_PROF_URL;'>Yocto Project Profiling and Tracing Manual</ulink>. For information on BitBake, which is the task execution tool the OpenEmbedded build system is based on, see the <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual'>BitBake User Manual</ulink>. @@ -147,34 +147,39 @@ </para> </note> <itemizedlist> -<!-- <listitem><para>Ubuntu 10.04</para></listitem> - <listitem><para>Ubuntu 11.10</para></listitem> --> +<!-- + <listitem><para>Ubuntu 10.04</para></listitem> + <listitem><para>Ubuntu 11.10</para></listitem> <listitem><para>Ubuntu 12.04 (LTS)</para></listitem> - <listitem><para>Ubuntu 13.10</para></listitem> + <listitem><para>Ubuntu 13.10</para></listitem> --> <listitem><para>Ubuntu 14.04 (LTS)</para></listitem> + <listitem><para>Ubuntu 14.10</para></listitem> <!-- <listitem><para>Fedora 16 (Verne)</para></listitem> - <listitem><para>Fedora 17 (Spherical)</para></listitem> --> + <listitem><para>Fedora 17 (Spherical)</para></listitem> <listitem><para>Fedora release 19 (Schrödinger's Cat)</para></listitem> - <listitem><para>Fedora release 20 (Heisenbug)</para></listitem> + <listitem><para>Fedora release 20 (Heisenbug)</para></listitem> --> + <listitem><para>Fedora release 21</para></listitem> <!-- <listitem><para>CentOS release 5.6 (Final)</para></listitem> <listitem><para>CentOS release 5.7 (Final)</para></listitem> <listitem><para>CentOS release 5.8 (Final)</para></listitem> <listitem><para>CentOS release 6.3 (Final)</para></listitem> --> - <listitem><para>CentOS release 6.4</para></listitem> - <listitem><para>CentOS release 6.5</para></listitem> + <listitem><para>CentOS release 6.x</para></listitem> + <listitem><para>CentOS release 7.x</para></listitem> <!-- <listitem><para>Debian GNU/Linux 6.0 (Squeeze)</para></listitem> --> - <listitem><para>Debian GNU/Linux 7.0 (Wheezy)</para></listitem> - <listitem><para>Debian GNU/Linux 7.1 (Wheezy)</para></listitem> + <listitem><para>Debian GNU/Linux 7.x (Wheezy)</para></listitem> + <listitem><para>Debian GNU/Linux 8.x (Jessie)</para></listitem> +<!-- <listitem><para>Debian GNU/Linux 7.1 (Wheezy)</para></listitem> <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>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.1</para></listitem> <listitem><para>openSUSE 12.2</para></listitem> <listitem><para>openSUSE 12.3</para></listitem> - <listitem><para>openSUSE 13.1</para></listitem> + <listitem><para>openSUSE 13.1</para></listitem> --> + <listitem><para>openSUSE 13.2</para></listitem> </itemizedlist> </para> @@ -262,7 +267,7 @@ Yocto Project documentation manuals: <literallayout class='monospaced'> $ sudo yum install make docbook-style-dsssl docbook-style-xsl \ - docbook-dtds docbook-utils fop libxslt dblatex xmlto + docbook-dtds docbook-utils fop libxslt dblatex xmlto xsltproc </literallayout></para></listitem> <listitem><para><emphasis>ADT Installer Extras:</emphasis> Packages needed if you are going to be using the @@ -347,7 +352,7 @@ Yocto Project documentation manuals: <literallayout class='monospaced'> $ sudo yum install make docbook-style-dsssl docbook-style-xsl \ - docbook-dtds docbook-utils fop libxslt dblatex xmlto + docbook-dtds docbook-utils fop libxslt dblatex xmlto xsltproc </literallayout></para></listitem> <listitem><para><emphasis>ADT Installer Extras:</emphasis> Packages needed if you are going to be using the @@ -398,7 +403,7 @@ Execute the installation script. Here is an example: <literallayout class='monospaced'> - $ sh poky-eglibc-x86_64-buildtools-tarball-x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh + $ sh poky-glibc-x86_64-buildtools-tarball-x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh </literallayout> During execution, a prompt appears that allows you to choose the installation directory. @@ -411,7 +416,7 @@ Source the tools environment setup script by using a command like the following: <literallayout class='monospaced'> - $ source /home/<replaceable>your-username</replaceable>/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). @@ -484,20 +489,20 @@ to install the tools. Here is an example: <literallayout class='monospaced'> - $ sh poky-eglibc-x86_64-buildtools-tarball-x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh + $ sh poky-glibc-x86_64-buildtools-tarball-x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh </literallayout> During execution, a prompt appears that allows you to choose the installation directory. For example, you could choose the following: <literallayout class='monospaced'> - /home/<replaceable>your-username</replaceable>/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/<replaceable>your-username</replaceable>/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). @@ -538,7 +543,7 @@ <ulink url='&YOCTO_DL_URL;/releases/yocto/'/>.</para></listitem> <listitem><para><emphasis>Nightly Builds:</emphasis> These tarball releases are available at - <ulink url='http://autobuilder.yoctoproject.org/nightly'/>. + <ulink url='&YOCTO_AB_NIGHTLY_URL;'/>. These builds include Yocto Project releases, meta-toolchain tarball installation scripts, and experimental builds. </para></listitem> diff --git a/documentation/ref-manual/migration.xml b/documentation/ref-manual/migration.xml index d072ecfa0e..7c78c9dd50 100644 --- a/documentation/ref-manual/migration.xml +++ b/documentation/ref-manual/migration.xml @@ -1014,7 +1014,7 @@ The <filename>buildhistory-diff</filename> and <filename>buildhistory-collect-srcrevs</filename> utilities have improved command-line handling. - Use the <filename>‐‐help</filename> option for + Use the <filename>--help</filename> option for each utility for more information on the new syntax. </para></listitem> </itemizedlist> @@ -1730,7 +1730,7 @@ 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 + <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 @@ -1770,7 +1770,7 @@ class instead of the <filename>autotools</filename> class. </para></listitem> <listitem><para><emphasis> - The <filename>‐‐foreign</filename> option is + 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 @@ -2013,6 +2013,279 @@ </section> </section> +<section id='moving-to-the-yocto-project-1.8-release'> + <title>Moving to the Yocto Project 1.8 Release</title> + + <para> + This section provides migration information for moving to the + Yocto Project 1.8 Release from the prior release. + </para> + + <section id='migration-1.8-removed-recipes'> + <title>Removed Recipes</title> + + <para> + The following recipes have been removed: + <itemizedlist> + <listitem><para><filename>owl-video</filename>: + Functionality replaced by <filename>gst-player</filename>. + </para></listitem> + <listitem><para><filename>gaku</filename>: + Functionality replaced by <filename>gst-player</filename>. + </para></listitem> + <listitem><para><filename>gnome-desktop</filename>: + This recipe is now available in + <filename>meta-gnome</filename> and is no longer needed. + </para></listitem> + <listitem><para><filename>gsettings-desktop-schemas</filename>: + This recipe is now available in + <filename>meta-gnome</filename> and is no longer needed. + </para></listitem> + <listitem><para><filename>python-argparse</filename>: + The <filename>argparse</filename> module is already + provided in the default Python distribution in a + package named <filename>python-argparse</filename>. + Consequently, the separate + <filename>python-argparse</filename> recipe is no + longer needed. + </para></listitem> + <listitem><para><filename>telepathy-python, libtelepathy, telepathy-glib, telepathy-idle, telepathy-mission-control</filename>: + All these recipes have moved to + <filename>meta-oe</filename> and are consequently no + longer needed by any recipes in OpenEmbedded-Core. + </para></listitem> + <listitem><para><filename>linux-yocto_3.10</filename> and <filename>linux-yocto_3.17</filename>: + Support for the linux-yocto 3.10 and 3.17 kernels has been + dropped. + Support for the 3.14 kernel remains, while support for + 3.19 kernel has been added. + </para></listitem> + <listitem><para><filename>poky-feed-config-opkg</filename>: + This recipe has become obsolete and is no longer needed. + Use <filename>distro-feed-config</filename> from + <filename>meta-oe</filename> instead. + </para></listitem> + <listitem><para><filename>libav 0.8.x</filename>: + <filename>libav 9.x</filename> is now used. + </para></listitem> + <listitem><para><filename>sed-native</filename>: + No longer needed. + A working version of <filename>sed</filename> is expected + to be provided by the host distribution. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-1.8-bluez'> + <title>BlueZ 4.x / 5.x Selection</title> + + <para> + Proper built-in support for selecting BlueZ 5.x in preference + to the default of 4.x now exists. + To use BlueZ 5.x, simply add "bluez5" to your + <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link> + value. + If you had previously added append files + (<filename>*.bbappend</filename>) to make this selection, you can + now remove them. + </para> + + <para> + Additionally, a + <link linkend='ref-classes-bluetooth'><filename>bluetooth</filename></link> + class has been added to make selection of the appropriate bluetooth + support within a recipe a little easier. + If you wish to make use of this class in a recipe, add something + such as the following: + <literallayout class='monospaced'> + inherit bluetooth + PACKAGECONFIG ??= "${@bb.utils.contains('DISTRO_FEATURES', 'bluetooth', '${BLUEZ}', '', d)} + PACKAGECONFIG[bluez4] = "--enable-bluetooth,--disable-bluetooth,bluez4" + PACKAGECONFIG[bluez5] = "--enable-bluez5,--disable-bluez5,bluez5" + </literallayout> + </para> + </section> + + <section id='migration-1.8-kernel-build-changes'> + <title>Kernel Build Changes</title> + + <para> + The kernel build process was changed to place the source + in a common shared work area and to place build artifacts + separately in the source code tree. + In theory, migration paths have been provided for most common + usages in kernel recipes but this might not work in all cases. + In particular, users need to ensure that + <filename>${S}</filename> (source files) and + <filename>${B}</filename> (build artifacts) are used + correctly in functions such as + <link linkend='ref-tasks-configure'><filename>do_configure</filename></link> + and + <link linkend='ref-tasks-install'><filename>do_install</filename></link>. + For kernel recipes that do not inherit from + <filename>kernel-yocto</filename> or include + <filename>linux-yocto.inc</filename>, you might wish to + refer to the <filename>linux.inc</filename> file in the + <filename>meta-oe</filename> layer for the kinds of changes you + need to make. + For reference, here is the + <ulink url='http://cgit.openembedded.org/meta-openembedded/commit/meta-oe/recipes-kernel/linux/linux.inc?id=fc7132ede27ac67669448d3d2845ce7d46c6a1ee'>commit</ulink> + where the <filename>linux.inc</filename> file in + <filename>meta-oe</filename> was updated. + </para> + + <para> + Recipes that rely on the kernel source code and do not inherit + the module classes might need to add explicit dependencies on + the <filename>do_shared_workdir</filename> kernel task, for example: + <literallayout class='monospaced'> + do_configure[depends] += "virtual/kernel:do_shared_workdir" + </literallayout> + </para> + </section> + + <section id='migration-1.8-ssl'> + <title>SSL 3.0 is Now Disabled in OpenSSL</title> + + <para> + SSL 3.0 is now disabled when building OpenSSL. + Disabling SSL 3.0 avoids any lingering instances of the POODLE + vulnerability. + If you feel you must re-enable SSL 3.0, then you can add an + append file (<filename>*.bbappend</filename>) for the + <filename>openssl</filename> recipe to remove "-no-ssl3" + from + <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>. + </para> + </section> + + <section id='migration-1.8-default-sysroot-poisoning'> + <title>Default Sysroot Poisoning</title> + + <para> + <filename>gcc's</filename> default sysroot and include directories + are now "poisoned". + In other words, the sysroot and include directories are being + redirected to a non-existent location in order to catch when + host directories are being used due to the correct options not + being passed. + This poisoning applies both to the cross-compiler used within the + build and to the cross-compiler produced in the SDK. + </para> + + <para> + If this change causes something in the build to fail, it almost + certainly means the various compiler flags and commands are not + being passed correctly to the underlying piece of software. + In such cases, you need to take corrective steps. + </para> + </section> + + <section id='migration-1.8-rebuild-improvements'> + <title>Rebuild Improvements</title> + + <para> + Changes have been made to the + <link linkend='ref-classes-base'><filename>base</filename></link>, + <link linkend='ref-classes-autotools'><filename>autotools</filename></link>, + and + <link linkend='ref-classes-cmake'><filename>cmake</filename></link> + classes to clean out generated files when the + <link linkend='ref-tasks-configure'><filename>do_configure</filename></link> + task needs to be re-executed. + </para> + + <para> + One of the improvements is to attempt to run "make clean" during + the <filename>do_configure</filename> task if a + <filename>Makefile</filename> exists. + Some software packages do not provide a working clean target + within their make files. + If you have such recipes, you need to set + <link linkend='var-CLEANBROKEN'><filename>CLEANBROKEN</filename></link> + to "1" within the recipe, for example: + <literallayout class='monospaced'> + CLEANBROKEN = "1" + </literallayout> + </para> + </section> + + <section id='migration-1.8-qa-check-and-validation-changes'> + <title>QA Check and Validation Changes</title> + + <para> + The following QA Check and Validation Changes have occurred: + <itemizedlist> + <listitem><para> + Usage of + <link linkend='var-PRINC'><filename>PRINC</filename></link> + previously triggered a warning. + It now triggers an error. + You should remove any remaining usage of + <filename>PRINC</filename> in any recipe or append file. + </para></listitem> + <listitem><para> + An additional QA check has been added to detect usage of + <filename>${D}</filename> in + <link linkend='var-FILES'><filename>FILES</filename></link> + values where + <link linkend='var-D'><filename>D</filename></link> values + should not be used at all. + The same check ensures that <filename>$D</filename> is used + in + <filename>pkg_preinst/pkg_postinst/pkg_prerm/pkg_postrm</filename> + functions instead of <filename>${D}</filename>. + </para></listitem> + <listitem><para> + <link linkend='var-S'><filename>S</filename></link> now + needs to be set to a valid value within a recipe. + If <filename>S</filename> is not set in the recipe, the + directory is not automatically created. + If <filename>S</filename> does not point to a directory + that exists at the time the + <link linkend='ref-tasks-unpack'><filename>do_unpack</filename></link> + task finishes, a warning will be shown. + </para></listitem> + <listitem><para> + <link linkend='var-LICENSE'><filename>LICENSE</filename></link> + is now validated for correct formatting of multiple + licenses. + If the format is invalid (e.g. multiple licenses are + specified with no operators to specify how the multiple + licenses interact), then a warning will be shown. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-1.8-miscellaneous-changes'> + <title>Miscellaneous Changes</title> + + <para> + The following miscellaneous changes have occurred: + <itemizedlist> + <listitem><para> + The <filename>send-error-report</filename> script now + expects a "-s" option to be specified before the server + address. + This assumes a server address is being specified. + </para></listitem> + <listitem><para> + The <filename>oe-pkgdata-util</filename> script now + expects a "-p" option to be specified before the + <filename>pkgdata</filename> directory, which is now + optional. + If the <filename>pkgdata</filename> directory is not + specified, the script will run BitBake to query + <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link> + from the build environment. + </para></listitem> + </itemizedlist> + </para> + </section> +</section> + </chapter> <!-- vim: expandtab tw=80 ts=4 diff --git a/documentation/ref-manual/ref-bitbake.xml b/documentation/ref-manual/ref-bitbake.xml index 28496dec9a..30aff6431f 100644 --- a/documentation/ref-manual/ref-bitbake.xml +++ b/documentation/ref-manual/ref-bitbake.xml @@ -169,7 +169,7 @@ <filename>packagegroup-core-x11-sato</filename>, which in turn leads to recipes like <filename>matchbox-terminal</filename>, <filename>pcmanfm</filename> and <filename>gthumb</filename>. - These recipes in turn depend on <filename>eglibc</filename> and the toolchain. + These recipes in turn depend on <filename>glibc</filename> and the toolchain. </para> <para> diff --git a/documentation/ref-manual/ref-classes.xml b/documentation/ref-manual/ref-classes.xml index fed25b25e6..4eb61c5ba5 100644 --- a/documentation/ref-manual/ref-classes.xml +++ b/documentation/ref-manual/ref-classes.xml @@ -116,19 +116,19 @@ 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> ‐ + <listitem><para><link linkend='ref-tasks-configure'><filename>do_configure</filename></link> - Regenerates the configure script (using <filename>autoreconf</filename>) and then launches it with a standard set of arguments used during cross-compilation. You can pass additional parameters to <filename>configure</filename> through the <filename><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link></filename> variable. </para></listitem> - <listitem><para><link linkend='ref-tasks-compile'><filename>do_compile</filename></link> ‐ Runs <filename>make</filename> with + <listitem><para><link linkend='ref-tasks-compile'><filename>do_compile</filename></link> - Runs <filename>make</filename> with arguments that specify the compiler and linker. You can pass additional arguments through the <filename><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></filename> variable. </para></listitem> - <listitem><para><link linkend='ref-tasks-install'><filename>do_install</filename></link> ‐ Runs <filename>make install</filename> + <listitem><para><link linkend='ref-tasks-install'><filename>do_install</filename></link> - Runs <filename>make install</filename> and passes in <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename> as <filename>DESTDIR</filename>. @@ -270,6 +270,23 @@ </para> </section> +<section id='ref-classes-bluetooth'> + <title><filename>bluetooth.bbclass</filename></title> + + <para> + The <filename>bluetooth</filename> class defines a variable that + expands to the recipe (package) providing core + bluetooth support on the platform. + </para> + + <para> + For details on how the class works, see the + <filename>meta/classes/bluetooth.bbclass</filename> file in the Yocto + Project + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. + </para> +</section> + <section id='ref-classes-boot-directdisk'> <title><filename>boot-directdisk.bbclass</filename></title> @@ -580,8 +597,8 @@ <para> The <filename>debian</filename> class renames output packages so that - they follow the Debian naming policy (i.e. <filename>eglibc</filename> - becomes <filename>libc6</filename> and <filename>eglibc-devel</filename> + they follow the Debian naming policy (i.e. <filename>glibc</filename> + becomes <filename>libc6</filename> and <filename>glibc-devel</filename> becomes <filename>libc6-dev</filename>.) Renaming includes the library name and version as part of the package name. @@ -1177,7 +1194,7 @@ <link linkend='var-ICECC_DISABLED'><filename>ICECC_DISABLED</filename></link> variable to "1" as follows: <literallayout class='monospaced'> - INHERIT_DISTRO += "icecc" + INHERIT_DISTRO_append = " icecc" ICECC_DISABLED ??= "1" </literallayout> This practice makes sure everyone is using the same signatures but also @@ -1680,7 +1697,11 @@ <listitem><para><emphasis><filename>textrel:</filename></emphasis> Checks for ELF binaries that contain relocations in their <filename>.text</filename> sections, which can result in a - performance impact at runtime.</para></listitem> + performance impact at runtime. + See the explanation for the + <link linkend='qa-issue-textrel'><filename>ELF binary</filename></link> + message for more information regarding runtime performance issues. + </para></listitem> <listitem><para><emphasis><filename>unsafe-references-in-binaries:</filename></emphasis> Reports when a binary installed in <filename>${base_libdir}</filename>, @@ -2160,6 +2181,11 @@ <link linkend='ref-classes-package_ipk'><filename>package_ipk</filename></link>, and <link linkend='ref-classes-package_tar'><filename>package_tar</filename></link>. + <note><title>Warning</title> + The <filename>package_tar</filename> class is broken and not + supported. + It is recommended that you do not use this class. + </note> </para> <para> @@ -2237,11 +2263,12 @@ <para> The <filename>package_deb</filename> class - provides support for creating packages that use the - <filename>.deb</filename> file format. - The class ensures the packages are written out to the - <filename>${</filename><link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link><filename>}/deb</filename> - directory in a <filename>.deb</filename> file format. + provides support for creating packages that use the Debian + (i.e. <filename>.deb</filename>) file format. + The class ensures the packages are written out in a + <filename>.deb</filename> file format to the + <filename>${</filename><link linkend='var-DEPLOY_DIR_DEB'><filename>DEPLOY_DIR_DEB</filename></link><filename>}</filename> + directory. </para> <para> @@ -2258,11 +2285,12 @@ <para> The <filename>package_ipk</filename> class - provides support for creating packages that use the - <filename>.ipk</filename> file format. - The class ensures the packages are written out to the - <filename>${</filename><link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link><filename>}/ipk</filename> - directory in a <filename>.ipk</filename> file format. + provides support for creating packages that use the IPK + (i.e. <filename>.ipk</filename>) file format. + The class ensures the packages are written out in a + <filename>.ipk</filename> file format to the + <filename>${</filename><link linkend='var-DEPLOY_DIR_IPK'><filename>DEPLOY_DIR_IPK</filename></link><filename>}</filename> + directory. </para> <para> @@ -2278,12 +2306,13 @@ <title><filename>package_rpm.bbclass</filename></title> <para> - The <filename>package_deb</filename> class - provides support for creating packages that use the - <filename>.rpm</filename> file format. - The class ensures the packages are written out to the - <filename>${</filename><link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link><filename>}/rpm</filename> - directory in a <filename>.rpm</filename> file format. + The <filename>package_rpm</filename> class + provides support for creating packages that use the RPM + (i.e. <filename>.rpm</filename>) file format. + The class ensures the packages are written out in a + <filename>.rpm</filename> file format to the + <filename>${</filename><link linkend='var-DEPLOY_DIR_RPM'><filename>DEPLOY_DIR_RPM</filename></link><filename>}</filename> + directory. </para> <para> @@ -2299,12 +2328,12 @@ <title><filename>package_tar.bbclass</filename></title> <para> - The <filename>package_tar</filename> - class provides support for creating packages that use the - <filename>.tar</filename> file format. - The class ensures the packages are written out to the - <filename>${</filename><link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link><filename>}/tar</filename> - directory in a <filename>.tar</filename> file format. + The <filename>package_tar</filename> class + provides support for creating tarballs. + The class ensures the packages are written out in a + tarball format to the + <filename>${</filename><link linkend='var-DEPLOY_DIR_TAR'><filename>DEPLOY_DIR_TAR</filename></link><filename>}</filename> + directory. </para> <para> @@ -2797,7 +2826,7 @@ file. Here is an example: <literallayout class='monospaced'> - RM_WORK_EXCLUDE += "busybox eglibc" + RM_WORK_EXCLUDE += "busybox glibc" </literallayout> </para> </section> diff --git a/documentation/ref-manual/ref-features.xml b/documentation/ref-manual/ref-features.xml index 230cabd155..b90ba7947d 100644 --- a/documentation/ref-manual/ref-features.xml +++ b/documentation/ref-manual/ref-features.xml @@ -222,13 +222,21 @@ <para> The following image features are available for all images: <itemizedlist> + <listitem><para><emphasis>allow-empty-password:</emphasis> + Allows Dropbear and OpenSSH to accept root logins + and logins from accounts having an empty password string. + </para></listitem> <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). + allows root logins without passwords and enables + post-installation logging). + See the 'allow-empty-password', 'empty-root-password', + and 'post-install-logging' features in this list for + additional information. </para></listitem> <listitem><para><emphasis>dev-pkgs:</emphasis> Installs development packages (headers and extra library @@ -238,10 +246,19 @@ documentation packages for all packages installed in a given image. </para></listitem> + <listitem><para><emphasis>empty-root-password:</emphasis> + Sets the root password to an empty string, which allows + logins with a blank password. + </para></listitem> <listitem><para><emphasis>package-management:</emphasis> Installs package management tools and preserves the package manager database. </para></listitem> + <listitem><para><emphasis>post-install-logging:</emphasis> + Enables logging postinstall script runs to + the <filename>/var/log/postinstall.log</filename> file + on first boot of the image on the target system. + </para></listitem> <listitem><para><emphasis>ptest-pkgs:</emphasis> Installs ptest packages for all ptest-enabled recipes. </para></listitem> diff --git a/documentation/ref-manual/ref-manual-customization.xsl b/documentation/ref-manual/ref-manual-customization.xsl index b58b1dcaf9..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"/> diff --git a/documentation/ref-manual/ref-manual-eclipse-customization.xsl b/documentation/ref-manual/ref-manual-eclipse-customization.xsl index 4e6b7997b8..4ac63ddc4e 100644 --- a/documentation/ref-manual/ref-manual-eclipse-customization.xsl +++ b/documentation/ref-manual/ref-manual-eclipse-customization.xsl @@ -6,7 +6,7 @@ version="1.0"> <xsl:import - href="http://docbook.sourceforge.net/release/xsl/current/eclipse/eclipse3.xsl" /> + href="http://docbook.sourceforge.net/release/xsl/1.76.1/eclipse/eclipse3.xsl" /> <xsl:param name="chunker.output.indent" select="'yes'"/> <xsl:param name="chunk.quietly" select="1"/> diff --git a/documentation/ref-manual/ref-manual.xml b/documentation/ref-manual/ref-manual.xml index 39b64e07bb..58f6ae390e 100644 --- a/documentation/ref-manual/ref-manual.xml +++ b/documentation/ref-manual/ref-manual.xml @@ -88,9 +88,9 @@ <revremark>Released with the Yocto Project 1.7 Release.</revremark> </revision> <revision> - <revnumber>1.7.1</revnumber> - <date>January 2015</date> - <revremark>Released with the Yocto Project 1.7.1 Release.</revremark> + <revnumber>1.8</revnumber> + <date>April 2015</date> + <revremark>Released with the Yocto Project 1.8 Release.</revremark> </revision> </revhistory> diff --git a/documentation/ref-manual/ref-qa-checks.xml b/documentation/ref-manual/ref-qa-checks.xml index 871cd294f6..2747766a9e 100644 --- a/documentation/ref-manual/ref-qa-checks.xml +++ b/documentation/ref-manual/ref-qa-checks.xml @@ -467,6 +467,21 @@ can be found then it should be implemented. I can't find one at the moment. </para> <para> + Typically, the way to solve this performance issue is to + add "-fPIC" or "-fpic" to the compiler command-line + options. + For example, given software that reads + <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link> + when you build it, you could add the following to your + recipe: + <literallayout class='monospaced'> + CFLAGS_append = " -fPIC " + </literallayout> + For more information on text relocations at runtime, see + <ulink url='http://www.akkadia.org/drepper/textrelocs.html'></ulink>. + </para> + + <para> </para> </listitem> @@ -894,7 +909,7 @@ can be found then it should be implemented. I can't find one at the moment. and there is another option that should be used instead. If you are unsure, consult the upstream build documentation, the - <filename>./configure ‐‐help</filename> output, + <filename>./configure --help</filename> output, and the upstream change log or release notes. Once you have worked out what the appropriate change is, you can update diff --git a/documentation/ref-manual/ref-structure.xml b/documentation/ref-manual/ref-structure.xml index 14419d3a84..f084f15021 100644 --- a/documentation/ref-manual/ref-structure.xml +++ b/documentation/ref-manual/ref-structure.xml @@ -323,7 +323,7 @@ <para> If you do not provide a port number with the script, the - BitBake server at port "12345" is started. + BitBake server starts at a randomnly selected port. </para> <para> @@ -373,7 +373,7 @@ <filename>source</filename> the script, the Build Directory is created using that name. For example, the following command starts the BitBake server using - the default port "12345" and creates a Build Directory named + a randomnly selected port and creates a Build Directory named <filename>mybuilds</filename> that is outside of the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>: <literallayout class='monospaced'> @@ -467,12 +467,8 @@ <filename><link linkend='var-MACHINE'>MACHINE</link></filename> for which you want to build, which package types you wish to use (<link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>), - the location from which you want to access downloaded files - (<filename><link linkend='var-DL_DIR'>DL_DIR</link></filename>), - and how you want your host machine to use resources - (<link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link> - and - <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>). + and the location from which you want to access downloaded files + (<filename><link linkend='var-DL_DIR'>DL_DIR</link></filename>). </para> <para> @@ -526,9 +522,7 @@ which are directory trees, traversed (or walked) by BitBake. The <filename>bblayers.conf</filename> file uses the <link linkend='var-BBLAYERS'><filename>BBLAYERS</filename></link> - variable to list the layers BitBake tries to find, and uses the - <link linkend='var-BBLAYERS_NON_REMOVABLE'><filename>BBLAYERS_NON_REMOVABLE</filename></link> - variable to list layers that must not be removed. + variable to list the layers BitBake tries to find. </para> <para> @@ -695,7 +689,7 @@ <para> This directory receives package licensing information. For example, the directory contains sub-directories for <filename>bash</filename>, - <filename>busybox</filename>, and <filename>eglibc</filename> (among others) that in turn + <filename>busybox</filename>, and <filename>glibc</filename> (among others) that in turn contain appropriate <filename>COPYING</filename> license files with other licensing information. For information on licensing, see the "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</ulink>" @@ -833,7 +827,7 @@ Within this directory, the source is unpacked to <filename>linux-qemux86-standard-build</filename> and then patched by Quilt. (See the - "<ulink url='&YOCTO_DOCS_DEV_URL;#using-a-quilt-workflow'>Using a Quilt Flow</ulink>" + "<ulink url='&YOCTO_DOCS_DEV_URL;#using-a-quilt-workflow'>Using Quilt in Your Workflow</ulink>" section in the Yocto Project Development Manual for more information.) Within the <filename>linux-qemux86-standard-build</filename> directory, standard Quilt directories <filename>linux-3.0/patches</filename> diff --git a/documentation/ref-manual/ref-style.css b/documentation/ref-manual/ref-style.css index e04b5006b4..8ea8dac730 100644 --- a/documentation/ref-manual/ref-style.css +++ b/documentation/ref-manual/ref-style.css @@ -193,6 +193,44 @@ h3.author { padding: 0em 0em 0em 0em; } +/* Use this set when you decide to get the images in for variables. + +div.glossary dl, +div.variablelist dl { +} + +.glossary dl dt, +.variablelist dl dt, +.variablelist dl dt span.term { + font-weight: normal; + width: 0em; + text-align: right; +} + +.variablelist dl dt { + margin-top: 0.5em; +} + +.glossary dl dd, +.variablelist dl dd { + margin-top: 0em; + margin-left: 15.5em; + margin-bottom: 2em; +} + +.glossary dd p, +.variablelist dd p { + margin-top: 0em; + margin-bottom: 1em; +} + +.glossdeffirst { + text-indent: -70px; +} +*/ + +/* Start of non-image set */ + div.glossary dl, div.variablelist dl { } @@ -211,7 +249,7 @@ div.variablelist dl { .glossary dl dd, .variablelist dl dd { - margin-top: -1em; + margin-top: 0em; margin-left: 25.5em; } @@ -221,6 +259,11 @@ div.variablelist dl { margin-bottom: 1em; } +.glossdeffirst { + text-indent: 0px; +} + +/* End of non-image set */ div.calloutlist table td { padding: 0em 0em 0em 0em; diff --git a/documentation/ref-manual/ref-tasks.xml b/documentation/ref-manual/ref-tasks.xml index f325f0e233..59b4d9607a 100644 --- a/documentation/ref-manual/ref-tasks.xml +++ b/documentation/ref-manual/ref-tasks.xml @@ -144,9 +144,13 @@ <title><filename>do_package_write_deb</filename></title> <para> - Creates the actual DEB packages and places them in the - <link linkend='package-feeds-dev-environment'>Package Feeds</link> - area. + Creates Debian packages (i.e. <filename>*.deb</filename> files) and + places them in the + <filename>${</filename><link linkend='var-DEPLOY_DIR_DEB'><filename>DEPLOY_DIR_DEB</filename></link><filename>}</filename> + directory in the package feeds area. + For more information, see the + "<link linkend='package-feeds-dev-environment'>Package Feeds</link>" + section. </para> </section> @@ -154,9 +158,13 @@ <title><filename>do_package_write_ipk</filename></title> <para> - Creates the actual IPK packages and places them in the - <link linkend='package-feeds-dev-environment'>Package Feeds</link> - area. + Creates IPK packages (i.e. <filename>*.ipk</filename> files) and + places them in the + <filename>${</filename><link linkend='var-DEPLOY_DIR_IPK'><filename>DEPLOY_DIR_IPK</filename></link><filename>}</filename> + directory in the package feeds area. + For more information, see the + "<link linkend='package-feeds-dev-environment'>Package Feeds</link>" + section. </para> </section> @@ -164,9 +172,13 @@ <title><filename>do_package_write_rpm</filename></title> <para> - Creates the actual RPM packages and places them in the - <link linkend='package-feeds-dev-environment'>Package Feeds</link> - area. + Creates RPM packages (i.e. <filename>*.rpm</filename> files) and + places them in the + <filename>${</filename><link linkend='var-DEPLOY_DIR_RPM'><filename>DEPLOY_DIR_RPM</filename></link><filename>}</filename> + directory in the package feeds area. + For more information, see the + "<link linkend='package-feeds-dev-environment'>Package Feeds</link>" + section. </para> </section> @@ -174,9 +186,12 @@ <title><filename>do_package_write_tar</filename></title> <para> - Creates tar archives for packages and places them in the - <link linkend='package-feeds-dev-environment'>Package Feeds</link> - area. + Creates tarballs and places them in the + <filename>${</filename><link linkend='var-DEPLOY_DIR_TAR'><filename>DEPLOY_DIR_TAR</filename></link><filename>}</filename> + directory in the package feeds area. + For more information, see the + "<link linkend='package-feeds-dev-environment'>Package Feeds</link>" + section. </para> </section> @@ -628,7 +643,8 @@ <para> Checks the size of the kernel image against - <filename>KERNEL_IMAGE_MAXSIZE</filename> when set. + <link linkend='var-KERNEL_IMAGE_MAXSIZE'><filename>KERNEL_IMAGE_MAXSIZE</filename></link> + when set. </para> </section> diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml index b22c661421..ecac2b6c26 100644 --- a/documentation/ref-manual/ref-variables.xml +++ b/documentation/ref-manual/ref-variables.xml @@ -18,11 +18,11 @@ <para> <link linkend='var-ABIEXTENSION'>A</link> <link linkend='var-B'>B</link> - <link linkend='var-CFLAGS'>C</link> + <link linkend='var-CACHE'>C</link> <link linkend='var-D'>D</link> <link linkend='var-EFI_PROVIDER'>E</link> <link linkend='var-FEATURE_PACKAGES'>F</link> - <link linkend='var-GLIBC_GENERATE_LOCALES'>G</link> + <link linkend='var-GDB'>G</link> <link linkend='var-HOMEPAGE'>H</link> <link linkend='var-ICECC_DISABLED'>I</link> <!-- <link linkend='var-glossary-j'>J</link> --> @@ -30,16 +30,16 @@ <link linkend='var-LABELS'>L</link> <link linkend='var-MACHINE'>M</link> <!-- <link linkend='var-glossary-n'>N</link> --> - <link linkend='var-OE_BINCONFIG_EXTRA_MANGLE'>O</link> + <link linkend='var-OBJCOPY'>O</link> <link linkend='var-P'>P</link> <link linkend='var-QMAKE_PROFILES'>Q</link> - <link linkend='var-RCONFLICTS'>R</link> + <link linkend='var-RANLIB'>R</link> <link linkend='var-S'>S</link> <link linkend='var-T'>T</link> <link linkend='var-UBOOT_CONFIG'>U</link> <!-- <link linkend='var-glossary-v'>V</link> --> <link linkend='var-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> @@ -47,8 +47,12 @@ <glossdiv id='var-glossary-a'><title>A</title> <glossentry id='var-ABIEXTENSION'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Extension to the Application Binary Interface (ABI) field of the GNU canonical architecture name (e.g. "eabi"). @@ -66,9 +70,13 @@ </glossdef> </glossentry> - <glossentry id='var-ALLOW_EMPTY'><glossterm>ALLOW_EMPTY</glossterm> + <glossentry id='var-ALLOW_EMPTY'><glossterm>ALLOW_EMPTY</glossterm> + <info> + ALLOW_EMPTY[doc] = "Specifies if an output package should still be produced if it is empty." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies if an output package should still be produced if it is empty. By default, BitBake does not produce empty packages. This default behavior can cause issues when there is an @@ -86,11 +94,15 @@ </literallayout> </para> </glossdef> - </glossentry> + </glossentry> - <glossentry id='var-ALTERNATIVE'><glossterm>ALTERNATIVE</glossterm> + <glossentry id='var-ALTERNATIVE'><glossterm>ALTERNATIVE</glossterm> + <info> + ALTERNATIVE[doc] = "Lists commands in a package that need an alternative binary naming scheme." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Lists commands in a package that need an alternative binary naming scheme. Sometimes the same command is provided in multiple packages. @@ -113,11 +125,15 @@ section. </para> </glossdef> - </glossentry> + </glossentry> - <glossentry id='var-ALTERNATIVE_LINK_NAME'><glossterm>ALTERNATIVE_LINK_NAME</glossterm> + <glossentry id='var-ALTERNATIVE_LINK_NAME'><glossterm>ALTERNATIVE_LINK_NAME</glossterm> + <info> + ALTERNATIVE_LINK_NAME[doc] = "Used by the alternatives system to map duplicated commands to actual locations." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Used by the alternatives system to map duplicated commands to actual locations. For example, if the <filename>bracket</filename> command @@ -128,6 +144,9 @@ <literallayout class='monospaced'> ALTERNATIVE_LINK_NAME[bracket] = "/usr/bin/[" </literallayout> + </para> + + <para> In this example, the binary for the <filename>bracket</filename> command (i.e. <filename>[</filename>) from the @@ -146,11 +165,15 @@ section. </para> </glossdef> - </glossentry> + </glossentry> - <glossentry id='var-ALTERNATIVE_PRIORITY'><glossterm>ALTERNATIVE_PRIORITY</glossterm> + <glossentry id='var-ALTERNATIVE_PRIORITY'><glossterm>ALTERNATIVE_PRIORITY</glossterm> + <info> + ALTERNATIVE_PRIORITY[doc] = "Used by the alternatives system to create default priorities for duplicated commands." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Used by the alternatives system to create default priorities for duplicated commands. You can use the variable to create a single default @@ -171,11 +194,15 @@ section. </para> </glossdef> - </glossentry> + </glossentry> - <glossentry id='var-ALTERNATIVE_TARGET'><glossterm>ALTERNATIVE_TARGET</glossterm> + <glossentry id='var-ALTERNATIVE_TARGET'><glossterm>ALTERNATIVE_TARGET</glossterm> + <info> + ALTERNATIVE_TARGET[doc] = "Used by the alternatives system to create default link locations for duplicated commands." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Used by the alternatives system to create default link locations for duplicated commands. You can use the variable to create a single default @@ -222,11 +249,15 @@ section. </para> </glossdef> - </glossentry> + </glossentry> - <glossentry id='var-APPEND'><glossterm>APPEND</glossterm> + <glossentry id='var-APPEND'><glossterm>APPEND</glossterm> + <info> + APPEND[doc] = "An override list of append strings for each LABEL." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> An override list of append strings for each <link linkend='var-LABELS'><filename>LABEL</filename></link>. </para> @@ -237,11 +268,41 @@ class for more information on how this variable is used. </para> </glossdef> - </glossentry> + </glossentry> - <glossentry id='var-ASSUME_PROVIDED'><glossterm>ASSUME_PROVIDED</glossterm> + <glossentry id='var-AR'><glossterm>AR</glossterm> + <info> + AR[doc] = "Minimal command and arguments to run 'ar'." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + The minimal command and arguments used to run + <filename>ar</filename>. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-AS'><glossterm>AS</glossterm> + <info> + AS[doc] = "Minimal command and arguments to run the assembler." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + The minimal command and arguments used to run the + assembler. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-ASSUME_PROVIDED'><glossterm>ASSUME_PROVIDED</glossterm> + <info> + ASSUME_PROVIDED[doc] = "Lists recipe names (PN values) BitBake does not attempt to build." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Lists recipe names (<link linkend='var-PN'><filename>PN</filename></link> values) BitBake does not attempt to build. @@ -257,43 +318,139 @@ used rather than building <filename>git-native</filename>. </para> </glossdef> - </glossentry> + </glossentry> + + <glossentry id='var-ASSUME_SHLIBS'><glossterm>ASSUME_SHLIBS</glossterm> + <info> + ASSUME_SHLIBS[doc] = Provides additional shlibs provider mapping information, which adds to or overwrites the information provided automatically by the system." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Provides additional <filename>shlibs</filename> provider + mapping information, which adds to or overwrites the + information provided automatically by the system. + Separate multiple entries using spaces. + </para> + + <para> + As an example, use the following form to add an + <filename>shlib</filename> provider of + <replaceable>shlibname</replaceable> in + <replaceable>packagename</replaceable> with the optional + <replaceable>version</replaceable>: + <literallayout class='monospaced'> + <replaceable>shlibname:packagename</replaceable>[_<replaceable>version</replaceable>] + </literallayout> + </para> + + <para> + Here is an example that adds a shared library named + <filename>libEGL.so.1</filename> as being provided by + the <filename>libegl-implementation</filename> package: + <literallayout class='monospaced'> + ASSUME_SHLIBS = "libEGL.so.1:libegl-implementation" + </literallayout> + </para> + </glossdef> + </glossentry> - <glossentry id='var-AUTHOR'><glossterm>AUTHOR</glossterm> + <glossentry id='var-AUTHOR'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + 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_LIBNAME_PKGS'><glossterm>AUTO_LIBNAME_PKGS</glossterm> + <info> + AUTO_LIBNAME_PKGS[doc] = "Specifies which packages should be checked for libraries and renamed according to Debian library package naming." + </info> <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + When the + <link linkend='ref-classes-debian'><filename>debian</filename></link> + class is inherited, which is the default behavior, + <filename>AUTO_LIBNAME_PKGS</filename> specifies which + packages should be checked for libraries and renamed + according to Debian library package naming. + </para> + <para> - Enables creating an automatic menu. - You must set this in your recipe. + The default value is "${PACKAGES}", which causes the + debian class to act on all packages that are + explicitly generated by the recipe. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-AUTO_SYSLINUXMENU'><glossterm>AUTO_SYSLINUXMENU</glossterm> + <info> + AUTO_SYSLINUXMENU[doc] = "Enables creating an automatic menu for the syslinux bootloader." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + 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> + <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. + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + 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. Here is an example: <literallayout class='monospaced'> SRCREV = "${AUTOREV}" </literallayout> </para> + + <para> + If you use the previous statement to retrieve the latest + version of software, you need to be sure + <link linkend='var-PV'><filename>PV</filename></link> + contains + <filename>${</filename><link linkend='var-SRCPV'><filename>SRCPV</filename></link><filename>}</filename>. + For example, suppose you have a kernel recipe that + inherits the + <link linkend='ref-classes-kernel'>kernel</link> class + and you use the previous statement. + In this example, <filename>${SRCPV}</filename> does not + automatically get into <filename>PV</filename>. + Consequently, you need to change <filename>PV</filename> + in your recipe so that it does contain + <filename>${SRCPV}</filename>. + </para> </glossdef> </glossentry> <glossentry id='var-AVAILTUNES'><glossterm>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 role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The list of defined CPU and Application Binary Interface (ABI) tunings (i.e. "tunes") available for use by the OpenEmbedded build system. @@ -318,14 +475,17 @@ </glossdef> </glossentry> - </glossdiv> <glossdiv id='var-glossary-b'><title>B</title> <glossentry id='var-B'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The directory within the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> in which the OpenEmbedded build system places generated @@ -335,6 +495,9 @@ <literallayout class='monospaced'> S = "${WORKDIR}/${BP}/" </literallayout> + </para> + + <para> You can separate the (<filename>S</filename>) directory and the directory pointed to by the <filename>B</filename> variable. @@ -347,8 +510,12 @@ </glossentry> <glossentry id='var-BAD_RECOMMENDATIONS'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Lists "recommended-only" packages to not install. Recommended-only packages are packages installed only through the @@ -360,6 +527,9 @@ <literallayout class='monospaced'> BAD_RECOMMENDATIONS = "<replaceable>package_name</replaceable> <replaceable>package_name</replaceable> <replaceable>package_name</replaceable> ..." </literallayout> + </para> + + <para> 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: @@ -395,8 +565,12 @@ </glossentry> <glossentry id='var-BASE_LIB'><glossterm>BASE_LIB</glossterm> + <info> + BASE_LIB[doc] = "The library directory name for the CPU or Application Binary Interface (ABI) tune." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The library directory name for the CPU or Application Binary Interface (ABI) tune. The <filename>BASE_LIB</filename> applies only in the @@ -416,9 +590,26 @@ </glossdef> </glossentry> + <glossentry id='var-BASE_WORKDIR'><glossterm>BASE_WORKDIR</glossterm> + <info> + BASE_WORKDIR[doc] = "Points to the base of the work directory for all recipes." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Points to the base of the work directory for all recipes. + The default value is "${TMPDIR}/work". + </para> + </glossdef> + </glossentry> + <glossentry id='var-BB_DANGLINGAPPENDS_WARNONLY'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Defines how BitBake handles situations where an append file (<filename>.bbappend</filename>) has no corresponding recipe file (<filename>.bb</filename>). @@ -451,8 +642,12 @@ </glossentry> <glossentry id='var-BB_DISKMON_DIRS'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Monitors disk space and available inodes during the build and allows you to control the build based on these parameters. @@ -546,8 +741,12 @@ </glossentry> <glossentry id='var-BB_DISKMON_WARNINTERVAL'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Defines the disk space and free inode warning intervals. To set these intervals, define the variable in your <filename>conf/local.conf</filename> file in the @@ -614,8 +813,12 @@ </glossentry> <glossentry id='var-BB_GENERATE_MIRROR_TARBALLS'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Causes tarballs of the Git repositories, including the Git metadata, to be placed in the <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link> @@ -637,25 +840,30 @@ </glossentry> <glossentry id='var-BB_NUMBER_THREADS'><glossterm>BB_NUMBER_THREADS</glossterm> + <info> + BB_NUMBER_THREADS[doc] = "The maximum number of tasks BitBake should run in parallel at any one time. This variable is automatically configured to be equal to the number of build system cores." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> 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 - number of cores. - </para> - - <para> - The default value for <filename>BB_NUMBER_THREADS</filename> - is equal to the number of cores your build system has. + The OpenEmbedded build system automatically configures + this variable to be equal to the number of cores on the + build system. + To gain optimal parallelism, you should not have to + override this variable. </para> </glossdef> </glossentry> <glossentry id='var-BBCLASSEXTEND'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Allows you to extend a recipe so that it builds variants of the software. Common variants for recipes exist such as "natives" like <filename>quilt-native</filename>, which is a copy of Quilt built to run on the build system; @@ -678,8 +886,13 @@ </glossentry> <glossentry id='var-BBFILE_COLLECTIONS'><glossterm>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. + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Lists the names of configured layers. These names are used to find the other <filename>BBFILE_*</filename> variables. Typically, each layer will append its name to this variable in its @@ -689,20 +902,34 @@ </glossentry> <glossentry id='var-BBFILE_PATTERN'><glossterm>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 + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Variable that expands to match files from <link linkend='var-BBFILES'><filename>BBFILES</filename></link> in a particular layer. This variable is used in the <filename>conf/layer.conf</filename> file and must be suffixed with the name of the specific layer (e.g. - <filename>BBFILE_PATTERN_emenlow</filename>).</para> + <filename>BBFILE_PATTERN_emenlow</filename>). + </para> </glossdef> </glossentry> <glossentry id='var-BBFILE_PRIORITY'><glossterm>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 + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Assigns the priority for recipe files in each layer. + </para> + + <para> + This variable is useful in situations where the same recipe appears in more than one layer. Setting this variable allows you to prioritize a layer against other layers that contain the same recipe - effectively @@ -712,8 +939,11 @@ (<link linkend='var-PV'><filename>PV</filename></link> variable). For example, a layer that has a recipe with a higher <filename>PV</filename> value but for which the <filename>BBFILE_PRIORITY</filename> is set to have a lower precedence still has a - lower precedence.</para> - <para>A larger value for the <filename>BBFILE_PRIORITY</filename> variable results in a higher + lower precedence. + </para> + + <para> + A larger value for the <filename>BBFILE_PRIORITY</filename> variable results in a higher precedence. For example, the value 6 has a higher precedence than the value 5. If not specified, the <filename>BBFILE_PRIORITY</filename> variable is set based on layer @@ -722,7 +952,8 @@ more information. The default priority, if unspecified for a layer with no dependencies, is the lowest defined priority + 1 - (or 1 if no priorities are defined).</para> + (or 1 if no priorities are defined). + </para> <tip> You can use the command <filename>bitbake-layers show-layers</filename> to list all configured layers along with their priorities. @@ -731,20 +962,54 @@ </glossentry> <glossentry id='var-BBFILES'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + List of recipe files used by BitBake to build software. + </para> </glossdef> </glossentry> <glossentry id='var-BBINCLUDELOGS'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Variable that controls how BitBake displays logs on build failure. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BBINCLUDELOGS_LINES'><glossterm>BBINCLUDELOGS_LINES</glossterm> + <info> + BBINCLUDELOGS_LINES[doc] = "Amount of log lines printed on failure." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + If + <link linkend='var-BBINCLUDELOGS'><filename>BBINCLUDELOGS</filename></link> + is set, specifies the maximum number of lines from the + task log file to print when reporting a failed task. + If you do not set <filename>BBINCLUDELOGS_LINES</filename>, + the entire log is printed. + </para> </glossdef> </glossentry> <glossentry id='var-BBLAYERS'><glossterm>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. + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Lists the layers to enable during the build. This variable is defined in the <filename>bblayers.conf</filename> configuration file in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. Here is an example: @@ -761,6 +1026,17 @@ /home/scottrif/poky/meta-yocto \ " </literallayout> + <note> + The + <link linkend='var-BBLAYERS_NON_REMOVABLE'><filename>BBLAYERS_NON_REMOVABLE</filename></link> + variable exists only for + <ulink url='https://www.yoctoproject.org/tools-resources/projects/hob'>Hob</ulink>. + The OpenEmbedded build system does not use this + variable. + </note> + </para> + + <para> This example enables four layers, one of which is a custom, user-defined layer named <filename>meta-mykernel</filename>. </para> @@ -768,15 +1044,23 @@ </glossentry> <glossentry id='var-BBLAYERS_NON_REMOVABLE'><glossterm>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 + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Lists core layers that cannot be removed from the <filename>bblayers.conf</filename> file during a build using the <ulink url='https://www.yoctoproject.org/tools-resources/projects/hob'>Hob</ulink>. <note> - When building an image outside of Hob, this variable - is ignored. + When building an image outside of Hob, the OpenEmbedded + build system ignores this variable. </note> + </para> + + <para> In order for BitBake to build your image using Hob, your <filename>bblayers.conf</filename> file must include the <filename>meta</filename> and <filename>meta-yocto</filename> @@ -801,8 +1085,12 @@ </glossentry> <glossentry id='var-BBMASK'><glossterm>BBMASK</glossterm> + <info> + BBMASK[doc] = "Prevents BitBake from processing specific recipes or recipe append files. Use the BBMASK variable from within conf/local.conf." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Prevents BitBake from processing recipes and recipe append files. Use the <filename>BBMASK</filename> variable from within the @@ -861,8 +1149,12 @@ </glossentry> <glossentry id='var-BBPATH'><glossterm>BBPATH</glossterm> + <info> + BBPATH[doc] = "Used by BitBake to locate .bbclass and configuration files. This variable is analogous to the PATH variable." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Used by BitBake to locate <filename>.bbclass</filename> and configuration files. This variable is analogous to the @@ -886,8 +1178,12 @@ </glossentry> <glossentry id='var-BBSERVER'><glossterm>BBSERVER</glossterm> + <info> + BBSERVER[doc] = "Points to the server that runs memory-resident BitBake." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Points to the server that runs memory-resident BitBake. This variable is set by the <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link> @@ -898,6 +1194,9 @@ <literallayout class='monospaced'> export BBSERVER=localhost:$port </literallayout> + </para> + + <para> For more information on how the <filename>BBSERVER</filename> is used, see the <filename>oe-init-build-env-memres</filename> script, which @@ -908,8 +1207,12 @@ </glossentry> <glossentry id='var-BINCONFIG'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> When inheriting the <link linkend='ref-classes-binconfig-disabled'><filename>binconfig-disabled</filename></link> class, this variable specifies binary configuration @@ -932,8 +1235,12 @@ </glossentry> <glossentry id='var-BINCONFIG_GLOB'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> When inheriting the <link linkend='ref-classes-binconfig'><filename>binconfig</filename></link> class, this variable specifies a wildcard for @@ -956,20 +1263,31 @@ </glossentry> <glossentry id='var-BP'><glossterm>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 + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + The base recipe name and version but without any special recipe name suffix (i.e. <filename>-native</filename>, <filename>lib64-</filename>, and so forth). <filename>BP</filename> is comprised of the following: <literallayout class="monospaced"> ${BPN}-${PV} - </literallayout></para> + </literallayout> + </para> </glossdef> </glossentry> <glossentry id='var-BPN'><glossterm>BPN</glossterm> + <info> + BPN[doc] = "The bare name of the recipe. This variable is a version of the PN variable but removes common suffixes and prefixes." + </info> <glossdef> - <para>The bare name of the recipe. + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + The bare name of the recipe. This variable is a version of the <link linkend='var-PN'><filename>PN</filename></link> variable but removes common suffixes such as "-native" and "-cross" as well as removes common prefixes such as multilib's "lib64-" and "lib32-". @@ -978,13 +1296,18 @@ The exact list of prefixes removed is specified by the <link linkend='var-MLPREFIX'><filename>MLPREFIX</filename></link> variable. Prefixes are removed for <filename>multilib</filename> - and <filename>nativesdk</filename> cases.</para> + and <filename>nativesdk</filename> cases. + </para> </glossdef> </glossentry> <glossentry id='var-BUGTRACKER'><glossterm>BUGTRACKER</glossterm> + <info> + BUGTRACKER[doc] = "Specifies a URL for an upstream bug tracking website for a recipe." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies a URL for an upstream bug tracking website for a recipe. The OpenEmbedded build system does not use this variable. @@ -994,9 +1317,29 @@ </glossdef> </glossentry> + <glossentry id='var-BUILD_ARCH'><glossterm>BUILD_ARCH</glossterm> + <info> + BUILD_ARCH[doc] = "The name of the building architecture (e.g. i686)." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Specifies the architecture of the build host + (e.g. <filename>i686</filename>). + The OpenEmbedded build system sets the value of + <filename>BUILD_ARCH</filename> from the machine name + reported by the <filename>uname</filename> command. + </para> + </glossdef> + </glossentry> + <glossentry id='var-BUILD_CFLAGS'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the flags to pass to the C compiler when building for the build host. When building in the <filename>-native</filename> context, @@ -1007,8 +1350,12 @@ </glossentry> <glossentry id='var-BUILD_CPPFLAGS'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> 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. @@ -1020,8 +1367,12 @@ </glossentry> <glossentry id='var-BUILD_CXXFLAGS'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the flags to pass to the C++ compiler when building for the build host. When building in the <filename>native</filename> context, @@ -1032,8 +1383,12 @@ </glossentry> <glossentry id='var-BUILD_LDFLAGS'><glossterm>BUILD_LDFLAGS</glossterm> + <info> + BUILD_LDFLAGS[doc] = "Specifies the flags to pass to the linker when building for the build host." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the flags to pass to the linker when building for the build host. When building in the <filename>-native</filename> context, @@ -1044,8 +1399,12 @@ </glossentry> <glossentry id='var-BUILD_OPTIMIZATION'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the optimization flags passed to the C compiler when building for the build host or the SDK. The flags are passed through the @@ -1063,9 +1422,86 @@ </glossdef> </glossentry> - <glossentry id='var-BUILDDIR'><glossterm>BUILDDIR</glossterm> + <glossentry id='var-BUILD_OS'><glossterm>BUILD_OS</glossterm> + <info> + BUILD_OS[doc] = "The operating system (in lower case) of the building architecture (e.g. Linux)." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Specifies the operating system in use on the build + host (e.g. "linux"). + The OpenEmbedded build system sets the value of + <filename>BUILD_OS</filename> from the OS reported by + the <filename>uname</filename> command - the first word, + converted to lower-case characters. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BUILD_PREFIX'><glossterm>BUILD_PREFIX</glossterm> + <info> + BUILD_PREFIX[doc] = "The toolchain binary prefix used for native recipes." + </info> <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + The toolchain binary prefix used for native recipes. + The OpenEmbedded build system uses the + <filename>BUILD_PREFIX</filename> value to set the + <link linkend='var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></link> + when building for native recipes. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BUILD_SYS'><glossterm>BUILD_SYS</glossterm> + <info> + BUILD_SYS[doc] = "The toolchain binary prefix used for native recipes." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Specifies the system, including the architecture and + the operating system, to use when building for the build + host (i.e. when building <filename>native</filename> + recipes). + </para> + <para> + The OpenEmbedded build system automatically sets this + variable based on + <link linkend='var-BUILD_ARCH'><filename>BUILD_ARCH</filename></link>, + <link linkend='var-BUILD_VENDOR'><filename>BUILD_VENDOR</filename></link>, + and + <link linkend='var-BUILD_OS'><filename>BUILD_OS</filename></link>. + You do not need to set the <filename>BUILD_SYS</filename> + variable yourself. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BUILD_VENDOR'><glossterm>BUILD_VENDOR</glossterm> + <info> + BUILD_VENDOR[doc] = "The vendor name to use when building for the build host." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Specifies the vendor name to use when building for the + build host. + The default value is an empty string (""). + </para> + </glossdef> + </glossentry> + + <glossentry id='var-BUILDDIR'><glossterm>BUILDDIR</glossterm> + <info> + BUILDDIR[doc] = "Points to the location of the Build Directory." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Points to the location of the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. You can define this directory indirectly through the @@ -1082,8 +1518,12 @@ </glossentry> <glossentry id='var-BUILDHISTORY_COMMIT'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> When inheriting the <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link> class, this variable specifies whether or not to commit the @@ -1110,8 +1550,12 @@ </glossentry> <glossentry id='var-BUILDHISTORY_COMMIT_AUTHOR'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> When inheriting the <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link> class, this variable specifies the author to use for each @@ -1141,8 +1585,12 @@ </glossentry> <glossentry id='var-BUILDHISTORY_DIR'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> When inheriting the <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link> class, this variable specifies the directory in which @@ -1162,8 +1610,12 @@ </glossentry> <glossentry id='var-BUILDHISTORY_FEATURES'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> When inheriting the <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link> class, this variable specifies the build history features @@ -1203,8 +1655,12 @@ </glossentry> <glossentry id='var-BUILDHISTORY_IMAGE_FILES'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> When inheriting the <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link> class, this variable specifies a list of paths to files @@ -1232,8 +1688,12 @@ </glossentry> <glossentry id='var-BUILDHISTORY_PUSH_REPO'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> When inheriting the <link linkend='ref-classes-buildhistory'><filename>buildhistory</filename></link> class, this variable optionally specifies a remote @@ -1263,8 +1723,12 @@ </glossentry> <glossentry id='var-BUILDSDK_CFLAGS'><glossterm>BUILDSDK_CFLAGS</glossterm> + <info> + BUILDSDK_CFLAGS[doc] = "Specifies the flags to pass to the C compiler when building for the SDK." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the flags to pass to the C compiler when building for the SDK. When building in the <filename>nativesdk</filename> @@ -1276,8 +1740,12 @@ </glossentry> <glossentry id='var-BUILDSDK_CPPFLAGS'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> 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. @@ -1290,8 +1758,12 @@ </glossentry> <glossentry id='var-BUILDSDK_CXXFLAGS'><glossterm>BUILDSDK_CXXFLAGS</glossterm> + <info> + BUILDSDK_CXXFLAGS[doc] = "Specifies the flags to pass to the C++ compiler when building for the SDK." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the flags to pass to the C++ compiler when building for the SDK. When building in the <filename>nativesdk</filename> @@ -1303,8 +1775,12 @@ </glossentry> <glossentry id='var-BUILDSDK_LDFLAGS'><glossterm>BUILDSDK_LDFLAGS</glossterm> + <info> + BUILDSDK_LDFLAGS[doc] = "Specifies the flags to pass to the linker when building for the SDK." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the flags to pass to the linker when building for the SDK. When building in the <filename>nativesdk-</filename> @@ -1316,8 +1792,12 @@ </glossentry> <glossentry id='var-BUILDSTATS_BASE'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Points to the location of the directory that holds build statistics when you use and enable the <link linkend='ref-classes-buildstats'><filename>buildstats</filename></link> @@ -1330,8 +1810,12 @@ </glossentry> <glossentry id='var-BUSYBOX_SPLIT_SUID'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> For the BusyBox recipe, specifies whether to split the output executable file into two parts: one for features that require <filename>setuid root</filename>, and one for @@ -1352,9 +1836,42 @@ <glossdiv id='var-glossary-c'><title>C</title> + <glossentry id='var-CACHE'><glossterm>CACHE</glossterm> + <info> + CACHE[doc] = "The directory BitBake uses to store a cache of the metadata." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Specifies the directory BitBake uses to store a cache + of the + <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> + so it does not need to be parsed every time BitBake is + started. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-CC'><glossterm>CC</glossterm> + <info> + CC[doc] = "Minimum command and arguments to run the C compiler." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + The minimal command and arguments used to run the C + compiler. + </para> + </glossdef> + </glossentry> + <glossentry id='var-CFLAGS'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the flags to pass to the C compiler. This variable is exported to an environment variable and thus made visible to the software being @@ -1385,8 +1902,12 @@ </glossentry> <glossentry id='var-CLASSOVERRIDE'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> An internal variable specifying the special class override that should currently apply (e.g. "class-target", "class-native", and so forth). @@ -1410,9 +1931,32 @@ </glossdef> </glossentry> + <glossentry id='var-CLEANBROKEN'><glossterm>CLEANBROKEN</glossterm> + <info> + CLEANBROKEN[doc] = "Prevents the build system from running 'make clean' during the do_configure task." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + If set to "1" within a recipe, + <filename>CLEANBROKEN</filename> specifies that + the <filename>make clean</filename> command does + not work for the software being built. + Consequently, the OpenEmbedded build system will not try + to run <filename>make clean</filename> during the + <link linkend='ref-tasks-configure'><filename>do_configure</filename></link> + task, which is the default behavior. + </para> + </glossdef> + </glossentry> + <glossentry id='var-COMBINED_FEATURES'><glossterm>COMBINED_FEATURES</glossterm> + <info> + COMBINED_FEATURES[doc] = "A set of features common between MACHINE_FEATURES and DISTRO_FEATURES." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Provides a list of hardware features that are enabled in both <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link> @@ -1437,8 +1981,12 @@ </glossentry> <glossentry id='var-COMMON_LICENSE_DIR'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Points to <filename>meta/files/common-licenses</filename> in the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>, @@ -1448,8 +1996,13 @@ </glossentry> <glossentry id='var-COMPATIBLE_HOST'><glossterm>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 + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + 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. The regular expression is matched against @@ -1460,13 +2013,19 @@ Stopping these builds is particularly useful with kernels. The variable also helps to increase parsing speed since the build system skips parsing recipes not - compatible with the current system.</para> + compatible with the current system. + </para> </glossdef> </glossentry> <glossentry id='var-COMPATIBLE_MACHINE'><glossterm>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 + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + A regular expression that resolves to one or more target machines with which a recipe is compatible. The regular expression is matched against <link linkend="var-MACHINEOVERRIDES"><filename>MACHINEOVERRIDES</filename></link>. @@ -1475,13 +2034,18 @@ Stopping these builds is particularly useful with kernels. The variable also helps to increase parsing speed since the build system skips parsing recipes not - compatible with the current machine.</para> + compatible with the current machine. + </para> </glossdef> </glossentry> <glossentry id='var-COMPLEMENTARY_GLOB'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Defines wildcards to match when installing a list of complementary packages for all the packages explicitly (or implicitly) installed in an image. @@ -1506,9 +2070,29 @@ </glossdef> </glossentry> + <glossentry id='var-CONF_VERSION'><glossterm>CONF_VERSION</glossterm> + <info> + CONF_VERSION[doc] = "Tracks the version of local.conf. Increased each time build/conf/ changes incompatibly." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Tracks the version of the local configuration file + (i.e. <filename>local.conf</filename>). + The value for <filename>CONF_VERSION</filename> + increments each time <filename>build/conf/</filename> + compatibility changes. + </para> + </glossdef> + </glossentry> + <glossentry id='var-CONFFILES'><glossterm>CONFFILES</glossterm> + <info> + CONFFILES[doc] = "Identifies editable or configurable files that are part of a package." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Identifies editable or configurable files that are part of a package. If the Package Management System (PMS) is being used to update packages on the target system, it is possible that @@ -1557,8 +2141,12 @@ </glossentry> <glossentry id='var-CONFIG_INITRAMFS_SOURCE'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Identifies the initial RAM disk (initramfs) source files. The OpenEmbedded build system receives and uses this kernel Kconfig variable as an environment variable. @@ -1589,8 +2177,12 @@ </glossentry> <glossentry id='var-CONFIG_SITE'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> A list of files that contains <filename>autoconf</filename> test results relevant to the current build. This variable is used by the Autotools utilities when running @@ -1599,9 +2191,25 @@ </glossdef> </glossentry> + <glossentry id='var-CONFIGURE_FLAGS'><glossterm>CONFIGURE_FLAGS</glossterm> + <info> + CONFIGURE_FLAGS[doc] = "The minimal arguments for GNU configure." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + The minimal arguments for GNU configure. + </para> + </glossdef> + </glossentry> + <glossentry id='var-CONFLICT_DISTRO_FEATURES'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> When inheriting the <link linkend='ref-classes-distro_features_check'><filename>distro_features_check</filename></link> class, this @@ -1619,8 +2227,12 @@ </glossentry> <glossentry id='var-COPY_LIC_DIRS'><glossterm>COPY_LIC_DIRS</glossterm> + <info> + COPY_LIC_DIRS[doc] = "If set to "1" along with the COPY_LIC_MANIFEST variable, the OpenEmbedded build system copies into the image the license files, which are located in /usr/share/common-licenses, for each package." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> If set to "1" along with the <link linkend='var-COPY_LIC_MANIFEST'><filename>COPY_LIC_MANIFEST</filename></link> variable, the OpenEmbedded build system copies @@ -1629,13 +2241,17 @@ for each package. The license files are placed in directories within the image itself. - </para> + </para> </glossdef> </glossentry> <glossentry id='var-COPY_LIC_MANIFEST'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> If set to "1", the OpenEmbedded build system copies the license manifest for the image to <filename>/usr/share/common-licenses/license.manifest</filename> @@ -1645,8 +2261,12 @@ </glossentry> <glossentry id='var-CORE_IMAGE_EXTRA_INSTALL'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the list of packages to be added to the image. You should only set this variable in the <filename>local.conf</filename> configuration file found @@ -1661,8 +2281,12 @@ </glossentry> <glossentry id='var-COREBASE'><glossterm>COREBASE</glossterm> + <info> + COREBASE[doc] = "Specifies the parent directory of the OpenEmbedded Core Metadata layer (i.e. meta)." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the parent directory of the OpenEmbedded Core Metadata layer (i.e. <filename>meta</filename>). </para> @@ -1682,9 +2306,26 @@ </glossdef> </glossentry> + <glossentry id='var-CPP'><glossterm>CPP</glossterm> + <info> + CPP[doc] = "Minimum command and arguments to run the C preprocessor." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + The minimal command and arguments used to run the C + preprocessor. + </para> + </glossdef> + </glossentry> + <glossentry id='var-CPPFLAGS'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the flags to pass to the C pre-processor (i.e. to both the C and the C++ compilers). This variable is exported to an environment @@ -1715,9 +2356,61 @@ </glossdef> </glossentry> + <glossentry id='var-CROSS_COMPILE'><glossterm>CROSS_COMPILE</glossterm> + <info> + CROSS_COMPILE[doc] = "The toolchain binary prefix for the target tools." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + The toolchain binary prefix for the target tools. + The <filename>CROSS_COMPILE</filename> variable is the + same as the + <link linkend='var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></link> + variable. + <note> + The OpenEmbedded build system sets the + <filename>CROSS_COMPILE</filename> variable only in + certain contexts (e.g. when building for kernel + and kernel module recipes). + </note> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-CVSDIR'><glossterm>CVSDIR</glossterm> + <info> + CVSDIR[doc] = "The directory where cvs checkouts will be stored in." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + The directory in which files checked out under the + CVS system are stored. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-CXX'><glossterm>CXX</glossterm> + <info> + CXX[doc] = "Minimum command and arguments to run the C++ compiler." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + The minimal command and arguments used to run the C++ + compiler. + </para> + </glossdef> + </glossentry> + <glossentry id='var-CXXFLAGS'><glossterm>CXXFLAGS</glossterm> + <info> + CXXFLAGS[doc] = "Specifies the flags to pass to the C++ compiler." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the flags to pass to the C++ compiler. This variable is exported to an environment variable and thus made visible to the software being @@ -1752,8 +2445,12 @@ <glossdiv id='var-glossary-d'><title>D</title> <glossentry id='var-D'><glossterm>D</glossterm> + <info> + D[doc] = "The destination directory." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The destination directory. The location in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> where components are installed by the @@ -1767,18 +2464,88 @@ </glossdef> </glossentry> + <glossentry id='var-DATE'><glossterm>DATE</glossterm> + <info> + DATE[doc] = "The date the build was started using YMD format." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + The date the build was started. + Dates appear using the year, month, and day (YMD) format + (e.g. "20150209" for February 9th, 2015). + </para> + </glossdef> + </glossentry> + <glossentry id='var-DATETIME'><glossterm>DATETIME</glossterm> + <info> + DATETIME[doc] = "The date and time the build was started." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The date and time on which the current build started. The format is suitable for timestamps. </para> </glossdef> </glossentry> + <glossentry id='var-DEBIAN_NOAUTONAME'><glossterm>DEBIAN_NOAUTONAME</glossterm> + <info> + DEBIAN_NOAUTONAME[doc] = "Prevents a particular package from being renamed according to Debian package naming." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + When the + <link linkend='ref-classes-debian'><filename>debian</filename></link> + class is inherited, which is the default behavior, + <filename>DEBIAN_NOAUTONAME</filename> specifies a + particular package should not be renamed according to + Debian library package naming. + You must use the package name as an override when you + set this variable. + Here is an example from the <filename>fontconfig</filename> + recipe: + <literallayout class='monospaced'> + DEBIAN_NOAUTONAME_fontconfig-utils = "1" + </literallayout> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-DEBIANNAME'><glossterm>DEBIANNAME</glossterm> + <info> + DEBIANNAME[doc] = "Allows you to override the library name for an individual package for Debian library package renaming." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + When the + <link linkend='ref-classes-debian'><filename>debian</filename></link> + class is inherited, which is the default behavior, + <filename>DEBIANNAME</filename> allows you to override the + library name for an individual package. + Overriding the library name in these cases is rare. + You must use the package name as an override when you + set this variable. + Here is an example from the <filename>dbus</filename> + recipe: + <literallayout class='monospaced'> + DEBIANNAME_${PN} = "dbus-1" + </literallayout> + </para> + </glossdef> + </glossentry> + <glossentry id='var-DEBUG_BUILD'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies to build packages with debugging information. This influences the value of the <filename><link linkend='var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</link></filename> @@ -1788,8 +2555,12 @@ </glossentry> <glossentry id='var-DEBUG_OPTIMIZATION'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The options to pass in <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename> and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename> when compiling @@ -1800,10 +2571,15 @@ </glossentry> <glossentry id='var-DEFAULT_PREFERENCE'><glossterm>DEFAULT_PREFERENCE</glossterm> + <info> + DEFAULT_PREFERENCE[doc] = "Specifies a weak bias for recipe selection priority." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies a weak bias for recipe selection priority. </para> + <para> The most common usage of this is variable is to set it to "-1" within a recipe for a development version of a @@ -1813,6 +2589,7 @@ <filename><link linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></filename> being used to build the development version. </para> + <note> The bias provided by <filename>DEFAULT_PREFERENCE</filename> is weak and is overridden by @@ -1824,8 +2601,12 @@ </glossentry> <glossentry id='var-DEFAULTTUNE'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The default CPU and Application Binary Interface (ABI) tunings (i.e. the "tune") used by the OpenEmbedded build system. @@ -1845,8 +2626,12 @@ </glossentry> <glossentry id='var-DEPENDS'><glossterm>DEPENDS</glossterm> + <info> + DEPENDS[doc] = "Lists a recipe's build-time dependencies (i.e. other recipe files)." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Lists a recipe's build-time dependencies (i.e. other recipe files). The system ensures that all the dependencies listed @@ -1880,8 +2665,12 @@ </glossentry> <glossentry id='var-DEPLOY_DIR'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> 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. @@ -1897,16 +2686,62 @@ section. For more detail on the contents of the <filename>deploy</filename> directory, see the - "<link linkend='images-dev-environment'>Images</link>" and + "<link linkend='images-dev-environment'>Images</link>", + "<link linkend='package-feeds-dev-environment'>Package Feeds</link>", + and "<link linkend='sdk-dev-environment'>Application Development SDK</link>" sections. </para> </glossdef> </glossentry> - <glossentry id='var-DEPLOY_DIR_IMAGE'><glossterm>DEPLOY_DIR_IMAGE</glossterm> + <glossentry id='var-DEPLOY_DIR_DEB'><glossterm>DEPLOY_DIR_DEB</glossterm> + <info> + DEPLOY_DIR_DEB[doc] = "Points to a Debian-specific 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 role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Points to the area that the OpenEmbedded build system uses + to place Debian packages that are ready to be used outside + of the build system. + This variable applies only when + <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link> + contains "package_deb". + </para> + <para> + The BitBake configuration file initially defines the + <filename>DEPLOY_DIR_DEB</filename> variable as a + sub-folder of + <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>: + <literallayout class='monospaced'> + DEPLOY_DIR_DEB = "${DEPLOY_DIR}/deb" + </literallayout> + </para> + + <para> + The + <link linkend='ref-classes-package_deb'><filename>package_deb</filename></link> + class uses the + <filename>DEPLOY_DIR_DEB</filename> variable to make sure + the + <link linkend='ref-tasks-package_write_deb'><filename>do_package_write_deb</filename></link> + task writes Debian packages into the appropriate folder. + For more information on how packaging works, see the + "<link linkend='package-feeds-dev-environment'>Package Feeds</link>" + section. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-DEPLOY_DIR_IMAGE'><glossterm>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 role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> 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. @@ -1931,9 +2766,130 @@ </glossdef> </glossentry> - <glossentry id='var-DEPLOYDIR'><glossterm>DEPLOYDIR</glossterm> + <glossentry id='var-DEPLOY_DIR_IPK'><glossterm>DEPLOY_DIR_IPK</glossterm> + <info> + DEPLOY_DIR_IPK[doc] = "Points to a IPK-specific 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 role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Points to the area that the OpenEmbedded build system uses + to place IPK packages that are ready to be used outside of + the build system. + This variable applies only when + <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link> + contains "package_ipk". + </para> + + <para> + The BitBake configuration file initially defines this + variable as a sub-folder of + <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>: + <literallayout class='monospaced'> + DEPLOY_DIR_IPK = "${DEPLOY_DIR}/ipk" + </literallayout> + </para> + <para> + The + <link linkend='ref-classes-package_ipk'><filename>package_ipk</filename></link> + class uses the + <filename>DEPLOY_DIR_IPK</filename> variable to make sure + the + <link linkend='ref-tasks-package_write_ipk'><filename>do_package_write_ipk</filename></link> + task writes IPK packages into the appropriate folder. + For more information on how packaging works, see the + "<link linkend='package-feeds-dev-environment'>Package Feeds</link>" + section. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-DEPLOY_DIR_RPM'><glossterm>DEPLOY_DIR_RPM</glossterm> + <info> + DEPLOY_DIR_RPM[doc] = "Points to a RPM-specific 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 role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Points to the area that the OpenEmbedded build system uses + to place RPM packages that are ready to be used outside + of the build system. + This variable applies only when + <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link> + contains "package_rpm". + </para> + + <para> + The BitBake configuration file initially defines this + variable as a sub-folder of + <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>: + <literallayout class='monospaced'> + DEPLOY_DIR_RPM = "${DEPLOY_DIR}/rpm" + </literallayout> + </para> + + <para> + The + <link linkend='ref-classes-package_rpm'><filename>package_rpm</filename></link> + class uses the + <filename>DEPLOY_DIR_RPM</filename> variable to make sure + the + <link linkend='ref-tasks-package_write_rpm'><filename>do_package_write_rpm</filename></link> + task writes RPM packages into the appropriate folder. + For more information on how packaging works, see the + "<link linkend='package-feeds-dev-environment'>Package Feeds</link>" + section. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-DEPLOY_DIR_TAR'><glossterm>DEPLOY_DIR_TAR</glossterm> + <info> + DEPLOY_DIR_TAR[doc] = "Points to a tarball 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 role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Points to the area that the OpenEmbedded build system uses + to place tarballs that are ready to be used outside of + the build system. + This variable applies only when + <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link> + contains "package_tar". + </para> + + <para> + The BitBake configuration file initially defines this + variable as a sub-folder of + <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>: + <literallayout class='monospaced'> + DEPLOY_DIR_TAR = "${DEPLOY_DIR}/tar" + </literallayout> + </para> + + <para> + The + <link linkend='ref-classes-package_tar'><filename>package_tar</filename></link> + class uses the + <filename>DEPLOY_DIR_TAR</filename> variable to make sure + the + <link linkend='ref-tasks-package_write_tar'><filename>do_package_write_tar</filename></link> + task writes TAR packages into the appropriate folder. + For more information on how packaging works, see the + "<link linkend='package-feeds-dev-environment'>Package Feeds</link>" + section. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-DEPLOYDIR'><glossterm>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 role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> When inheriting the <link linkend='ref-classes-deploy'><filename>deploy</filename></link> class, the <filename>DEPLOYDIR</filename> points to a @@ -1942,6 +2898,9 @@ <literallayout class='monospaced'> DEPLOYDIR = "${WORKDIR}/deploy-${<link linkend='var-PN'><filename>PN</filename></link>}" </literallayout> + </para> + + <para> Recipes inheriting the <filename>deploy</filename> class should copy files to be deployed into <filename>DEPLOYDIR</filename>, and the class will take @@ -1953,19 +2912,28 @@ </glossentry> <glossentry id='var-DESCRIPTION'><glossterm>DESCRIPTION</glossterm> - <glossdef> - <para>The package description used by package managers. - If not set, <filename>DESCRIPTION</filename> takes - the value of the - <link linkend='var-SUMMARY'><filename>SUMMARY</filename></link> - variable. + <info> + DESCRIPTION[doc] = "The package description used by package managers. If not set, DESCRIPTION takes the value of the SUMMARY variable." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + The package description used by package managers. + If not set, <filename>DESCRIPTION</filename> takes + the value of the + <link linkend='var-SUMMARY'><filename>SUMMARY</filename></link> + variable. </para> </glossdef> </glossentry> <glossentry id='var-DISK_SIGNATURE'><glossterm>DISK_SIGNATURE</glossterm> + <info> + DISK_SIGNATURE[doc] = "A 32-bit MBR disk signature used by directdisk images." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> A 32-bit MBR disk signature used by <filename>directdisk</filename> images. </para> @@ -2014,8 +2982,12 @@ </glossentry> <glossentry id='var-DISTRO'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The short name of the distribution. This variable corresponds to a distribution configuration file whose root name is the same as the @@ -2055,9 +3027,25 @@ </glossdef> </glossentry> + <glossentry id='var-DISTRO_CODENAME'><glossterm>DISTRO_CODENAME</glossterm> + <info> + DISTRO_CODENAME[doc] = "Specifies a codename for the distribution being built." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Specifies a codename for the distribution being built. + </para> + </glossdef> + </glossentry> + <glossentry id='var-DISTRO_EXTRA_RDEPENDS'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies a list of distro-specific packages to add to all images. This variable takes affect through <filename>packagegroup-base</filename> so the @@ -2072,8 +3060,12 @@ </glossentry> <glossentry id='var-DISTRO_EXTRA_RRECOMMENDS'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies a list of distro-specific packages to add to all images if the packages exist. The packages might not exist or be empty (e.g. kernel modules). @@ -2084,8 +3076,12 @@ </glossentry> <glossentry id='var-DISTRO_FEATURES'><glossterm>DISTRO_FEATURES</glossterm> + <info> + DISTRO_FEATURES[doc] = "The features enabled for the distribution." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The software support you want in your distribution for various features. You define your distribution features in the distribution @@ -2117,8 +3113,13 @@ </glossentry> <glossentry id='var-DISTRO_FEATURES_BACKFILL'><glossterm>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 + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Features to be added to <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename> if not also present in <filename><link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'>DISTRO_FEATURES_BACKFILL_CONSIDERED</link></filename>. @@ -2136,43 +3137,99 @@ </glossentry> <glossentry id='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><glossterm>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 + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Features from <filename><link linkend='var-DISTRO_FEATURES_BACKFILL'>DISTRO_FEATURES_BACKFILL</link></filename> that should not be backfilled (i.e. added to <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>) during the build. See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for more information. - </para> + </para> </glossdef> </glossentry> - <glossentry id='var-DISTRO_NAME'><glossterm>DISTRO_NAME</glossterm> + <glossentry id='var-DISTRO_FEATURES_DEFAULT'><glossterm>DISTRO_FEATURES_DEFAULT</glossterm> + <info> + DISTRO_FEATURES_DEFAULT[doc] = "Provides the default list of distro features with the exception of any libc-specific features." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + A convenience variable that gives you the default + list of distro features with the exception of any + features specific to the C library + (<filename>libc</filename>). + </para> + + <para> + When creating a custom distribution, you might find it + useful to be able to reuse the default + <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link> + options without the need to write out the full set. + Here is an example that uses + <filename>DISTRO_FEATURES_DEFAULT</filename> from a + custom distro configuration file: + <literallayout class='monospaced'> + DISTRO_FEATURES ?= "${DISTRO_FEATURES_DEFAULT} ${DISTRO_FEATURES_LIBC} myfeature" + </literallayout> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-DISTRO_FEATURES_LIBC'><glossterm>DISTRO_FEATURES_LIBC</glossterm> + <info> + DISTRO_FEATURES_LIBC[doc] = "Specifies the list of distro features that are specific to the C library (libc)." + </info> <glossdef> - <para>The long name of the distribution.</para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + A convenience variable that specifies the list of distro + features that are specific to the C library + (<filename>libc</filename>). + Typically, these features are prefixed with "libc-" and + control which features are enabled at during the build + within the C library itself. + </para> </glossdef> </glossentry> - <glossentry id='var-DISTRO_PN_ALIAS'><glossterm>DISTRO_PN_ALIAS</glossterm> + <glossentry id='var-DISTRO_NAME'><glossterm>DISTRO_NAME</glossterm> + <info> + DISTRO_NAME[doc] = "The long name of the distribution." + </info> <glossdef> - <para>Alias names used for the recipe in various Linux distributions.</para> - <para>See the - "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-configuring-DISTRO_PN_ALIAS'>Handling - a Package Name Alias</ulink>" section in the Yocto Project Development - Manual for more information.</para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + The long name of the distribution. + </para> </glossdef> </glossentry> <glossentry id='var-DISTRO_VERSION'><glossterm>DISTRO_VERSION</glossterm> + <info> + DISTRO_VERSION[doc] = "The version of the distribution." + </info> <glossdef> - <para>The version of the distribution.</para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + The version of the distribution. + </para> </glossdef> </glossentry> <glossentry id='var-DISTROOVERRIDES'><glossterm>DISTROOVERRIDES</glossterm> + <info> + DISTROOVERRIDES[doc] = "Lists overrides specific to the current distribution. By default, the variable list includes the value of the DISTRO variable." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> This variable lists overrides specific to the current distribution. By default, the variable list includes the value of the @@ -2187,8 +3244,12 @@ </glossentry> <glossentry id='var-DL_DIR'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The central download directory used by the build process to store downloads. By default, <filename>DL_DIR</filename> gets files @@ -2243,8 +3304,12 @@ </glossentry> <glossentry id='var-DOC_COMPRESS'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> When inheriting the <link linkend='ref-classes-compress_doc'><filename>compress_doc</filename></link> class, this variable sets the compression policy used when @@ -2267,13 +3332,17 @@ <glossdiv id='var-glossary-e'><title>E</title> <glossentry id='var-EFI_PROVIDER'><glossterm>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 role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> 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 <filename>EFI_PROVIDER</filename> variable specifies the EFI bootloader to use. The default is "grub-efi", but "gummiboot" can be used instead. @@ -2288,32 +3357,27 @@ </glossentry> <glossentry id='var-ENABLE_BINARY_LOCALE_GENERATION'><glossterm>ENABLE_BINARY_LOCALE_GENERATION</glossterm> - <glossdef> - <para>Variable that controls which locales for - <filename>eglibc</filename> are generated during the + <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 role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Variable that controls which locales for + <filename>glibc</filename> are generated during the build (useful if the target device has 64Mbytes - of RAM or less).</para> - </glossdef> - </glossentry> - - <glossentry id='var-ERROR_QA'><glossterm>ERROR_QA</glossterm> - <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. + of RAM or less). </para> </glossdef> </glossentry> <glossentry id='var-ERR_REPORT_DIR'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> When used with the <link linkend='ref-classes-report-error'><filename>report-error</filename></link> class, specifies the path used for storing the debug files @@ -2336,9 +3400,32 @@ </glossdef> </glossentry> + <glossentry id='var-ERROR_QA'><glossterm>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 role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + 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>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Directs BitBake to exclude a recipe from world builds (i.e. <filename>bitbake world</filename>). During world builds, BitBake locates, parses and builds all @@ -2363,8 +3450,12 @@ </glossentry> <glossentry id='var-EXTENDPE'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Used with file and pathnames to create a prefix for a recipe's version based on the recipe's <link linkend='var-PE'><filename>PE</filename></link> value. @@ -2381,8 +3472,12 @@ </glossentry> <glossentry id='var-EXTENDPKGV'><glossterm>EXTENDPKGV</glossterm> + <info> + EXTENDPKGV[doc] = "The full package version specification as it appears on the final packages produced by a recipe." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The full package version specification as it appears on the final packages produced by a recipe. The variable's value is normally used to fix a runtime @@ -2401,9 +3496,39 @@ </glossdef> </glossentry> - <glossentry id='var-EXTERNALSRC'><glossterm>EXTERNALSRC</glossterm> + <glossentry id='var-EXTERNAL_KERNEL_TOOLS'><glossterm>EXTERNAL_KERNEL_TOOLS</glossterm> + <info> + EXTERNAL_KERNEL_TOOLS[doc] = "Indicates kernel tools are external to the source tree." + </info> <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + When set, the <filename>EXTERNAL_KERNEL_TOOLS</filename> + variable indicates that these tools are not in the + source tree. + </para> + <para> + When kernel tools are available in the tree, they are + preferred over any externally installed tools. + Setting the <filename>EXTERNAL_KERNEL_TOOLS</filename> + variable tells the OpenEmbedded build system to prefer + the installed external tools. + See the + <link linkend='ref-classes-kernel-yocto'><filename>kernel-yocto</filename></link> + class in <filename>meta/classes</filename> to see how + the variable is used. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-EXTERNALSRC'><glossterm>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 role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> When inheriting the <link linkend='ref-classes-externalsrc'><filename>externalsrc</filename></link> class, this variable points to the source tree, which is @@ -2428,8 +3553,12 @@ </glossentry> <glossentry id='var-EXTERNALSRC_BUILD'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> When inheriting the <link linkend='ref-classes-externalsrc'><filename>externalsrc</filename></link> class, this variable points to the directory in which the @@ -2454,9 +3583,36 @@ </glossdef> </glossentry> - <glossentry id='var-EXTRA_IMAGE_FEATURES'><glossterm>EXTRA_IMAGE_FEATURES</glossterm> + <glossentry id='var-EXTRA_AUTORECONF'><glossterm>EXTRA_AUTORECONF</glossterm> + <info> + EXTRA_AUTORECONF[doc] = "Extra options passed to the autoreconf command, which is executed during do_configure." + </info> <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + For recipes inheriting the + <link linkend='ref-classes-autotools'><filename>autotools</filename></link> + class, you can use <filename>EXTRA_AUTORECONF</filename> to + specify extra options to pass to the + <filename>autoreconf</filename> command that is + executed during the + <link linkend='ref-tasks-configure'><filename>do_configure</filename></link> + task. + </para> + <para> + The default value is "--exclude=autopoint". + </para> + </glossdef> + </glossentry> + + <glossentry id='var-EXTRA_IMAGE_FEATURES'><glossterm>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 role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The list of additional features to include in an image. Typically, you configure this variable in your <filename>local.conf</filename> file, which is found in the @@ -2478,10 +3634,13 @@ including symbol information for debugging and profiling. -"debug-tweaks" - Makes an image suitable for development. - For example, ssh root access has a blank - password. You should remove this feature - before you produce a production image. +"debug-tweaks" - Makes an image suitable for debugging. + For example, allows root logins without + passwords and enables post-installation + logging. See the 'allow-empty-password' + and 'post-install-logging' features in + the "<link linkend='ref-features-image'>Image Features</link>" section for + more information. "dev-pkgs" - Adds -dev packages for all installed packages. This is useful if you want to develop against @@ -2527,8 +3686,12 @@ </glossentry> <glossentry id='var-EXTRA_IMAGECMD'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies additional options for the image creation command that has been specified in <link linkend='var-IMAGE_CMD'><filename>IMAGE_CMD</filename></link>. @@ -2543,16 +3706,24 @@ </glossentry> <glossentry id='var-EXTRA_IMAGEDEPENDS'><glossterm>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 + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + A list of recipes to build that do not provide packages for installing into the root filesystem. </para> - <para>Sometimes a recipe is required to build the final image but is not + + <para> + Sometimes a recipe is required to build the final image but is not needed in the root filesystem. You can use the <filename>EXTRA_IMAGEDEPENDS</filename> variable to list these recipes and thus specify the dependencies. A typical example is a required bootloader in a machine configuration. </para> + <note> To add packages to the root filesystem, see the various <filename>*<link linkend='var-RDEPENDS'>RDEPENDS</link></filename> @@ -2563,26 +3734,48 @@ </glossentry> <glossentry id='var-EXTRA_OECMAKE'><glossterm>EXTRA_OECMAKE</glossterm> + <info> + EXTRA_OECMAKE[doc] = "Additional cmake options." + </info> <glossdef> - <para>Additional <filename>cmake</filename> options.</para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Additional <filename>cmake</filename> options. + </para> </glossdef> </glossentry> <glossentry id='var-EXTRA_OECONF'><glossterm>EXTRA_OECONF</glossterm> + <info> + EXTRA_OECONF[doc] = "Additional configure script options." + </info> <glossdef> - <para>Additional <filename>configure</filename> script options.</para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Additional <filename>configure</filename> script options. + </para> </glossdef> </glossentry> <glossentry id='var-EXTRA_OEMAKE'><glossterm>EXTRA_OEMAKE</glossterm> + <info> + EXTRA_OEMAKE[doc] = "Additional GNU make options." + </info> <glossdef> - <para>Additional GNU <filename>make</filename> options.</para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Additional GNU <filename>make</filename> options. + </para> </glossdef> </glossentry> <glossentry id='var-EXTRA_OESCONS'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> When inheriting the <link linkend='ref-classes-scons'><filename>scons</filename></link> class, this variable specifies additional configuration @@ -2593,8 +3786,12 @@ </glossentry> <glossentry id='var-EXTRA_QMAKEVARS_POST'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Configuration variables or options you want to pass to <filename>qmake</filename>. Use this variable when the arguments need to be after the @@ -2611,8 +3808,12 @@ </glossentry> <glossentry id='var-EXTRA_QMAKEVARS_PRE'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Configuration variables or options you want to pass to <filename>qmake</filename>. Use this variable when the arguments need to be before the @@ -2629,8 +3830,12 @@ </glossentry> <glossentry id='var-EXTRA_USERS_PARAMS'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> When inheriting the <link linkend='ref-classes-extrausers'><filename>extrausers</filename></link> class, this variable provides image level user and group @@ -2667,8 +3872,12 @@ <glossdiv id='var-glossary-f'><title>F</title> <glossentry id='var-FEATURE_PACKAGES'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Defines one or more packages to include in an image when a specific item is included in <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>. @@ -2678,6 +3887,9 @@ <literallayout class='monospaced'> FEATURE_PACKAGES_widget = "<replaceable>package1</replaceable> <replaceable>package2</replaceable>" </literallayout> + </para> + + <para> In this example, if "widget" were added to <filename>IMAGE_FEATURES</filename>, <replaceable>package1</replaceable> and <replaceable>package2</replaceable> would be included in the image. @@ -2695,8 +3907,12 @@ </glossentry> <glossentry id='var-FEED_DEPLOYDIR_BASE_URI'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Points to the base URL of the server and location within the document-root that provides the metadata and packages required by OPKG to support runtime package @@ -2722,8 +3938,12 @@ </glossentry> <glossentry id='var-FILES'><glossterm>FILES</glossterm> + <info> + FILES[doc] = "The list of directories or files that are placed in packages." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The list of directories or files that are placed in packages. </para> @@ -2768,9 +3988,37 @@ </glossdef> </glossentry> - <glossentry id='var-FILESEXTRAPATHS'><glossterm>FILESEXTRAPATHS</glossterm> + <glossentry id='var-FILES_SOLIBSDEV'><glossterm>FILES_SOLIBSDEV</glossterm> + <info> + FILES_SOLIBSDEV[doc] = "Defines the full path name of the development symbolic link (symlink) for shared libraries on the target platform." + </info> <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Defines the file specification to match + <link linkend='var-SOLIBSDEV'><filename>SOLIBSDEV</filename></link>. + In other words, <filename>FILES_SOLIBSDEV</filename> + defines the full path name of the development symbolic link + (symlink) for shared libraries on the target platform. + </para> + <para> + The following statement from the + <filename>bitbake.conf</filename> shows how it is set: + <literallayout class='monospaced'> + FILES_SOLIBSDEV ?= "${base_libdir}/lib*${SOLIBSDEV} ${libdir}/lib*${SOLIBSDEV}" + </literallayout> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-FILESEXTRAPATHS'><glossterm>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 role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Extends the search path the OpenEmbedded build system uses when looking for files and patches as it processes recipes and append files. @@ -2836,8 +4084,12 @@ </glossentry> <glossentry id='var-FILESOVERRIDES'><glossterm>FILESOVERRIDES</glossterm> + <info> + FILESOVERRIDES[doc] = "A subset of OVERRIDES used by the OpenEmbedded build system for creating FILESPATH." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> 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>. @@ -2864,8 +4116,12 @@ </glossentry> <glossentry id='var-FILESPATH'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The default set of directories the OpenEmbedded build system uses when searching for patches and files. During the build process, BitBake searches each directory in @@ -2907,14 +4163,20 @@ </glossentry> <glossentry id='var-FILESYSTEM_PERMS_TABLES'><glossterm>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 + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Allows you to define your own file permissions settings table as part of your configuration for the packaging process. For example, suppose you need a consistent set of custom permissions for a set of groups and users across an entire work project. It is best to do this in the packages themselves but this is not always possible. </para> + <para> By default, the OpenEmbedded build system uses the <filename>fs-perms.txt</filename>, which is located in the <filename>meta/files</filename> folder in the @@ -2922,6 +4184,7 @@ If you create your own file permissions setting table, you should place it in your layer or the distro's layer. </para> + <para> You define the <filename>FILESYSTEM_PERMS_TABLES</filename> variable in the <filename>conf/local.conf</filename> file, which is found in the @@ -2931,6 +4194,7 @@ The paths you specify to these files must be defined within the <link linkend='var-BBPATH'><filename>BBPATH</filename></link> variable. </para> + <para> For guidance on how to create your own file permissions settings table file, examine the existing <filename>fs-perms.txt</filename>. @@ -2938,9 +4202,30 @@ </glossdef> </glossentry> + <glossentry id='var-FONT_EXTRA_RDEPENDS'><glossterm>FONT_EXTRA_RDEPENDS</glossterm> + <info> + FONT_EXTRA_RDEPENDS[doc] = "When a recipe inherits the fontcache class, this variable specifies runtime dependencies for font packages. This variable defaults to 'fontconfig-utils'." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + When inheriting the + <link linkend='ref-classes-fontcache'><filename>fontcache</filename></link> + class, this variable specifies the runtime dependencies + for font packages. + By default, the <filename>FONT_EXTRA_RDEPENDS</filename> + is set to "fontconfig-utils". + </para> + </glossdef> + </glossentry> + <glossentry id='var-FONT_PACKAGES'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> When inheriting the <link linkend='ref-classes-fontcache'><filename>fontcache</filename></link> class, this variable identifies packages containing font @@ -2955,8 +4240,12 @@ </glossentry> <glossentry id='var-FULL_OPTIMIZATION'><glossterm>FULL_OPTIMIZATION</glossterm> + <info> + FULL_OPTIMIZATION[doc]= "The options to pass in TARGET_CFLAGS and CFLAGS when compiling an optimized system. This variable defaults to '-fexpensive-optimizations -fomit-frame-pointer -frename-registers -O2'." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The options to pass in <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename> and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename> @@ -2970,9 +4259,38 @@ <glossdiv id='var-glossary-g'><title>G</title> + <glossentry id='var-GDB'><glossterm>GDB</glossterm> + <info> + GDB[doc] = "The minimal command and arguments to run the GNU Debugger." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + The minimal command and arguments to run the GNU Debugger. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-GITDIR'><glossterm>GITDIR</glossterm> + <info> + GITDIR[doc] = "The directory where Git clones will be stored." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + The directory in which a local copy of a Git repository + is stored when it is cloned. + </para> + </glossdef> + </glossentry> + <glossentry id='var-GLIBC_GENERATE_LOCALES'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the list of GLIBC locales to generate should you not wish generate all LIBC locals, which can be time consuming. @@ -2982,6 +4300,9 @@ <link linkend='var-IMAGE_LINGUAS'><filename>IMAGE_LINGUAS</filename></link> appropriately. </note> + </para> + + <para> You can set <filename>GLIBC_GENERATE_LOCALES</filename> in your <filename>local.conf</filename> file. By default, all locales are generated. @@ -2993,8 +4314,12 @@ </glossentry> <glossentry id='var-GROUPADD_PARAM'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> When inheriting the <link linkend='ref-classes-useradd'><filename>useradd</filename></link> class, this variable @@ -3018,8 +4343,12 @@ </glossentry> <glossentry id='var-GROUPMEMS_PARAM'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> When inheriting the <link linkend='ref-classes-useradd'><filename>useradd</filename></link> class, this variable @@ -3038,8 +4367,12 @@ </glossentry> <glossentry id='var-GRUB_GFXSERIAL'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Configures the GNU GRand Unified Bootloader (GRUB) to have graphics and serial in the boot menu. Set this variable to "1" in your @@ -3057,8 +4390,12 @@ </glossentry> <glossentry id='var-GRUB_OPTS'><glossterm>GRUB_OPTS</glossterm> + <info> + GRUB_OPTS[doc] = "Additional options to add to the GNU GRand Unified Bootloader (GRUB) configuration." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Additional options to add to the GNU GRand Unified Bootloader (GRUB) configuration. Use a semi-colon character (<filename>;</filename>) to @@ -3075,8 +4412,12 @@ </glossentry> <glossentry id='var-GRUB_TIMEOUT'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the timeout before executing the default <filename>LABEL</filename> in the GNU GRand Unified Bootloader (GRUB). @@ -3092,8 +4433,12 @@ </glossentry> <glossentry id='var-GTKIMMODULES_PACKAGES'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> 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 @@ -3104,8 +4449,12 @@ </glossentry> <glossentry id='var-GUMMIBOOT_CFG'><glossterm>GUMMIBOOT_CFG</glossterm> + <info> + GUMMIBOOT_CFG[doc] = "When EFI_PROVIDER is set to "gummiboot", the GUMMIBOOT_CFG variable specifies the configuration file that should be used." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> When <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link> is set to "gummiboot", the @@ -3128,8 +4477,12 @@ </glossentry> <glossentry id='var-GUMMIBOOT_ENTRIES'><glossterm>GUMMIBOOT_ENTRIES</glossterm> + <info> + GUMMIBOOT_ENTRIES[doc] = "When EFI_PROVIDER is set to "gummiboot", the GUMMIBOOT_ENTRIES variable specifies a list of entry files (*.conf) to be installed containing one boot entry per file." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> When <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link> is set to "gummiboot", the @@ -3154,8 +4507,12 @@ </glossentry> <glossentry id='var-GUMMIBOOT_TIMEOUT'><glossterm>GUMMIBOOT_TIMEOUT</glossterm> + <info> + GUMMIBOOT_TIMEOUT[doc] = "When EFI_PROVIDER is set to "gummiboot", the GUMMIBOOT_TIMEOUT variable specifies the boot menu timeout in seconds." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> When <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link> is set to "gummiboot", the @@ -3182,15 +4539,54 @@ <glossdiv id='var-glossary-h'><title>H</title> <glossentry id='var-HOMEPAGE'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Website where more information about the software the recipe is building + can be found. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-HOST_ARCH'><glossterm>HOST_ARCH</glossterm> + <info> + HOST_ARCH[doc] = "The name of the target architecture. Normally same as the TARGET_ARCH." + + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + The name of the target architecture, which is normally + the same as + <link linkend='var-TARGET_ARCH'><filename>TARGET_ARCH</filename></link>. + The OpenEmbedded build system supports many + architectures. + Here is an example list of architectures supported. + This list is by no means complete as the architecture + is configurable: + <literallayout class='monospaced'> + arm + i586 + x86_64 + powerpc + powerpc64 + mips + mipsel + </literallayout> + </para> </glossdef> </glossentry> <glossentry id='var-HOST_CC_ARCH'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies architecture-specific compiler flags that are passed to the C compiler. </para> @@ -3218,20 +4614,65 @@ </glossdef> </glossentry> + <glossentry id='var-HOST_OS'><glossterm>HOST_OS</glossterm> + <info> + HOST_OS[doc] = "The name of the target operating system. Normally the same as the TARGET_OS." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Specifies the name of the target operating system, which + is normally the same as the + <link linkend='var-TARGET_OS'><filename>TARGET_OS</filename></link>. + The variable can be set to "linux" for <filename>glibc</filename>-based systems and + to "linux-uclibc" for <filename>uclibc</filename>. + For ARM/EABI targets, there are also "linux-gnueabi" and + "linux-uclibc-gnueabi" values possible. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-HOST_PREFIX'><glossterm>HOST_PREFIX</glossterm> + <info> + HOST_PREFIX[doc] = "The prefix for the cross compile toolchain. Normally same as the TARGET_PREFIX." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Specifies the prefix for the cross-compile toolchain. + <filename>HOST_PREFIX</filename> is normally the same as + <link linkend='var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></link>. + </para> + </glossdef> + </glossentry> + <glossentry id='var-HOST_SYS'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the system, including the architecture and the - operating system, for with the build is occurring - in the context of the current - recipe. + operating system, for which the build is occurring + in the context of the current recipe. + </para> + + <para> The OpenEmbedded build system automatically sets this - variable. - You do not need to set the variable yourself. + variable based on + <link linkend='var-HOST_ARCH'><filename>HOST_ARCH</filename></link>, + <link linkend='var-HOST_VENDOR'><filename>HOST_VENDOR</filename></link>, + and + <link linkend='var-HOST_OS'><filename>HOST_OS</filename></link> + variables. + <note> + You do not need to set the variable yourself. + </note> </para> <para> - Here are two examples: + Consider these two examples: <itemizedlist> <listitem><para>Given a native recipe on a 32-bit x86 machine running Linux, the value is @@ -3246,13 +4687,31 @@ </glossdef> </glossentry> + <glossentry id='var-HOST_VENDOR'><glossterm>HOST_VENDOR</glossterm> + <info> + HOST_VENDOR[doc] = "The name of the vendor. Normally same as the TARGET_VENDOR." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Specifies the name of the vendor. + <filename>HOST_VENDOR</filename> is normally the same as + <link linkend='var-TARGET_PREFIX'><filename>TARGET_VENDOR</filename></link>. + </para> + </glossdef> + </glossentry> + </glossdiv> <glossdiv id='var-glossary-i'><title>I</title> <glossentry id='var-ICECC_DISABLED'><glossterm>ICECC_DISABLED</glossterm> + <info> + ICECC_DISABLED[doc] = "Disables or enables the icecc (Icecream) function." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Disables or enables the <filename>icecc</filename> (Icecream) function. For more information on this function and best practices @@ -3276,8 +4735,12 @@ </glossentry> <glossentry id='var-ICECC_ENV_EXEC'><glossterm>ICECC_ENV_EXEC</glossterm> + <info> + ICECC_ENV_EXEC[doc] = "Points to the icecc-create-env script that you provide." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Points to the <filename>icecc-create-env</filename> script that you provide. This variable is used by the @@ -3298,8 +4761,12 @@ </glossentry> <glossentry id='var-ICECC_PARALLEL_MAKE'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Extra options passed to the <filename>make</filename> command during the <link linkend='ref-tasks-compile'><filename>do_compile</filename></link> @@ -3339,8 +4806,12 @@ </glossentry> <glossentry id='var-ICECC_PATH'><glossterm>ICECC_PATH</glossterm> + <info> + ICECC_PATH[doc] = "The location of the icecc binary." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The location of the <filename>icecc</filename> binary. You can set this variable in your <filename>local.conf</filename> file. @@ -3354,8 +4825,12 @@ </glossentry> <glossentry id='var-ICECC_USER_CLASS_BL'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Identifies user classes that you do not want the Icecream distributed compile support to consider. This variable is used by the @@ -3376,8 +4851,12 @@ </glossentry> <glossentry id='var-ICECC_USER_PACKAGE_BL'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Identifies user recipes that you do not want the Icecream distributed compile support to consider. This variable is used by the @@ -3398,8 +4877,12 @@ </glossentry> <glossentry id='var-ICECC_USER_PACKAGE_WL'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Identifies user recipes that use an empty <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link> variable that you want to force remote distributed @@ -3415,8 +4898,12 @@ </glossentry> <glossentry id='var-IMAGE_BASENAME'><glossterm>IMAGE_BASENAME</glossterm> + <info> + IMAGE_BASENAME[doc] = "The base name of image output files." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The base name of image output files. This variable defaults to the recipe name (<filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>). @@ -3425,12 +4912,19 @@ </glossentry> <glossentry id='var-IMAGE_BOOT_FILES'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> A space-separated list of files installed into the - boot partition when preparing an image. - By default, the files are installed under the same name as - the source files. + 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 @@ -3440,13 +4934,40 @@ <literallayout class="monospaced"> IMAGE_BOOT_FILES = "u-boot.img uImage;kernel" IMAGE_BOOT_FILES = "u-boot.${UBOOT_SUFFIX} ${KERNEL_IMAGETYPE}" - </literallayout></para> + </literallayout> + </para> + + <para> + 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>IMAGE_CLASSES</glossterm> + <info> + IMAGE_CLASSES[doc] = "A list of classes that all images should inherit." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> A list of classes that all images should inherit. You typically use this variable to specify the list of classes that register the different types of images @@ -3470,8 +4991,12 @@ </glossentry> <glossentry id='var-IMAGE_CMD'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the command to create the image file for a specific image type, which corresponds to the value set set in @@ -3486,6 +5011,9 @@ --faketime --output=${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.jffs2 \ ${EXTRA_IMAGECMD}" </literallayout> + </para> + + <para> You typically do not need to set this variable unless you are adding support for a new image type. For more examples on how to set this variable, see the @@ -3497,8 +5025,12 @@ </glossentry> <glossentry id='var-IMAGE_DEVICE_TABLES'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies one or more files that contain custom device tables that are passed to the <filename>makedevs</filename> command as part of creating @@ -3517,8 +5049,12 @@ </glossentry> <glossentry id='var-IMAGE_FEATURES'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The primary list of features to include in an image. Typically, you configure this variable in an image recipe. Although you can use this variable from your @@ -3530,6 +5066,9 @@ use the <filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename> variable. </note> + </para> + + <para> For a list of image features that ships with the Yocto Project, see the "<link linkend="ref-features-image">Image Features</link>" @@ -3546,8 +5085,12 @@ </glossentry> <glossentry id='var-IMAGE_FSTYPES'><glossterm>IMAGE_FSTYPES</glossterm> + <info> + IMAGE_FSTYPES[doc] = "Formats of root filesystem images that you want to have created." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the formats the OpenEmbedded build system uses during the build when creating the root filesystem. For example, setting <filename>IMAGE_FSTYPES</filename> @@ -3557,6 +5100,9 @@ <literallayout class='monospaced'> IMAGE_FSTYPES = "ext3 tar.bz2" </literallayout> + </para> + + <para> For the complete list of supported image formats from which you can choose, see <link linkend='var-IMAGE_TYPES'><filename>IMAGE_TYPES</filename></link>. @@ -3581,8 +5127,12 @@ </glossentry> <glossentry id='var-IMAGE_INSTALL'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the packages to install into an image. The <filename>IMAGE_INSTALL</filename> variable is a mechanism for an image recipe and you should use it @@ -3644,8 +5194,12 @@ </glossentry> <glossentry id='var-IMAGE_LINGUAS'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the list of locales to install into the image during the root filesystem construction process. The OpenEmbedded build system automatically splits locale @@ -3659,6 +5213,9 @@ <literallayout class='monospaced'> IMAGE_LINGUAS = "pt-br de-de" </literallayout> + </para> + + <para> In this example, the build system ensures any Brazilian Portuguese and German locale files that correspond to packages in the image are installed (i.e. @@ -3679,8 +5236,12 @@ </glossentry> <glossentry id='var-IMAGE_MANIFEST'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The manifest file for the image. This file lists all the installed packages that make up the image. @@ -3712,8 +5273,12 @@ </glossentry> <glossentry id='var-IMAGE_NAME'><glossterm>IMAGE_NAME</glossterm> + <info> + IMAGE_NAME[doc] = "The name of the output image files minus the extension." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The name of the output image files minus the extension. This variable is derived using the <link linkend='var-IMAGE_BASENAME'><filename>IMAGE_BASENAME</filename></link>, @@ -3729,8 +5294,12 @@ </glossentry> <glossentry id='var-IMAGE_OVERHEAD_FACTOR'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> 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 @@ -3771,8 +5340,12 @@ </glossentry> <glossentry id='var-IMAGE_PKGTYPE'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Defines the package type (DEB, RPM, IPK, or TAR) used by the OpenEmbedded build system. The variable is defined appropriately by the @@ -3782,6 +5355,11 @@ or <link linkend='ref-classes-package_tar'><filename>package_tar</filename></link> class. + <note><title>Warning</title> + The <filename>package_tar</filename> class is broken + and is not supported. + It is recommended that you do not use it. + </note> </para> <para> @@ -3814,14 +5392,21 @@ </glossentry> <glossentry id='var-IMAGE_POSTPROCESS_COMMAND'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> 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 += "<replaceable>shell_command</replaceable>; ... " </literallayout> + </para> + + <para> If you need to pass the path to the root filesystem within the command, you can use <filename>${IMAGE_ROOTFS}</filename>, which points to @@ -3831,8 +5416,12 @@ </glossentry> <glossentry id='var-IMAGE_ROOTFS'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The location of the root filesystem while it is under construction (i.e. during the <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link> @@ -3844,8 +5433,12 @@ </glossentry> <glossentry id='var-IMAGE_ROOTFS_ALIGNMENT'><glossterm>IMAGE_ROOTFS_ALIGNMENT</glossterm> + <info> + IMAGE_ROOTFS_ALIGNMENT[doc] = "Specifies the alignment for the output image file in Kbytes." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the alignment for the output image file in Kbytes. If the size of the image is not a multiple of @@ -3860,8 +5453,12 @@ </glossentry> <glossentry id='var-IMAGE_ROOTFS_EXTRA_SPACE'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Defines additional free disk space created in the image in Kbytes. By default, this variable is set to "0". This free disk space is added to the image after the build system determines @@ -3891,8 +5488,12 @@ </glossentry> <glossentry id='var-IMAGE_ROOTFS_SIZE'><glossterm>IMAGE_ROOTFS_SIZE</glossterm> + <info> + IMAGE_ROOTFS_SIZE[doc] = "Defines the size in Kbytes for the generated image." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Defines the size in Kbytes for the generated image. The OpenEmbedded build system determines the final size for the generated image using an algorithm that takes into account the initial disk space used @@ -3920,6 +5521,9 @@ xspace = IMAGE_ROOTFS_EXTRA_SPACE </literallayout> + </para> + + <para> See the <link linkend='var-IMAGE_OVERHEAD_FACTOR'><filename>IMAGE_OVERHEAD_FACTOR</filename></link> and <link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'><filename>IMAGE_ROOTFS_EXTRA_SPACE</filename></link> variables for related information. @@ -3934,8 +5538,12 @@ </glossentry> <glossentry id='var-IMAGE_TYPEDEP'><glossterm>IMAGE_TYPEDEP</glossterm> + <info> + IMAGE_TYPEDEP[doc] = "Specifies a dependency from one image type on another." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies a dependency from one image type on another. Here is an example from the <link linkend='ref-classes-image-live'><filename>image-live</filename></link> @@ -3943,6 +5551,9 @@ <literallayout class='monospaced'> IMAGE_TYPEDEP_live = "ext3" </literallayout> + </para> + + <para> In the previous example, the variable ensures that when "live" is listed with the <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link> @@ -3957,8 +5568,12 @@ </glossentry> <glossentry id='var-IMAGE_TYPES'><glossterm>IMAGE_TYPES</glossterm> + <info> + IMAGE_TYPES[doc] = "Specifies the complete list of supported image types by default." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the complete list of supported image types by default: <literallayout class='monospaced'> @@ -3988,6 +5603,9 @@ vmdk elf </literallayout> + </para> + + <para> For more information about these types of images, see <filename>meta/classes/image_types*.bbclass</filename> in the @@ -3997,12 +5615,20 @@ </glossentry> <glossentry id='var-INC_PR'><glossterm>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 + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Helps define the recipe revision for recipes that share a common <filename>include</filename> file. You can think of this variable as part of the recipe revision - as set from within an include file.</para> - <para>Suppose, for example, you have a set of recipes that + as set from within an include file. + </para> + + <para> + Suppose, for example, you have a set of recipes that are used across several projects. And, within each of those recipes the revision (its <link linkend='var-PR'><filename>PR</filename></link> @@ -4013,14 +5639,18 @@ version of the recipe. In this scenario, it can get complicated when recipes that are used in many places and provide common functionality - are upgraded to a new revision.</para> - <para>A more efficient way of dealing with this situation is + are upgraded to a new revision. + </para> + + <para> + A more efficient way of dealing with this situation is to set the <filename>INC_PR</filename> variable inside the <filename>include</filename> files that the recipes share and then expand the <filename>INC_PR</filename> variable within the recipes to help define the recipe revision. - </para> + </para> + <para> The following provides an example that shows how to use the <filename>INC_PR</filename> variable @@ -4045,13 +5675,18 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <filename>include</filename> file. The remaining lines in the example are from individual recipes and show how the <filename>PR</filename> value - is set.</para> + is set. + </para> </glossdef> </glossentry> <glossentry id='var-INCOMPATIBLE_LICENSE'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies a space-separated list of license names (as they would appear in <link linkend='var-LICENSE'><filename>LICENSE</filename></link>) @@ -4077,8 +5712,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-INHIBIT_DEFAULT_DEPS'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Prevents the default dependencies, namely the C compiler and standard C library (libc), from being added to <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>. @@ -4094,9 +5733,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-INHIBIT_PACKAGE_DEBUG_SPLIT'><glossterm>INHIBIT_PACKAGE_DEBUG_SPLIT</glossterm> + <info> + INHIBIT_PACKAGE_STRIP[doc] = "If set to "1", causes the build to not strip binaries in resulting packages." + </info> <glossdef> - - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Prevents the OpenEmbedded build system from splitting out debug information during packaging. By default, the build system splits out debugging @@ -4122,16 +5764,24 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-INHIBIT_PACKAGE_STRIP'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> If set to "1", causes the build to not strip binaries in resulting packages. </para> </glossdef> </glossentry> <glossentry id='var-INHERIT'><glossterm>INHERIT</glossterm> + <info> + INHERIT[doc] = "Causes the named class to be inherited at this point during parsing. The variable is only valid in configuration files." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Causes the named class to be inherited at this point during parsing. The variable is only valid in configuration files. @@ -4140,8 +5790,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-INHERIT_DISTRO'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Lists classes that will be inherited at the distribution level. It is unlikely that you want to edit this variable. @@ -4159,8 +5813,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-INITRAMFS_FSTYPES'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Defines the format for the output image of an initial RAM disk (initramfs), which is used during boot. Supported formats are the same as those supported by the @@ -4171,8 +5829,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-INITRAMFS_IMAGE'><glossterm>INITRAMFS_IMAGE</glossterm> + <info> + INITRAMFS_IMAGE[doc] = "Causes the OpenEmbedded build system to build an additional recipe as a dependency to your root filesystem recipe (e.g. core-image-sato)." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Causes the OpenEmbedded build system to build an additional recipe as a dependency to your root filesystem recipe (e.g. <filename>core-image-sato</filename>). @@ -4214,8 +5876,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-INITRAMFS_IMAGE_BUNDLE'><glossterm>INITRAMFS_IMAGE_BUNDLE</glossterm> + <info> + INITRAMFS_IMAGE_BUNDLE[doc] = "Controls whether or not the image recipe specified by INITRAMFS_IMAGE is run through an extra pass during kernel compilation in order to build a single binary that contains both the kernel image and the initial RAM disk (initramfs)." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Controls whether or not the image recipe specified by <link linkend='var-INITRAMFS_IMAGE'><filename>INITRAMFS_IMAGE</filename></link> is run through an extra pass during kernel compilation @@ -4261,8 +5927,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-INITRD'><glossterm>INITRD</glossterm> + <info> + INITRD[doc] = "Indicates a list of filesystem images to concatenate and use as an initial RAM disk (initrd)." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Indicates list of filesystem images to concatenate and use as an initial RAM disk (<filename>initrd</filename>). </para> @@ -4277,8 +5947,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-INITRD_IMAGE'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> When building a "live" bootable image (i.e. when <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link> contains "live"), <filename>INITRD_IMAGE</filename> @@ -4296,11 +5970,16 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-INITSCRIPT_NAME'><glossterm>INITSCRIPT_NAME</glossterm> + <info> + INITSCRIPT_NAME[doc] = "The filename of the initialization script as installed to ${sysconfdir}/init.d." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The filename of the initialization script as installed to <filename>${sysconfdir}/init.d</filename>. </para> + <para> This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>. The variable is mandatory. @@ -4309,11 +5988,17 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-INITSCRIPT_PACKAGES'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> A list of the packages that contain initscripts. If multiple packages are specified, you need to append the package name - to the other <filename>INITSCRIPT_*</filename> as an override.</para> + to the other <filename>INITSCRIPT_*</filename> as an override. + </para> + <para> This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>. The variable is optional and defaults to the @@ -4323,23 +6008,32 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-INITSCRIPT_PARAMS'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the options to pass to <filename>update-rc.d</filename>. Here is an example: <literallayout class='monospaced'> INITSCRIPT_PARAMS = "start 99 5 2 . stop 20 0 1 6 ." </literallayout> + </para> + + <para> In this example, the script has a runlevel of 99, starts the script in initlevels 2 and 5, and stops the script in levels 0, 1 and 6. </para> + <para> 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 @@ -4352,8 +6046,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-INSANE_SKIP'><glossterm>INSANE_SKIP</glossterm> + <info> + INSANE_SKIP[doc] = "Specifies the QA checks to skip for a specific package within a recipe." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the QA checks to skip for a specific package within a recipe. For example, to skip the check for symbolic link @@ -4365,6 +6063,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" INSANE_SKIP_${PN} += "dev-so" </literallayout> </para> + <para> See the "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>" section for a list of the valid QA checks you can @@ -4374,8 +6073,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-IPK_FEED_URIS'><glossterm>IPK_FEED_URIS</glossterm> + <info> + IPK_FEED_URIS[doc] = "List of ipkg feed records to put into generated image." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> When the IPK backend is in use and package management is enabled on the target, you can use this variable to set up <filename>opkg</filename> in the target image @@ -4430,8 +6133,12 @@ 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> + <info> + KARCH[doc] = "Defines the kernel architecture used when assembling the configuration. You define the KARCH variable in the BSP Descriptions." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Defines the kernel architecture used when assembling the configuration. Architectures supported for this release are: @@ -4453,13 +6160,16 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-KBRANCH'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> A regular expression used by the build process to explicitly - identify the kernel branch that is validated, patched + identify the kernel branch that is validated, patched, and configured during a build. - The <filename>KBRANCH</filename> variable is optional. - You can use it to trigger checks to ensure the exact kernel + You must set this variable to ensure the exact kernel branch you want is being used by the build process. </para> @@ -4467,20 +6177,14 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" Values for this variable are set in the kernel's recipe file and the kernel's append file. For example, if you are using the Yocto Project kernel that - is based on the Linux 3.10 kernel, the kernel recipe file + is based on the Linux 3.14 kernel, the kernel recipe file is the - <filename>meta/recipes-kernel/linux/linux-yocto_3.10.bb</filename> + <filename>meta/recipes-kernel/linux/linux-yocto_3.14.bb</filename> file. - Following is the default value for <filename>KBRANCH</filename> - and the default override for the architectures the Yocto - Project supports: + Following is an example for a kernel recipe file: <literallayout class='monospaced'> - KBRANCH_DEFAULT = "standard/base" - KBRANCH = "${KBRANCH_DEFAULT}" + KBRANCH ?= "standard/base" </literallayout> - This branch exists in the <filename>linux-yocto-3.10</filename> - kernel Git repository - <ulink url='&YOCTO_GIT_URL;/cgit.cgi/linux-yocto-3.10/refs/heads'></ulink>. </para> <para> @@ -4489,48 +6193,30 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" machine or target hardware. The kernel's append file is located in the BSP layer for a given machine. - For example, the kernel append file for the Crown Bay BSP is in the + For example, the kernel append file for the Emenlow BSP is in the <filename>meta-intel</filename> Git repository and is named - <filename>meta-crownbay/recipes-kernel/linux/linux-yocto_3.10.bbappend</filename>. + <filename>meta-emenlow/recipes-kernel/linux/linux-yocto_3.14.bbappend</filename>. Here are the related statements from the append file: <literallayout class='monospaced'> - 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" + COMPATIBLE_MACHINE_emenlow-noemgd = "emenlow-noemgd" + KMACHINE_emenlow-noemgd = "emenlow" + KBRANCH_emenlow-noemgd = "standard/base" + KERNEL_FEATURES_append_emenlow-noemgd = " features/drm-gma500/drm-gma500.scc" </literallayout> - The <filename>KBRANCH_*</filename> statements identify - the kernel branch to use when building for the Crown - Bay BSP. - In this case there are two identical statements: one - for each type of Crown Bay machine. - </para> - </glossdef> - </glossentry> - - <glossentry id='var-KBRANCH_DEFAULT'><glossterm>KBRANCH_DEFAULT</glossterm> - <glossdef> - <para> - Defines the Linux kernel source repository's default - branch used to build the Linux kernel. - The <filename>KBRANCH_DEFAULT</filename> value is - the default value for - <link linkend='var-KBRANCH'><filename>KBRANCH</filename></link>. - Unless you specify otherwise, - <filename>KBRANCH_DEFAULT</filename> initializes to - "master". + The <filename>KBRANCH</filename> statement identifies + the kernel branch to use when building for the Emenlow + BSP. </para> </glossdef> </glossentry> <glossentry id='var-KERNEL_EXTRA_ARGS'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies additional <filename>make</filename> command-line arguments the OpenEmbedded build system passes on when compiling the kernel. @@ -4539,38 +6225,53 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-KERNEL_FEATURES'><glossterm>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. + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Includes additional metadata from the Yocto Project kernel Git repository. In the OpenEmbedded build system, the default Board Support Packages (BSPs) <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> is provided through the <link linkend='var-KMACHINE'><filename>KMACHINE</filename></link> and <link linkend='var-KBRANCH'><filename>KBRANCH</filename></link> variables. You can use the <filename>KERNEL_FEATURES</filename> variable to further - add metadata for all BSPs.</para> - <para>The metadata you add through this variable includes config fragments and + add metadata for all BSPs. + </para> + + <para> + The metadata you add through this variable includes config fragments and features descriptions, which usually includes patches as well as config fragments. You typically override the <filename>KERNEL_FEATURES</filename> variable for a specific machine. In this way, you can provide validated, but optional, sets of kernel - configurations and features.</para> - <para>For example, the following adds <filename>netfilter</filename> to all + configurations and features. + </para> + + <para> + For example, the following adds <filename>netfilter</filename> to all the Yocto Project kernels and adds sound support to the <filename>qemux86</filename> machine: <literallayout class='monospaced'> # Add netfilter to all linux-yocto kernels - KERNEL_FEATURES="features/netfilter" + KERNEL_FEATURES="features/netfilter/netfilter.scc" # Add sound support to the qemux86 machine - KERNEL_FEATURES_append_qemux86=" cfg/sound" + KERNEL_FEATURES_append_qemux86=" cfg/sound.scc" </literallayout></para> </glossdef> </glossentry> <glossentry id='var-KERNEL_IMAGE_BASE_NAME'><glossterm>KERNEL_IMAGE_BASE_NAME</glossterm> + <info> + KERNEL_IMAGE_BASE_NAME[doc] = "The base name of the kernel image." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The base name of the kernel image. This variable is set in the <link linkend='ref-classes-kernel'>kernel</link> class @@ -4578,6 +6279,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <literallayout class='monospaced'> KERNEL_IMAGE_BASE_NAME ?= "${KERNEL_IMAGETYPE}-${PKGE}-${PKGV}-${PKGR}-${MACHINE}-${DATETIME}" </literallayout> + </para> + + <para> See the <link linkend='var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></link>, <link linkend='var-PKGE'><filename>PKGE</filename></link>, @@ -4591,19 +6295,60 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> + <glossentry id='var-KERNEL_IMAGE_MAXSIZE'><glossterm>KERNEL_IMAGE_MAXSIZE</glossterm> + <info> + KERNEL_IMAGE_MAXSIZE[doc] = "The maximum allowable size in kilobytes of the kernel image file." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Specifies the maximum size of the kernel image file in + kilobytes. + If <filename>KERNEL_IMAGE_MAXSIZE</filename> is set, + the size of the kernel image file is checked against + the set value during the + <link linkend='ref-tasks-sizecheck'><filename>do_sizecheck</filename></link> + task. + The task fails if the kernel image file is larger than + the setting. + </para> + + <para> + <filename>KERNEL_IMAGE_MAXSIZE</filename> is useful for + target devices that have a limited amount of space in + which the kernel image must be stored. + </para> + + <para> + By default, this variable is not set, which means the + size of the kernel image is not checked. + </para> + </glossdef> + </glossentry> + <glossentry id='var-KERNEL_IMAGETYPE'><glossterm>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 + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + The type of kernel to build for a device, usually set by the machine configuration files and defaults to "zImage". This variable is used when building the kernel and is passed to <filename>make</filename> as the target to - build.</para> + build. + </para> </glossdef> </glossentry> <glossentry id='var-KERNEL_MODULE_AUTOLOAD'><glossterm>KERNEL_MODULE_AUTOLOAD</glossterm> + <info> + KERNEL_MODULE_AUTOLOAD[doc] = "Lists kernel modules that need to be auto-loaded during boot" + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Lists kernel modules that need to be auto-loaded during boot. <note> @@ -4652,8 +6397,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-KERNEL_MODULE_PROBECONF'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Provides a list of modules for which the OpenEmbedded build system expects to find <filename>module_conf_</filename><replaceable>modname</replaceable> @@ -4667,8 +6416,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-KERNEL_PATH'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> 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> @@ -4694,8 +6447,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-KERNEL_SRC'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> 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> @@ -4721,8 +6478,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-KFEATURE_DESCRIPTION'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Provides a short description of a configuration fragment. You use this variable in the <filename>.scc</filename> file that describes a configuration fragment file. @@ -4737,101 +6498,59 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-KMACHINE'><glossterm>KMACHINE</glossterm> + <info> + KMACHINE[doc] = "The machine as known by the kernel." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The machine as known by the kernel. - Sometimes the machine name used by the kernel does not match the machine name - used by the OpenEmbedded build system. - For example, the machine name that the OpenEmbedded build system understands as - <filename>qemuarm</filename> goes by a different name in the Linux Yocto kernel. - The kernel understands that machine as <filename>arm_versatile926ejs</filename>. - For cases like these, the <filename>KMACHINE</filename> variable maps the - kernel machine name to the OpenEmbedded build system machine name. + Sometimes the machine name used by the kernel does not + match the machine name used by the OpenEmbedded build + system. + For example, the machine name that the OpenEmbedded build + system understands as + <filename>core2-32-intel-common</filename> goes by a + different name in the Linux Yocto kernel. + The kernel understands that machine as + <filename>intel-core2-32</filename>. + For cases like these, the <filename>KMACHINE</filename> + variable maps the kernel machine name to the OpenEmbedded + build system machine name. </para> <para> - Kernel machine names are initially defined in the + These mappings between different names occur in the Yocto Linux Kernel's <filename>meta</filename> branch. - From the <filename>meta</filename> branch, look in - the <filename>meta/cfg/kernel-cache/bsp/<bsp_name>/<bsp-name>-<kernel-type>.scc</filename> file. - For example, from the <filename>meta</filename> branch in the - <filename>linux-yocto-3.0</filename> kernel, the - <filename>meta/cfg/kernel-cache/bsp/cedartrail/cedartrail-standard.scc</filename> file - has the following: - <literallayout class='monospaced'> - define KMACHINE cedartrail - define KTYPE standard - define KARCH i386 - - include ktypes/standard - branch cedartrail - - include cedartrail.scc - </literallayout> - You can see that the kernel understands the machine name for - the Cedar Trail Board Support Package (BSP) as - <filename>cedartrail</filename>. - </para> - - <para> - If you look in the Cedar Trail BSP layer in the - <filename>meta-intel</filename> - <ulink url='&YOCTO_DOCS_DEV_URL;#source-repositories'>Source Repositories</ulink> - at <filename>meta-cedartrail/recipes-kernel/linux/linux-yocto_3.0.bbappend</filename>, - you will find the following statements among others: - <literallayout class='monospaced'> - COMPATIBLE_MACHINE_cedartrail = "cedartrail" - KMACHINE_cedartrail = "cedartrail" - KBRANCH_cedartrail = "yocto/standard/cedartrail" - KERNEL_FEATURES_append_cedartrail += "bsp/cedartrail/cedartrail-pvr-merge.scc" - KERNEL_FEATURES_append_cedartrail += "cfg/efi-ext.scc" - - COMPATIBLE_MACHINE_cedartrail-nopvr = "cedartrail" - KMACHINE_cedartrail-nopvr = "cedartrail" - KBRANCH_cedartrail-nopvr = "yocto/standard/cedartrail" - KERNEL_FEATURES_append_cedartrail-nopvr += " cfg/smp.scc" - </literallayout> - The <filename>KMACHINE</filename> statements in the kernel's append file make sure that - the OpenEmbedded build system and the Yocto Linux kernel understand the same machine - names. - </para> - - <para> - This append file uses two <filename>KMACHINE</filename> statements. - The first is not really necessary but does ensure that the machine known to the - OpenEmbedded build system as <filename>cedartrail</filename> maps to the machine - in the kernel also known as <filename>cedartrail</filename>: - <literallayout class='monospaced'> - KMACHINE_cedartrail = "cedartrail" - </literallayout> - </para> - - <para> - The second statement is a good example of why the <filename>KMACHINE</filename> variable - is needed. - In this example, the OpenEmbedded build system uses the <filename>cedartrail-nopvr</filename> - machine name to refer to the Cedar Trail BSP that does not support the proprietary - PowerVR driver. - The kernel, however, uses the machine name <filename>cedartrail</filename>. - Thus, the append file must map the <filename>cedartrail-nopvr</filename> machine name to - the kernel's <filename>cedartrail</filename> name: + As an example take a look in the + <filename>common/recipes-kernel/linux/linux-yocto_3.19.bbappend</filename> + file: <literallayout class='monospaced'> - KMACHINE_cedartrail-nopvr = "cedartrail" + LINUX_VERSION_core2-32-intel-common = "3.19.0" + COMPATIBLE_MACHINE_core2-32-intel-common = "${MACHINE}" + SRCREV_meta_core2-32-intel-common = "8897ef68b30e7426bc1d39895e71fb155d694974" + SRCREV_machine_core2-32-intel-common = "43b9eced9ba8a57add36af07736344dcc383f711" + KMACHINE_core2-32-intel-common = "intel-core2-32" + KBRANCH_core2-32-intel-common = "standard/base" + KERNEL_FEATURES_append_core2-32-intel-common = "${KERNEL_FEATURES_INTEL_COMMON}" </literallayout> + The <filename>KMACHINE</filename> statement says that + the kernel understands the machine name as + "intel-core2-32". + However, the OpenEmbedded build system understands the + machine as "core2-32-intel-common". </para> - <para> - BSPs that ship with the Yocto Project release provide all mappings between the Yocto - Project kernel machine names and the OpenEmbedded machine names. - Be sure to use the <filename>KMACHINE</filename> if you create a BSP and the machine - name you use is different than that used in the kernel. - </para> </glossdef> </glossentry> <glossentry id='var-KTYPE'><glossterm>KTYPE</glossterm> + <info> + KTYPE[doc] = "Defines the kernel type to be used in assembling the configuration." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Defines the kernel type to be used in assembling the configuration. The linux-yocto recipes define "standard", "tiny", @@ -4856,8 +6575,12 @@ 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> + <info> + LABELS[doc] = "Provides a list of targets for automatic configuration." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Provides a list of targets for automatic configuration. </para> @@ -4870,8 +6593,13 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-LAYERDEPENDS'><glossterm>LAYERDEPENDS</glossterm> + <info> + LAYERDEPENDS[doc] = "Lists the layers, separated by spaces, upon which this recipe depends. This variable is used in the conf/layer.conf file and must be suffixed with the name of the specific layer." + </info> <glossdef> - <para>Lists the layers that this recipe depends upon, separated by spaces. + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Lists the layers that this recipe depends upon, separated by spaces. Optionally, you can specify a specific layer version for a dependency by adding it to the end of the layer name with a colon, (e.g. "anotherlayer:3" to be compared against @@ -4881,35 +6609,65 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" the version numbers do not match exactly (if specified). This variable is used in the <filename>conf/layer.conf</filename> file and must be suffixed with the name of the specific layer (e.g. - <filename>LAYERDEPENDS_mylayer</filename>).</para> + <filename>LAYERDEPENDS_mylayer</filename>). + </para> </glossdef> </glossentry> <glossentry id='var-LAYERDIR'><glossterm>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 + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + When used inside the <filename>layer.conf</filename> configuration file, this variable provides the path of the current layer. This variable is not available outside of <filename>layer.conf</filename> - and references are expanded immediately when parsing of the file completes.</para> + and references are expanded immediately when parsing of the file completes. + </para> </glossdef> </glossentry> <glossentry id='var-LAYERVERSION'><glossterm>LAYERVERSION</glossterm> + <info> + LAYERVERSION[doc] = "Optionally specifies the version of a layer as a single number. This variable is used in the conf/layer.conf file and must be suffixed with the name of the specific layer." + </info> <glossdef> - <para>Optionally specifies the version of a layer as a single number. + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Optionally specifies the version of a layer as a single number. You can use this within <link linkend='var-LAYERDEPENDS'><filename>LAYERDEPENDS</filename></link> for another layer in order to depend on a specific version of the layer. This variable is used in the <filename>conf/layer.conf</filename> file and must be suffixed with the name of the specific layer (e.g. - <filename>LAYERVERSION_mylayer</filename>).</para> + <filename>LAYERVERSION_mylayer</filename>). + </para> + </glossdef> + </glossentry> + + <glossentry id='var-LD'><glossterm>LD</glossterm> + <info> + LD[doc] = "Minimal command and arguments to run the linker." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + The minimal command and arguments used to run the + linker. + </para> </glossdef> </glossentry> <glossentry id='var-LDFLAGS'><glossterm>LDFLAGS</glossterm> + <info> + LDFLAGS[doc] = "Specifies the flags to pass to the linker." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the flags to pass to the linker. This variable is exported to an environment variable and thus made visible to the software being @@ -4940,8 +6698,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-LEAD_SONAME'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the lead (or primary) compiled library file (<filename>.so</filename>) that the <link linkend='ref-classes-debian'><filename>debian</filename></link> @@ -4957,26 +6719,41 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-LIC_FILES_CHKSUM'><glossterm>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 + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Checksums of the license text in the recipe source code. + </para> + + <para> + This variable tracks changes in license text of the source code files. If the license text is changed, it will trigger a build failure, which gives the developer an opportunity to review any - license change.</para> + license change. + </para> + <para> This variable must be defined for all recipes (unless <link linkend='var-LICENSE'><filename>LICENSE</filename></link> is set to "CLOSED").</para> <para>For more information, see the "<link linkend='usingpoky-configuring-LIC_FILES_CHKSUM'> - Tracking License Changes</link>" section.</para> + Tracking License Changes</link>" section. + </para> </glossdef> </glossentry> <glossentry id='var-LICENSE'><glossterm>LICENSE</glossterm> + <info> + LICENSE[doc] = "The list of source licenses for the recipe. The logical operators &, '|', and parentheses can be used." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The list of source licenses for the recipe. Follow these rules: <itemizedlist> @@ -5036,8 +6813,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-LICENSE_FLAGS'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies additional flags for a recipe you must whitelist through <link linkend='var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></link> @@ -5060,8 +6841,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-LICENSE_FLAGS_WHITELIST'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Lists license flags that when specified in <link linkend='var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></link> within a recipe should not prevent that recipe from being @@ -5076,21 +6861,31 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-LICENSE_PATH'><glossterm>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. + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Path to additional licenses used during the build. By default, the OpenEmbedded build system uses <filename>COMMON_LICENSE_DIR</filename> to define the directory that holds common license text used during the build. The <filename>LICENSE_PATH</filename> variable allows you to extend that location to other areas that have additional licenses: <literallayout class='monospaced'> LICENSE_PATH += "<replaceable>path-to-additional-common-licenses</replaceable>" - </literallayout></para> + </literallayout> + </para> </glossdef> </glossentry> <glossentry id='var-LINUX_KERNEL_TYPE'><glossterm>LINUX_KERNEL_TYPE</glossterm> + <info> + LINUX_KERNEL_TYPE[doc] = "Defines the kernel type to be used in assembling the configuration." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Defines the kernel type to be used in assembling the configuration. The linux-yocto recipes define "standard", "tiny", and @@ -5118,8 +6913,13 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-LINUX_VERSION'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + The Linux version from <filename>kernel.org</filename> on which the Linux kernel image being built using the OpenEmbedded build system is based. You define this variable in the kernel recipe. @@ -5130,18 +6930,27 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <literallayout class='monospaced'> LINUX_VERSION ?= "3.4.24" </literallayout> + </para> + + <para> The <filename>LINUX_VERSION</filename> variable is used to define <link linkend='var-PV'><filename>PV</filename></link> for the recipe: <literallayout class='monospaced'> PV = "${LINUX_VERSION}+git${SRCPV}" - </literallayout></para> + </literallayout> + </para> </glossdef> </glossentry> <glossentry id='var-LINUX_VERSION_EXTENSION'><glossterm>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 + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + 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. @@ -5150,6 +6959,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <literallayout class='monospaced'> LINUX_VERSION_EXTENSION ?= "-yocto-${<link linkend='var-LINUX_KERNEL_TYPE'>LINUX_KERNEL_TYPE</link>}" </literallayout> + </para> + + <para> Defining this variable essentially sets the Linux kernel configuration item <filename>CONFIG_LOCALVERSION</filename>, which is visible @@ -5165,12 +6977,17 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-LOG_DIR'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the directory to which the OpenEmbedded build system writes overall log files. The default directory is <filename>${TMPDIR}/log</filename>. </para> + <para> For the directory containing logs specific to each task, see the <link linkend='var-T'><filename>T</filename></link> @@ -5184,8 +7001,12 @@ 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> + <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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the target device for which the image is built. You define <filename>MACHINE</filename> in the <filename>local.conf</filename> file found in the @@ -5196,6 +7017,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <literallayout class='monospaced'> MACHINE ?= "qemux86" </literallayout> + </para> + + <para> The variable corresponds to a machine configuration file of the same name, through which machine-specific configurations are set. Thus, when <filename>MACHINE</filename> is set to "qemux86" there @@ -5210,7 +7034,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" shipped include the following: <literallayout class='monospaced'> MACHINE ?= "qemuarm" + MACHINE ?= "qemuarm64" MACHINE ?= "qemumips" + MACHINE ?= "qemumips64" MACHINE ?= "qemuppc" MACHINE ?= "qemux86" MACHINE ?= "qemux86-64" @@ -5231,8 +7057,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-MACHINE_ARCH'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the name of the machine-specific architecture. This variable is set automatically from <link linkend='var-MACHINE'><filename>MACHINE</filename></link> @@ -5245,8 +7075,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><glossterm>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 role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> A list of required machine-specific packages to install as part of the image being built. The build process depends on these packages being present. @@ -5256,6 +7090,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <filename>packagegroup-core-boot</filename>, including the <filename>core-image-minimal</filename> image. </para> + <para> This variable is similar to the <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</link></filename> @@ -5263,6 +7098,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" dependency on the variable's list of packages. In other words, the image will not build if a file in this list is not found. </para> + <para> As an example, suppose the machine for which you are building requires <filename>example-init</filename> to be run during boot to initialize the hardware. @@ -5276,8 +7112,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><glossterm>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 role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> A list of recommended machine-specific packages to install as part of the image being built. The build process does not depend on these packages being present. @@ -5287,6 +7127,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <filename>packagegroup-core-boot</filename>, including the <filename>core-image-minimal</filename> image. </para> + <para> This variable is similar to the <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</link></filename> @@ -5297,6 +7138,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" functionality may be selected to be built into the kernel rather than as a module, in which case a package will not be produced. </para> + <para> Consider an example where you have a custom kernel where a specific touchscreen driver is required for the machine to be usable. @@ -5315,6 +7157,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123" </literallayout> </para> + <para> Some examples of these machine essentials are flash, screen, keyboard, mouse, or touchscreen drivers (depending on the machine). @@ -5323,19 +7166,25 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-MACHINE_EXTRA_RDEPENDS'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> 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. </para> + <para> This variable affects all images based on <filename>packagegroup-base</filename>, which does not include the <filename>core-image-minimal</filename> or <filename>core-image-full-cmdline</filename> images. </para> + <para> The variable is similar to the <filename><link linkend='var-MACHINE_EXTRA_RRECOMMENDS'>MACHINE_EXTRA_RRECOMMENDS</link></filename> @@ -5343,6 +7192,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" dependency on the variable's list of packages. In other words, the image will not build if a file in this list is not found. </para> + <para> An example is a machine that has WiFi capability but is not essential for the machine to boot the image. @@ -5362,18 +7212,24 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-MACHINE_EXTRA_RRECOMMENDS'><glossterm>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 role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> 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 dependency on this list of packages. </para> + <para> This variable affects only images based on <filename>packagegroup-base</filename>, which does not include the <filename>core-image-minimal</filename> or <filename>core-image-full-cmdline</filename> images. </para> + <para> This variable is similar to the <filename><link linkend='var-MACHINE_EXTRA_RDEPENDS'>MACHINE_EXTRA_RDEPENDS</link></filename> @@ -5381,6 +7237,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" dependency on the variable's list of packages. In other words, the image will build if a file in this list is not found. </para> + <para> An example is a machine that has WiFi capability but is not essential For the machine to boot the image. @@ -5400,8 +7257,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-MACHINE_FEATURES'><glossterm>MACHINE_FEATURES</glossterm> + <info> + MACHINE_FEATURES[doc] = "Specifies the list of hardware features the MACHINE supports." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the list of hardware features the <link linkend='var-MACHINE'><filename>MACHINE</filename></link> is capable of supporting. @@ -5423,8 +7284,13 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-MACHINE_FEATURES_BACKFILL'><glossterm>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 + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Features to be added to <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename> if not also present in <filename><link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'>MACHINE_FEATURES_BACKFILL_CONSIDERED</link></filename>. @@ -5442,21 +7308,30 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><glossterm>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 + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Features from <filename><link linkend='var-MACHINE_FEATURES_BACKFILL'>MACHINE_FEATURES_BACKFILL</link></filename> that should not be backfilled (i.e. added to <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>) during the build. See the "<link linkend='ref-features-backfill'>Feature backfilling</link>" section for more information. - </para> + </para> </glossdef> </glossentry> <glossentry id='var-MACHINEOVERRIDES'><glossterm>MACHINEOVERRIDES</glossterm> + <info> + MACHINEOVERRIDES[doc] = "Lists overrides specific to the current machine. By default, this list includes the value of MACHINE." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Lists overrides specific to the current machine. By default, this list includes the value of <filename><link linkend='var-MACHINE'>MACHINE</link></filename>. @@ -5470,6 +7345,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <literallayout class='monospaced'> MACHINEOVERRIDES =. "qemuall:" </literallayout> + </para> + + <para> Applying an override like <filename>qemuall</filename> affects all QEMU emulated machines elsewhere. Here is an example from the @@ -5484,14 +7362,24 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-MAINTAINER'><glossterm>MAINTAINER</glossterm> + <info> + MAINTAINER[doc] = "The email address of the distribution maintainer." + </info> <glossdef> - <para>The email address of the distribution maintainer.</para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + The email address of the distribution maintainer. + </para> </glossdef> </glossentry> <glossentry id='var-MIRRORS'><glossterm>MIRRORS</glossterm> + <info> + MIRRORS[doc] = "Specifies additional paths from which the OpenEmbedded build system gets source code." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies additional paths from which the OpenEmbedded build system gets source code. When the build system searches for source code, it first @@ -5515,8 +7403,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-MLPREFIX'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies a prefix has been added to <link linkend='var-PN'><filename>PN</filename></link> to create a special version of a recipe or package, such as a Multilib version. @@ -5530,8 +7422,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-module_autoload'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> This variable has been replaced by the <filename>KERNEL_MODULE_AUTOLOAD</filename> variable. You should replace all occurrences of @@ -5540,6 +7436,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <literallayout class='monospaced'> module_autoload_rfcomm = "rfcomm" </literallayout> + </para> + + <para> should now be replaced with: <literallayout class='monospaced'> KERNEL_MODULE_AUTOLOAD += "rfcomm" @@ -5552,8 +7451,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-module_conf'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies <ulink url='http://linux.die.net/man/5/modprobe.d'><filename>modprobe.d</filename></ulink> syntax lines for inclusion in the @@ -5609,8 +7512,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-MODULE_IMAGE_BASE_NAME'><glossterm>MODULE_IMAGE_BASE_NAME</glossterm> + <info> + MODULE_IMAGE_BASE_NAME[doc] = "The base name of the kernel modules tarball." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The base name of the kernel modules tarball. This variable is set in the <link linkend='ref-classes-kernel'>kernel</link> class @@ -5618,6 +7525,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <literallayout class='monospaced'> MODULE_IMAGE_BASE_NAME ?= "modules-${PKGE}-${PKGV}-${PKGR}-${MACHINE}-${DATETIME}" </literallayout> + </para> + + <para> See the <link linkend='var-PKGE'><filename>PKGE</filename></link>, <link linkend='var-PKGV'><filename>PKGV</filename></link>, @@ -5631,8 +7541,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-MODULE_TARBALL_DEPLOY'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Controls creation of the <filename>modules-*.tgz</filename> file. Set this variable to "0" to disable creation of this @@ -5643,8 +7557,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-MULTIMACH_TARGET_SYS'><glossterm>MULTIMACH_TARGET_SYS</glossterm> + <info> + MULTIMACH_TARGET_SYS[doc] = "Separates files for different machines such that you can build for multiple target machines using the same output directories." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Separates files for different machines such that you can build for multiple target machines using the same output directories. See the <link linkend='var-STAMP'><filename>STAMP</filename></link> variable @@ -5658,8 +7576,12 @@ 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> + <info> + NATIVELSBSTRING[doc] = "A string identifying the host distribution." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> A string identifying the host distribution. Strings consist of the host distributor ID followed by the release, as reported by the @@ -5670,6 +7592,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" If this information is unable to be determined, the value resolves to "Unknown". </para> + <para> This variable is used by default to isolate native shared state packages for different distributions (e.g. to avoid @@ -5682,9 +7605,26 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> + <glossentry id='var-NM'><glossterm>NM</glossterm> + <info> + NM[doc] = "Minimal command and arguments to run 'nm'." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + The minimal command and arguments to run + <filename>nm</filename>. + </para> + </glossdef> + </glossentry> + <glossentry id='var-NO_RECOMMENDATIONS'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Prevents installation of all "recommended-only" packages. Recommended-only packages are packages installed only through the @@ -5695,6 +7635,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <literallayout class='monospaced'> NO_RECOMMENDATIONS = "1" </literallayout> + </para> + + <para> 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: @@ -5737,8 +7680,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-NOHDD'><glossterm>NOHDD</glossterm> + <info> + NOHDD[doc] = "Causes the OpenEmbedded build system to skip building the .hddimg image." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Causes the OpenEmbedded build system to skip building the <filename>.hddimg</filename> image. The <filename>NOHDD</filename> variable is used with the @@ -5751,8 +7698,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-NOISO'><glossterm>NOISO</glossterm> + <info> + NOISO[doc] = "Causes the OpenEmbedded build system to skip building the ISO image." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Causes the OpenEmbedded build system to skip building the ISO image. The <filename>NOISO</filename> variable is used with the @@ -5769,9 +7720,39 @@ 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-OBJCOPY'><glossterm>OBJCOPY</glossterm> + <info> + OBJCOPY[doc] = "Minimal command and arguments to run 'objcopy'." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + The minimal command and arguments to run + <filename>objcopy</filename>. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-OBJDUMP'><glossterm>OBJDUMP</glossterm> + <info> + OBJDUMP[doc] = "Minimal command and arguments to run 'objdump'." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + The minimal command and arguments to run + <filename>objdump</filename>. + </para> + </glossdef> + </glossentry> + <glossentry id='var-OE_BINCONFIG_EXTRA_MANGLE'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> When inheriting the <link linkend='ref-classes-binconfig'><filename>binconfig</filename></link> class, this variable @@ -5800,8 +7781,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-OE_IMPORTS'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> An internal variable used to tell the OpenEmbedded build system what Python modules to import for every Python function run by the system. @@ -5815,8 +7800,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-OE_TERMINAL'><glossterm>OE_TERMINAL</glossterm> + <info> + OE_TERMINAL[doc] = "Controls how the OpenEmbedded build system spawns interactive terminals on the host development system." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Controls how the OpenEmbedded build system spawns interactive terminals on the host development system (e.g. using the BitBake command with the @@ -5838,16 +7827,17 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" konsole none </literallayout> - <note>Konsole support only works for KDE 3.x. - Also, "auto" is the default behavior for - <filename>OE_TERMINAL</filename></note> </para> </glossdef> </glossentry> <glossentry id='var-OEROOT'><glossterm>OEROOT</glossterm> + <info> + OEROOT[doc] = "The directory from which the top-level build environment setup script is sourced." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The directory from which the top-level build environment setup script is sourced. The Yocto Project makes two top-level build environment @@ -5868,12 +7858,16 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-OLDEST_KERNEL'><glossterm>OLDEST_KERNEL</glossterm> + <info> + OLDEST_KERNEL[doc] = "Declares the oldest version of the Linux kernel that the produced binaries must support." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Declares the oldest version of the Linux kernel that the produced binaries must support. This variable is passed into the build of the Embedded - GNU C Library (<filename>eglibc</filename>). + GNU C Library (<filename>glibc</filename>). </para> <para> @@ -5887,8 +7881,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-OVERRIDES'><glossterm>OVERRIDES</glossterm> + <info> + OVERRIDES[doc] = "BitBake uses OVERRIDES to control what variables are overridden after BitBake parses recipes and configuration files." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> BitBake uses <filename>OVERRIDES</filename> to control what variables are overridden after BitBake parses recipes and configuration files. @@ -5904,18 +7902,28 @@ 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> + <info> + P[doc] = "The recipe name and version. P is comprised of ${PN}-${PV}." + </info> <glossdef> - <para>The recipe name and version. + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + The recipe name and version. <filename>P</filename> is comprised of the following: <literallayout class='monospaced'> ${PN}-${PV} - </literallayout></para> + </literallayout> + </para> </glossdef> </glossentry> <glossentry id='var-PACKAGE_ARCH'><glossterm>PACKAGE_ARCH</glossterm> + <info> + PACKAGE_ARCH[doc] = "The architecture of the resulting package or packages." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The architecture of the resulting package or packages. </para> @@ -5940,8 +7948,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-PACKAGE_ARCHS'><glossterm>PACKAGE_ARCHS</glossterm> + <info> + PACKAGE_ARCHS[doc] = "A list of architectures compatible with the given target in order of priority." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies a list of architectures compatible with the target machine. This variable is set automatically and should not @@ -5955,21 +7967,29 @@ 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> + <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> - before <filename>${<link linkend='var-PN'>PN</link>}</filename> - so that those added packages can pick up files that would normally be - included in the default package.</para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Enables easily adding packages to + <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename> + before <filename>${<link linkend='var-PN'>PN</link>}</filename> + so that those added packages can pick up files that would normally be + included in the default package. + </para> </glossdef> </glossentry> <glossentry id='var-PACKAGE_CLASSES'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> This variable, which is set in the <filename>local.conf</filename> configuration file found in the <filename>conf</filename> folder of the @@ -5984,6 +8004,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <literallayout class='monospaced'> PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk package_tar" </literallayout> + <note><title>Warning</title> + While it is a legal option, the + <filename>package_tar</filename> class is broken + and is not supported. + It is recommended that you do not use it. + </note> The build system uses only the first argument in the list as the package manager when creating your image or SDK. However, packages will be created using any additional @@ -5991,20 +8017,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" For example, if you use the following in your <filename>local.conf</filename> file: <literallayout class='monospaced'> - PACKAGE_CLASSES ?= "package_ipk package_tar" + PACKAGE_CLASSES ?= "package_ipk" </literallayout> The OpenEmbedded build system uses the IPK package manager - to create your image or SDK as well as generating - TAR packages. - </para> - - <para> - You cannot specify the - <link linkend='ref-classes-package_tar'><filename>package_tar</filename></link> - class first in the list. - Files using the <filename>.tar</filename> format cannot - be used as a substitute packaging format - for DEB, RPM, and IPK formatted files for your image or SDK. + to create your image or SDK. </para> <para> @@ -6017,9 +8033,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-PACKAGE_DEBUG_SPLIT_STYLE'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> 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). @@ -6073,13 +8092,20 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-PACKAGE_EXCLUDE'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Lists packages that should not be installed into an image. For example: <literallayout class='monospaced'> PACKAGE_EXCLUDE = "<replaceable>package_name</replaceable> <replaceable>package_name</replaceable> <replaceable>package_name</replaceable> ..." </literallayout> + </para> + + <para> 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: @@ -6118,17 +8144,26 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-PACKAGE_EXTRA_ARCHS'><glossterm>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. + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + 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> + <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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The <filename>PACKAGE_GROUP</filename> variable has been renamed to <link linkend='var-FEATURE_PACKAGES'><filename>FEATURE_PACKAGES</filename></link>. @@ -6145,8 +8180,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-PACKAGE_INSTALL'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The final list of packages passed to the package manager for installation into the image. </para> @@ -6172,9 +8211,29 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> + <glossentry id='var-PACKAGE_INSTALL_ATTEMPTONLY'><glossterm>PACKAGE_INSTALL_ATTEMPTONLY</glossterm> + <info> + PACKAGE_INSTALL_ATTEMPTONLY[doc] = "List of packages attempted to be installed when creating an image. If a listed package fails to install, the build system does not generate an error. This variable is generally not user-defined." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Specifies a list of packages the OpenEmbedded build + system attempts to install when creating an image. + If a listed package fails to install, the build system + does not generate an error. + This variable is generally not user-defined. + </para> + </glossdef> + </glossentry> + <glossentry id='var-PACKAGE_PREPROCESS_FUNCS'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies a list of functions run to pre-process the <link linkend='var-PKGD'><filename>PKGD</filename></link> directory prior to splitting the files out to individual @@ -6184,8 +8243,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-PACKAGECONFIG'><glossterm>PACKAGECONFIG</glossterm> + <info> + PACKAGECONFIG[doc] = "This variable provides a means of enabling or disabling features of a recipe on a per-recipe basis." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> This variable provides a means of enabling or disabling features of a recipe on a per-recipe basis. <filename>PACKAGECONFIG</filename> blocks are defined @@ -6198,6 +8261,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" PACKAGECONFIG[f2] = "--with-f2,--without-f2,build-deps-f2,rt-deps-f2" PACKAGECONFIG[f3] = "--with-f3,--without-f3,build-deps-f3,rt-deps-f3" </literallayout> + </para> + + <para> The <filename>PACKAGECONFIG</filename> variable itself specifies a space-separated list of the features to enable. @@ -6298,37 +8364,50 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-PACKAGES'><glossterm>PACKAGES</glossterm> + <glossentry id='var-PACKAGEGROUP_DISABLE_COMPLEMENTARY'><glossterm>PACKAGEGROUP_DISABLE_COMPLEMENTARY</glossterm> + <info> + PACKAGEGROUP_DISABLE_COMPLEMENTARY[doc] = "Prevents automatic creation of the normal complementary packages such as -dev and -dbg in a packagegroup recipe." + </info> <glossdef> - <para>The list of packages to be created from the recipe. - The default value is the following: - <literallayout class='monospaced'> - ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN} - </literallayout></para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + For recipes inheriting the + <link linkend='ref-classes-packagegroup'><filename>packagegroup</filename></link> + class, setting + <filename>PACKAGEGROUP_DISABLE_COMPLEMENTARY</filename> to + "1" specifies that the normal complementary packages + (i.e. <filename>-dev</filename>, + <filename>-dbg</filename>, and so forth) should not be + automatically created by the + <filename>packagegroup</filename> recipe, which is the + default behavior. + </para> </glossdef> </glossentry> - <glossentry id='var-PACKAGESPLITFUNCS'><glossterm>PACKAGESPLITFUNCS</glossterm> + <glossentry id='var-PACKAGES'><glossterm>PACKAGES</glossterm> + <info> + PACKAGES[doc] = "The list of packages to be created from the recipe." + </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 role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + The list of packages to be created from the recipe. + The default value is the following: + <literallayout class='monospaced'> + ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN} + </literallayout> </para> </glossdef> </glossentry> <glossentry id='var-PACKAGES_DYNAMIC'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> A promise that your recipe satisfies runtime dependencies for optional modules that are found in other recipes. <filename>PACKAGES_DYNAMIC</filename> @@ -6346,6 +8425,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link> task. </para> + <para> Typically, if there is a chance that such a situation can occur and the package that is not created is valid @@ -6364,9 +8444,35 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> + <glossentry id='var-PACKAGESPLITFUNCS'><glossterm>PACKAGESPLITFUNCS</glossterm> + <info> + PACKAGESPLITFUNCS[doc] = "Specifies a list of functions run to perform additional splitting of files into individual packages." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + 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>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Extra options passed to the <filename>make</filename> command during the <link linkend='ref-tasks-compile'><filename>do_compile</filename></link> @@ -6378,11 +8484,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </para> <para> - If your development host supports multiple cores, a good - rule of thumb is to set this variable to twice the number - of cores on the host. - If you do not set <filename>PARALLEL_MAKE</filename>, it - defaults to the number of cores your build system has. + The OpenEmbedded build system automatically sets this + variable to be equal to the number of cores the build + system uses. <note> Individual recipes might clear out this variable if the software being built has problems running its @@ -6393,8 +8497,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-PARALLEL_MAKEINST'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Extra options passed to the <filename>make install</filename> command during the <link linkend='ref-tasks-install'><filename>do_install</filename></link> @@ -6411,8 +8519,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-PATCHRESOLVE'><glossterm>PATCHRESOLVE</glossterm> + <info> + PATCHRESOLVE[doc] = "Enable or disable interactive patch resolution." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Determines the action to take when a patch fails. You can set this variable to one of two values: "noop" and "user". @@ -6435,8 +8547,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-PATCHTOOL'><glossterm>PATCHTOOL</glossterm> + <info> + PATCHTOOL[doc] = "Specifies the utility used to apply patches for a recipe during do_patch." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the utility used to apply patches for a recipe during the <link linkend='ref-tasks-patch'><filename>do_patch</filename></link> @@ -6462,8 +8578,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-PE'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The epoch of the recipe. By default, this variable is unset. The variable is used to make upgrades possible when the @@ -6474,20 +8594,30 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-PF'><glossterm>PF</glossterm> - <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 + <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 role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Specifies the recipe or package name and includes all version and revision + numbers (i.e. <filename>glibc-2.13-r20+svnr15508/</filename> and <filename>bash-4.2-r1/</filename>). This variable is comprised of the following: <literallayout class='monospaced'> ${<link linkend='var-PN'>PN</link>}-${<link linkend='var-EXTENDPE'>EXTENDPE</link>}${<link linkend='var-PV'>PV</link>}-${<link linkend='var-PR'>PR</link>} - </literallayout></para> + </literallayout> + </para> </glossdef> </glossentry> <glossentry id='var-PIXBUF_PACKAGES'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> When inheriting the <link linkend='ref-classes-pixbufcache'><filename>pixbufcache</filename></link> class, this variable identifies packages that contain @@ -6503,14 +8633,21 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-PKG'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The name of the resulting package created by the OpenEmbedded build system. <note> When using the <filename>PKG</filename> variable, you must use a package name override. </note> + </para> + + <para> For example, when the <link linkend='ref-classes-debian'><filename>debian</filename></link> class renames the output package, it does so by setting @@ -6519,23 +8656,49 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> + <glossentry id='var-PKG_CONFIG_PATH'><glossterm>PKG_CONFIG_PATH</glossterm> + <info> + PKG_CONFIG_PATH[doc] = "Path to pkg-config files for the current build context." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + The path to <filename>pkg-config</filename> files for the + current build context. + <filename>pkg-config</filename> reads this variable + from the environment. + </para> + </glossdef> + </glossentry> + <glossentry id='var-PKGD'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Points to the destination directory for files to be packaged before they are split into individual packages. This directory defaults to the following: <literallayout class='monospaced'> ${WORKDIR}/package </literallayout> + </para> + + <para> Do not change this default. </para> </glossdef> </glossentry> <glossentry id='var-PKGDATA_DIR'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Points to a shared, global-state directory that holds data generated during the packaging process. During the packaging process, the @@ -6546,20 +8709,30 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <literallayout class='monospaced'> ${STAGING_DIR_HOST}/pkgdata </literallayout> + </para> + + <para> Do not change this default. </para> </glossdef> </glossentry> <glossentry id='var-PKGDEST'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Points to the parent directory for files to be packaged after they have been split into individual packages. This directory defaults to the following: <literallayout class='monospaced'> ${WORKDIR}/packages-split </literallayout> + </para> + + <para> Under this directory, the build system creates directories for each package specified in <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>. @@ -6569,8 +8742,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-PKGDESTWORK'><glossterm>PKGDESTWORK</glossterm> + <info> + PKGDESTWORK[doc] = "Points to a temporary work area used by the do_package task to write output from the do_packagedata task." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Points to a temporary work area used by the <link linkend='ref-tasks-package'><filename>do_package</filename></link> task to write output from the @@ -6581,6 +8758,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <literallayout class='monospaced'> ${WORKDIR}/pkgdata </literallayout> + </para> + + <para> The <filename>do_packagedata</filename> task then packages the data in the temporary work area and installs it into a shared directory pointed to by @@ -6594,8 +8774,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-PKGE'><glossterm>PKGE</glossterm> + <info> + PKGE[doc] = "The epoch of the output package built by the OpenEmbedded build system." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The epoch of the output package built by the OpenEmbedded build system. By default, <filename>PKGE</filename> is set to @@ -6605,19 +8789,27 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-PKGR'><glossterm>PKGR</glossterm> + <info> + PKGR[doc] = "The revision of the output package built by the OpenEmbedded build system." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The revision of the output package built by the OpenEmbedded build system. By default, <filename>PKGR</filename> is set to <link linkend='var-PR'><filename>PR</filename></link>. - </para> + </para> </glossdef> </glossentry> <glossentry id='var-PKGV'><glossterm>PKGV</glossterm> + <info> + PKGV[doc] = "The version of the output package built by the OpenEmbedded build system." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The version of the output package built by the OpenEmbedded build system. By default, <filename>PKGV</filename> is set to @@ -6627,19 +8819,32 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-PN'><glossterm>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> - <para><filename>PN</filename> refers to a recipe name in the context of a file used + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + This variable can have two separate functions depending on the context: a recipe + name or a resulting package name. + </para> + + <para> + <filename>PN</filename> refers to a recipe name in the context of a file used by the OpenEmbedded build system as input to create a package. The name is normally extracted from the recipe file name. For example, if the recipe is named <filename>expat_2.0.1.bb</filename>, then the default value of <filename>PN</filename> - will be "expat".</para> + will be "expat". + </para> + <para> The variable refers to a package name in the context of a file created or produced by the - OpenEmbedded build system.</para> - <para>If applicable, the <filename>PN</filename> variable also contains any special + OpenEmbedded build system. + </para> + + <para> + If applicable, the <filename>PN</filename> variable also contains any special suffix or prefix. For example, using <filename>bash</filename> to build packages for the native machine, <filename>PN</filename> is <filename>bash-native</filename>. @@ -6651,8 +8856,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-PNBLACKLIST'><glossterm>PNBLACKLIST</glossterm> + <info> + PNBLACKLIST[doc] = "Lists recipes you do not want the OpenEmbedded build system to build." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Lists recipes you do not want the OpenEmbedded build system to build. This variable works in conjunction with the @@ -6675,17 +8884,25 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-PR'><glossterm>PR</glossterm> + <info> + PR[doc] = "The revision of the recipe. The default value for this variable is 'r0'." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The revision of the recipe. The default value for this variable is "r0". - </para> + </para> </glossdef> </glossentry> <glossentry id='var-PREFERRED_PROVIDER'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> If multiple recipes provide an item, this variable determines which recipe should be given preference. You should always suffix the variable with the name of the @@ -6703,8 +8920,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-PREFERRED_VERSION'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> If there are multiple versions of recipes available, this variable determines which recipe should be given preference. You must always suffix the variable with the @@ -6719,15 +8940,19 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" Here are two examples: <literallayout class='monospaced'> PREFERRED_VERSION_python = "2.7.3" - PREFERRED_VERSION_linux-yocto = "3.10%" + PREFERRED_VERSION_linux-yocto = "3.19%" </literallayout> </para> </glossdef> </glossentry> <glossentry id='var-PREMIRRORS'><glossterm>PREMIRRORS</glossterm> + <info> + PREMIRRORS[doc] = "Specifies additional paths from which the OpenEmbedded build system gets source code." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies additional paths from which the OpenEmbedded build system gets source code. When the build system searches for source code, it first @@ -6771,9 +8996,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-PRINC'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The <filename>PRINC</filename> variable has been deprecated and triggers a warning if detected during a build. For @@ -6816,9 +9044,39 @@ 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-PRIORITY'><glossterm>PRIORITY</glossterm> + <info> + PRIORITY[doc] = "Indicates the importance of a package. The default value is 'optional'. Other standard values are 'required', 'standard' and 'extra'." + </info> <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Indicates the importance of a package. + </para> + <para> + <filename>PRIORITY</filename> is considered to be part of + the distribution policy because the importance of any given + recipe depends on the purpose for which the distribution + is being produced. + Thus, <filename>PRIORITY</filename> is not normally set + within recipes. + </para> + + <para> + You can set <filename>PRIORITY</filename> to "required", + "standard", "extra", and "optional", which is the default. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-PRIVATE_LIBS'><glossterm>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 role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies libraries installed within a recipe that should be ignored by the OpenEmbedded build system's shared library resolver. @@ -6849,8 +9107,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-PROVIDES'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> A list of aliases by which a particular recipe can be known. By default, a recipe's own @@ -6878,8 +9140,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-PRSERV_HOST'><glossterm>PRSERV_HOST</glossterm> + <info> + PRSERV_HOST[doc] = "The network based PR service host and port." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The network based <link linkend='var-PR'><filename>PR</filename></link> service host and port. @@ -6904,8 +9170,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-PTEST_ENABLED'><glossterm>PTEST_ENABLED</glossterm> + <info> + PRSERV_HOST[doc] = "Specifies whether or not Package Test (ptest) functionality is enabled when building a recipe." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies whether or not <ulink url='&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest'>Package Test</ulink> (ptest) functionality is enabled when building a recipe. @@ -6919,8 +9189,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-PV'><glossterm>PV</glossterm> + <info> + PV[doc] = "The version of the recipe. The version is normally extracted from the recipe filename." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The version of the recipe. The version is normally extracted from the recipe filename. For example, if the recipe is named @@ -6934,8 +9208,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-PYTHON_ABI'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> When used by recipes that inherit the <link linkend='ref-classes-distutils3'><filename>distutils3</filename></link>, <link linkend='ref-classes-setuptools3'><filename>setuptools3</filename></link>, @@ -6967,8 +9245,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-PYTHON_PN'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> When used by recipes that inherit the <link linkend='ref-classes-distutils3'><filename>distutils3</filename></link>, <link linkend='ref-classes-setuptools3'><filename>setuptools3</filename></link>, @@ -7000,8 +9282,12 @@ 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> + <info> + QMAKE_PROFILES[doc] = "Specifies your own subset of .pro files to be built for use with qmake." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies your own subset of <filename>.pro</filename> files to be built for use with <filename>qmake</filename>. @@ -7024,9 +9310,26 @@ 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-RANLIB'><glossterm>RANLIB</glossterm> + <info> + RANLIB[doc] = "Minimal command and arguments to run 'ranlib'." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + The minimal command and arguments to run + <filename>ranlib</filename>. + </para> + </glossdef> + </glossentry> + <glossentry id='var-RCONFLICTS'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The list of packages that conflict with packages. Note that packages will not be installed if conflicting packages are not first removed. @@ -7037,7 +9340,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} = "<replaceable>another-conflicting-package-name</replaceable>" + RCONFLICTS_${PN} = "<replaceable>another_conflicting_package_name</replaceable>" </literallayout> </para> @@ -7070,8 +9373,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm> + <info> + RDEPENDS[doc] = "Lists a package's runtime dependencies (i.e. other packages) that must be installed for the package to be built. They must be the names of other packages as listed in the PACKAGES variable, not recipe names (PN)." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Lists a package's runtime dependencies (i.e. other packages) that must be installed in order for the built package to run correctly. @@ -7202,8 +9509,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-REQUIRED_DISTRO_FEATURES'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> When inheriting the <link linkend='ref-classes-distro_features_check'><filename>distro_features_check</filename></link> class, this @@ -7221,8 +9532,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-RM_OLD_IMAGE'><glossterm>RM_OLD_IMAGE</glossterm> + <info> + RM_OLD_IMAGE[doc] = "Reclaims disk space by removing previously built versions of the same image from the images directory pointed to by the DEPLOY_DIR variable." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Reclaims disk space by removing previously built versions of the same image from the <filename>images</filename> directory pointed to by the @@ -7239,8 +9554,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-RM_WORK_EXCLUDE'><glossterm>RM_WORK_EXCLUDE</glossterm> + <info> + RM_WORK_EXCLUDE[doc] = "With rm_work enabled, this variable specifies a list of packages whose work directories should not be removed." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> With <filename>rm_work</filename> enabled, this variable specifies a list of recipes whose work directories should not be removed. @@ -7251,8 +9570,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-ROOT_HOME'><glossterm>ROOT_HOME</glossterm> + <info> + ROOT_HOME[doc] = "Defines the root home directory." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Defines the root home directory. By default, this directory is set as follows in the BitBake configuration file: @@ -7284,8 +9607,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-ROOTFS'><glossterm>ROOTFS</glossterm> + <info> + ROOTFS[doc] = "Indicates a filesystem image to include as the root filesystem." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Indicates a filesystem image to include as the root filesystem. </para> @@ -7300,14 +9627,21 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-ROOTFS_POSTPROCESS_COMMAND'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> 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 += "<replaceable>shell_command</replaceable>; ... " </literallayout> + </para> + + <para> If you need to pass the path to the root filesystem within the command, you can use <filename>${IMAGE_ROOTFS}</filename>, which points to @@ -7320,8 +9654,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-RPROVIDES'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> 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 @@ -7332,6 +9670,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <filename>RPROVIDES</filename> list. </note> </para> + <para> As with all package-controlling variables, you must always use the variable in conjunction with a package name override. @@ -7344,8 +9683,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-RRECOMMENDS'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> A list of packages that extends the usability of a package being built. The package being built does not depend on this list of @@ -7433,8 +9776,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-RREPLACES'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> 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) @@ -7444,13 +9791,14 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" package to the <filename><link linkend='var-RCONFLICTS'>RCONFLICTS</link></filename> variable. </para> + <para> As with all package-controlling variables, you must use this variable in conjunction with a package name override. Here is an example: <literallayout class='monospaced'> - RREPLACES_${PN} = "<replaceable>other-package-being-replaced</replaceable>" + RREPLACES_${PN} = "<replaceable>other_package_being_replaced</replaceable>" </literallayout> </para> @@ -7484,20 +9832,25 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-RSUGGESTS'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> 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. </para> + <para> As with all package-controlling variables, you must always use this variable in conjunction with a package name override. Here is an example: <literallayout class='monospaced'> - RSUGGESTS_${PN} = "<replaceable>useful-package</replaceable> <replaceable>another-package</replaceable>" + RSUGGESTS_${PN} = "<replaceable>useful_package</replaceable> <replaceable>another_package</replaceable>" </literallayout> </para> </glossdef> @@ -7508,8 +9861,12 @@ 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> + <info> + S[doc] = "The location in the Build Directory where unpacked package source code resides." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The location in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> where unpacked recipe source code resides. @@ -7524,6 +9881,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <literallayout class='monospaced'> ${WORKDIR}/${PN}-${PV} </literallayout> + </para> + + <para> As an example, assume a <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> top-level folder named <filename>poky</filename> and a @@ -7539,8 +9899,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-SANITY_REQUIRED_UTILITIES'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies a list of command-line utilities that should be checked for during the initial sanity checking process when running BitBake. @@ -7551,8 +9915,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-SANITY_TESTED_DISTROS'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> A list of the host distribution identifiers that the build system has been tested against. Identifiers consist of the host distributor ID @@ -7572,8 +9940,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-SDK_ARCH'><glossterm>SDK_ARCH</glossterm> + <info> + SDK_ARCH[doc] = "The target architecture for the SDK." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The target architecture for the SDK. Typically, you do not directly set this variable. Instead, use @@ -7583,8 +9955,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-SDK_DEPLOY'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The directory set up and used by the <link linkend='ref-classes-populate-sdk'><filename>populate_sdk_base</filename></link> to which the SDK is deployed. @@ -7598,8 +9974,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-SDK_DIR'><glossterm>SDK_DIR</glossterm> + <info> + SDK_DIR[doc] = "The parent directory used by the OpenEmbedded build system when creating SDK output." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The parent directory used by the OpenEmbedded build system when creating SDK output. The @@ -7620,8 +10000,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-SDK_NAME'><glossterm>SDK_NAME</glossterm> + <info> + SDK_NAME[doc] = "The base name for SDK output files." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The base name for SDK output files. The name is derived from the <link linkend='var-DISTRO'><filename>DISTRO</filename></link>, @@ -7638,9 +10022,28 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> + <glossentry id='var-SDK_OS'><glossterm>SDK_OS</glossterm> + <info> + SDK_OS[doc] = "The operating system for which the SDK will be built." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Specifies the operating system for which the SDK + will be built. + The default value is the value of + <link linkend='var-BUILD_OS'><filename>BUILD_OS</filename></link>. + </para> + </glossdef> + </glossentry> + <glossentry id='var-SDK_OUTPUT'><glossterm>SDK_OUTPUT</glossterm> + <info> + SDK_OUTPUT[doc] = "The location used by the OpenEmbedded build system when creating SDK output." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The location used by the OpenEmbedded build system when creating SDK output. The @@ -7657,14 +10060,17 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" The final output directory is <link linkend='var-SDK_DEPLOY'><filename>SDK_DEPLOY</filename></link>. </note> - </para> </glossdef> </glossentry> <glossentry id='var-SDK_PACKAGE_ARCHS'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies a list of architectures compatible with the SDK machine. This variable is set automatically and should not @@ -7678,9 +10084,67 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> + <glossentry id='var-SDK_PREFIX'><glossterm>SDK_PREFIX</glossterm> + <info> + SDK_PREFIX[doc] = "The toolchain binary prefix used for nativesdk recipes." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + The toolchain binary prefix used for nativesdk recipes. + The OpenEmbedded build system uses the + <filename>SDK_PREFIX</filename> value to set the + <link linkend='var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></link> + when building <filename>nativesdk</filename> recipes. + The default value is "${SDK_SYS}-". + </para> + </glossdef> + </glossentry> + + <glossentry id='var-SDK_SYS'><glossterm>SDK_SYS</glossterm> + <info> + SDK_SYS[doc] = "Specifies the system, including the architecture and the operating system, for which the SDK will be built." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Specifies the system, including the architecture and the + operating system, for which the SDK will be built. + </para> + + <para> + The OpenEmbedded build system automatically sets this + variable based on + <link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link>, + <link linkend='var-SDK_VENDOR'><filename>SDK_VENDOR</filename></link>, + and + <link linkend='var-SDK_OS'><filename>SDK_OS</filename></link>. + You do not need to set the <filename>SDK_SYS</filename> + variable yourself. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-SDK_VENDOR'><glossterm>SDK_VENDOR</glossterm> + <info> + SDK_VENDOR[doc] = "Specifies the name of the SDK vendor." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Specifies the name of the SDK vendor. + </para> + </glossdef> + </glossentry> + <glossentry id='var-SDKIMAGE_FEATURES'><glossterm>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 + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + 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: @@ -7692,8 +10156,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-SDKMACHINE'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The machine for which the Application Development Toolkit (ADT) or SDK is built. In other words, the SDK or ADT is built such that it @@ -7721,8 +10189,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-SDKPATH'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Defines the path offered to the user for installation of the SDK that is generated by the OpenEmbedded build system. @@ -7734,16 +10206,41 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> + <glossentry id='var-SDKTARGETSYSROOT'><glossterm>SDKTARGETSYSROOT</glossterm> + <info> + SDKTARGETSYSROOT[doc] = "Full path to the sysroot used for cross-compilation within an SDK as it will be when installed into the default SDKPATH." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + The full path to the sysroot used for cross-compilation + within an SDK as it will be when installed into the + default + <link linkend='var-SDKPATH'><filename>SDKPATH</filename></link>. + </para> + </glossdef> + </glossentry> + <glossentry id='var-SECTION'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + 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> + <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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the optimization flags passed to the C compiler when building for the target. The flags are passed through the default value of the @@ -7763,8 +10260,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-SERIAL_CONSOLE'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Defines a serial console (TTY) to enable using getty. Provide a value that specifies the baud rate followed by the TTY device name separated by a space. @@ -7784,8 +10285,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-SERIAL_CONSOLES'><glossterm>SERIAL_CONSOLES</glossterm> + <info> + SERIAL_CONSOLES[doc] = "Defines the serial consoles (TTYs) to enable using getty." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Defines the serial consoles (TTYs) to enable using getty. Provide a value that specifies the baud rate followed by the TTY device name separated by a semicolon. @@ -7798,8 +10303,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-SERIAL_CONSOLES_CHECK'><glossterm>SERIAL_CONSOLES_CHECK</glossterm> + <info> + SERIAL_CONSOLES_CHECK[doc] = "Similar to SERIAL_CONSOLES except the device is checked for existence before attempting to enable it. Supported only by SysVinit." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Similar to <link linkend='var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></link> except the device is checked for existence before attempting @@ -7811,8 +10320,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> 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. @@ -7820,6 +10333,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <literallayout class='monospaced'> SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "intone->mplayer2" </literallayout> + </para> + + <para> In this example, <filename>intone</filename> depends on <filename>mplayer2</filename>. </para> @@ -7839,8 +10355,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-SIGGEN_EXCLUDERECIPES_ABISAFE'><glossterm>SIGGEN_EXCLUDERECIPES_ABISAFE</glossterm> + <info> + SIGGEN_EXCLUDERECIPES_ABISAFE[doc] = "A list of recipes that are completely stable and will never change." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> A list of recipes that are completely stable and will never change. The ABI for the recipes in the list are presented by @@ -7859,8 +10379,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-SITEINFO_BITS'><glossterm>SITEINFO_BITS</glossterm> + <info> + SITEINFO_BITS[doc] = "Specifies the number of bits for the target system CPU." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the number of bits for the target system CPU. The value should be either "32" or "64". </para> @@ -7868,8 +10392,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-SITEINFO_ENDIANNESS'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the endian byte order of the target system. The value should be either "le" for little-endian or "be" for big-endian. </para> @@ -7877,8 +10405,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-SOC_FAMILY'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Groups together machines based upon the same family of SOC (System On Chip). You typically set this variable in a common @@ -7888,15 +10420,19 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" You must include <filename>conf/machine/include/soc-family.inc</filename> for this variable to appear in - <link linkend='var-MACHINEOVERRIDES'><filename>MACHINEOVERRIDES</filename></link>. + <link linkend='var-MACHINEOVERRIDES'><filename>MACHINEOVERRIDES</filename></link>. </note> </para> </glossdef> </glossentry> <glossentry id='var-SOLIBS'><glossterm>SOLIBS</glossterm> + <info> + SOLIBS[doc] = "Defines the suffix for shared libraries used on the target platform." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Defines the suffix for shared libraries used on the target platform. By default, this suffix is ".so.*" for all Linux-based @@ -7913,8 +10449,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-SOLIBSDEV'><glossterm>SOLIBSDEV</glossterm> + <info> + SOLIBSDEV[doc] = "Defines the suffix for the development symbolic link (symlink) for shared libraries on the target platform." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Defines the suffix for the development symbolic link (symlink) for shared libraries on the target platform. By default, this suffix is ".so" for Linux-based @@ -7930,9 +10470,45 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> + <glossentry id='var-SOURCE_MIRROR_FETCH'><glossterm>SOURCE_MIRROR_FETCH</glossterm> + <info> + SOURCE_MIRROR_FETCH[doc] = "Set as part of a source mirror generation script to skip COMPATIBLE_MACHINE and COMPATIBLE_HOST checks." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + When you are fetching files to create a mirror of sources + (i.e. creating a source mirror), setting + <filename>SOURCE_MIRROR_FETCH</filename> to "1" in your + <filename>local.conf</filename> configuration file ensures + the source for all recipes are fetched regardless of + whether or not a recipe is compatible with the + configuration. + A recipe is considered incompatible with the currently + configured machine when either or both the + <link linkend='var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></link> + variable and + <link linkend='var-COMPATIBLE_HOST'><filename>COMPATIBLE_HOST</filename></link> + variables specify compatibility with a machine other + than that of the current machine or host. + <note><title>Warning</title> + Do not set the + <filename>SOURCE_MIRROR_FETCH</filename> variable + unless you are creating a source mirror. + In other words, do not set the variable during a + normal build. + </note> + </para> + </glossdef> + </glossentry> + <glossentry id='var-SOURCE_MIRROR_URL'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Defines your own <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link> from which to first fetch source before attempting to fetch @@ -7944,10 +10520,10 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" To use this variable, you must globally inherit the <link linkend='ref-classes-own-mirrors'><filename>own-mirrors</filename></link> class and then provide the URL to your mirrors. - Here is an example: + Here is the general syntax: <literallayout class='monospaced'> INHERIT += "own-mirrors" - SOURCE_MIRROR_URL = "http://example.com/my-source-mirror" + SOURCE_MIRROR_URL = "http://<replaceable>example</replaceable>.com/<replaceable>my_source_mirror</replaceable>" </literallayout> <note> You can specify only a single URL in @@ -7958,8 +10534,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-SPDXLICENSEMAP'><glossterm>SPDXLICENSEMAP</glossterm> + <info> + SPDXLICENSEMAP[doc] = "Maps commonly used license names to their SPDX counterparts found in meta/files/common-licenses/." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Maps commonly used license names to their SPDX counterparts found in <filename>meta/files/common-licenses/</filename>. For the default <filename>SPDXLICENSEMAP</filename> @@ -7976,8 +10556,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-SPECIAL_PKGSUFFIX'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> A list of prefixes for <link linkend='var-PN'><filename>PN</filename></link> used by the OpenEmbedded build system to create variants of recipes or packages. The list specifies the prefixes to strip off during certain circumstances @@ -7987,8 +10571,13 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-SRC_URI'><glossterm>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. + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + The list of source files - local or remote. This variable tells the OpenEmbedded build system which bits to pull in for the build and how to pull them in. For example, if the recipe or append file only needs to @@ -7998,8 +10587,11 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" On the other hand, if the recipe or append file needs to fetch a tarball, apply two patches, and include a custom file, the recipe or append file would include four - instances of the variable.</para> - <para>The following list explains the available URI protocols: + instances of the variable. + </para> + + <para> + The following list explains the available URI protocols: <itemizedlist> <listitem><para><emphasis><filename>file://</filename> -</emphasis> Fetches files, which are usually files shipped with @@ -8072,7 +10664,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" a Subversion (<filename>svn</filename>) revision control repository.</para></listitem> </itemizedlist> </para> - <para>Standard and recipe-specific options for <filename>SRC_URI</filename> exist. + + <para> + Standard and recipe-specific options for <filename>SRC_URI</filename> exist. Here are standard options: <itemizedlist> <listitem><para><emphasis><filename>apply</filename> -</emphasis> Whether to apply @@ -8087,7 +10681,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </para></listitem> </itemizedlist> </para> - <para>Here are options specific to recipes building code from a revision control system: + + <para> + Here are options specific to recipes building code from a revision control system: <itemizedlist> <listitem><para><emphasis><filename>mindate</filename> -</emphasis> Apply the patch only if @@ -8116,7 +10712,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </para></listitem> </itemizedlist> </para> - <para>Here are some additional options worth mentioning: + + <para> + Here are some additional options worth mentioning: <itemizedlist> <listitem><para><emphasis><filename>unpack</filename> -</emphasis> Controls whether or not to unpack the file if it is an archive. @@ -8139,8 +10737,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'><glossterm>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 role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> By default, the OpenEmbedded build system automatically detects whether <filename><link linkend='var-SRC_URI'>SRC_URI</link></filename> contains files that are machine-specific. @@ -8152,8 +10754,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-SRCDATE'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> 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). </para> @@ -8161,8 +10767,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-SRCPV'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Returns the version string of the current package. This string is used to help define the value of <link linkend='var-PV'><filename>PV</filename></link>. @@ -8195,28 +10805,51 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-SRCREV'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The revision of the source code used to build the package. - This variable applies to Subversion, Git, Mercurial and Bazaar - only. - Note that if you wish to build a fixed revision and you wish - to avoid performing a query on the remote repository every time - BitBake parses your recipe, you should specify a <filename>SRCREV</filename> that is a + This variable applies to Subversion, Git, Mercurial and + Bazaar only. + Note that if you want to build a fixed revision and you + want to avoid performing a query on the remote repository + every time BitBake parses your recipe, you should specify + a <filename>SRCREV</filename> that is a full revision identifier and not just a tag. </para> + + <note> + For information on limitations when inheriting the latest + revision of software using <filename>SRCREV</filename>, + see the + <link linkend='var-AUTOREV'><filename>AUTOREV</filename></link> + variable description. + </note> </glossdef> </glossentry> <glossentry id='var-SSTATE_DIR'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + The directory for the shared state cache. + </para> </glossdef> </glossentry> <glossentry id='var-SSTATE_MIRROR_ALLOW_NETWORK'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> If set to "1", allows fetches from mirrors that are specified in <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link> @@ -8234,8 +10867,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-SSTATE_MIRRORS'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Configures the OpenEmbedded build system to search other mirror locations for prebuilt cache data objects before building out the data. @@ -8272,8 +10909,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-STAGING_BASE_LIBDIR_NATIVE'><glossterm>STAGING_BASE_LIBDIR_NATIVE</glossterm> + <info> + STAGING_BASE_LIBDIR_NATIVE[doc] = "Specifies the path to the /lib subdirectory of the sysroot directory for the build host." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the path to the <filename>/lib</filename> subdirectory of the sysroot directory for the build host. @@ -8282,8 +10923,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-STAGING_BASELIBDIR'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the path to the <filename>/lib</filename> subdirectory of the sysroot directory for the target for which the current recipe is being built @@ -8293,8 +10938,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-STAGING_BINDIR'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the path to the <filename>/usr/bin</filename> subdirectory of the sysroot directory for the target for which the current @@ -8305,8 +10954,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-STAGING_BINDIR_CROSS'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the path to the directory containing binary configuration scripts. These scripts provide configuration information for @@ -8327,8 +10980,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-STAGING_BINDIR_NATIVE'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the path to the <filename>/usr/bin</filename> subdirectory of the sysroot directory for the build host. @@ -8337,8 +10994,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-STAGING_DATADIR'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the path to the <filename>/usr/share</filename> subdirectory of the sysroot directory for the target for which the current recipe is being built @@ -8347,9 +11008,26 @@ 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> + <info> + STAGING_DATADIR_NATIVE[doc] = "Specifies the path to the /usr/share subdirectory of the sysroot directory for the build host." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + 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>STAGING_DIR</glossterm> + <info> + STAGING_DIR[doc] = "Specifies the path to the top-level sysroots directory (i.e. ${TMPDIR}/sysroots)." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the path to the top-level sysroots directory (i.e. <filename>${</filename><link linkend='var-TMPDIR'><filename>TMPDIR</filename></link><filename>}/sysroots</filename>). @@ -8369,8 +11047,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-STAGING_DIR_HOST'><glossterm>STAGING_DIR_HOST</glossterm> + <info> + STAGING_DIR_HOST[doc] = "Specifies the path to the primary sysroot directory for which the target is being built." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the path to the primary sysroot directory for which the target is being built. Depending on the type of recipe and the build target, the @@ -8386,7 +11068,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" the build host's own directories should be used. </para></listitem> <listitem><para>For <filename>nativesdk</filename> - recipes that Build for the SDK, the value is + recipes that build for the SDK, the value is "${STAGING_DIR}/${MULTIMACH_HOST_SYS}". </para></listitem> </itemizedlist> @@ -8394,20 +11076,13 @@ 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> + <info> + STAGING_DIR_NATIVE[doc] = "Specifies the path to the sysroot directory for the build host." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the path to the sysroot directory for the build host. </para> @@ -8415,8 +11090,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-STAGING_DIR_TARGET'><glossterm>STAGING_DIR_TARGET</glossterm> + <info> + STAGING_DIR_TARGET[doc] = "Specifies the path to the sysroot directory for the target for which the current recipe is being built." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the path to the sysroot directory for the target for which the current recipe is being built. In most cases, this path is the @@ -8439,8 +11118,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-STAGING_ETCDIR_NATIVE'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the path to the <filename>/etc</filename> subdirectory of the sysroot directory for the build host. @@ -8449,8 +11132,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-STAGING_EXECPREFIXDIR'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the path to the <filename>/usr</filename> subdirectory of the sysroot directory for the target for which the current recipe is being built @@ -8460,8 +11147,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-STAGING_INCDIR'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the path to the <filename>/usr/include</filename> subdirectory of the sysroot directory for the target for which the current @@ -8472,17 +11163,38 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-STAGING_INCDIR_NATIVE'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the path to the <filename>/usr/include</filename> subdirectory of the sysroot directory for the build host. </para> </glossdef> </glossentry> + <glossentry id='var-STAGING_KERNEL_DIR'><glossterm>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 role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + The directory with kernel headers that are required to build out-of-tree + modules. + </para> + </glossdef> + </glossentry> + <glossentry id='var-STAGING_LIBDIR'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> 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 @@ -8492,26 +11204,25 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-STAGING_LIBDIR_NATIVE'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the path to the <filename>/usr/lib</filename> subdirectory of the sysroot directory for the build host. </para> </glossdef> </glossentry> - <glossentry id='var-STAGING_KERNEL_DIR'><glossterm>STAGING_KERNEL_DIR</glossterm> - <glossdef> - <para> - The directory with kernel headers that are required to build out-of-tree - modules. - </para> - </glossdef> - </glossentry> - <glossentry id='var-STAMP'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> 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. @@ -8521,6 +11232,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <literallayout class='monospaced'> STAMP = "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}" </literallayout> + </para> + + <para> See <link linkend='var-STAMPS_DIR'><filename>STAMPS_DIR</filename></link>, <link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>, <link linkend='var-PN'><filename>PN</filename></link>, @@ -8533,8 +11247,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-STAMPS_DIR'><glossterm>STAMPS_DIR</glossterm> + <info> + STAMPS_DIR[doc] = "Specifies the base directory in which the OpenEmbedded build system places stamps." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the base directory in which the OpenEmbedded build system places stamps. The default directory is @@ -8543,9 +11261,28 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> + <glossentry id='var-STRIP'><glossterm>STRIP</glossterm> + <info> + STRIP[doc] = "Minimal command and arguments to run 'strip' (strip symbols)." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + The minimal command and arguments to run + <filename>strip</filename>, which is used to strip + symbols. + </para> + </glossdef> + </glossentry> + <glossentry id='var-SUMMARY'><glossterm>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 + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + The short (72 characters or less) summary of the binary package for packaging systems such as <filename>opkg</filename>, <filename>rpm</filename> or <filename>dpkg</filename>. By default, <filename>SUMMARY</filename> is used to define @@ -8556,9 +11293,26 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> + <glossentry id='var-SVNDIR'><glossterm>SVNDIR</glossterm> + <info> + SVNDIR[doc] = "The directory where Subversion checkouts will be stored." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + The directory in which files checked out of a Subversion + system are stored. + </para> + </glossdef> + </glossentry> + <glossentry id='var-SYSLINUX_DEFAULT_CONSOLE'><glossterm>SYSLINUX_DEFAULT_CONSOLE</glossterm> + <info> + SYSLINUX_DEFAULT_CONSOLE[doc] = "Specifies the kernel boot default console." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the kernel boot default console. If you want to use a console other than the default, set this variable in your recipe as follows where "X" is @@ -8578,8 +11332,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-SYSLINUX_OPTS'><glossterm>SYSLINUX_OPTS</glossterm> + <info> + SYSLINUX_OPTS[doc] = "Lists additional options to add to the syslinux file." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Lists additional options to add to the syslinux file. You need to set this variable in your recipe. If you want to list multiple options, separate the options @@ -8595,8 +11353,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-SYSLINUX_SERIAL'><glossterm>SYSLINUX_SERIAL</glossterm> + <info> + SYSLINUX_SERIAL[doc] = "Specifies the alternate serial port or turns it off." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the alternate serial port or turns it off. To turn off serial, set this variable to an empty string in your recipe. @@ -8606,13 +11368,21 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <literallayout class='monospaced'> SYSLINUX_SERIAL ?= "0 115200" </literallayout> - The class checks for and uses the variable as needed. </para> + </para> + + <para> + The class checks for and uses the variable as needed. + </para> </glossdef> </glossentry> <glossentry id='var-SYSLINUX_SPLASH'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> An <filename>.LSS</filename> file used as the background for the VGA boot menu when you are using the boot menu. You need to set this variable in your recipe. @@ -8628,8 +11398,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-SYSLINUX_SERIAL_TTY'><glossterm>SYSLINUX_SERIAL_TTY</glossterm> + <info> + SYSLINUX_SERIAL_TTY[doc] = "Specifies the alternate console=tty... kernel boot argument." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the alternate console=tty... kernel boot argument. The variable's default value is set in the <link linkend='ref-classes-syslinux'><filename>syslinux</filename></link> @@ -8637,14 +11411,21 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <literallayout class='monospaced'> SYSLINUX_SERIAL_TTY ?= "console=ttyS0,115200" </literallayout> + </para> + + <para> The class checks for and uses the variable as needed. </para> </glossdef> </glossentry> <glossentry id='var-SYSROOT_PREPROCESS_FUNCS'><glossterm>SYSROOT_PREPROCESS_FUNCS</glossterm> + <info> + SYSROOT_PREPROCESS_FUNCS[doc] = "A list of functions to execute after files are staged into the sysroot. These functions are usually used to apply additional processing on the staged files, or to stage additional files." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> A list of functions to execute after files are staged into the sysroot. These functions are usually used to apply additional @@ -8655,8 +11436,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-SYSTEMD_AUTO_ENABLE'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> When inheriting the <link linkend='ref-classes-systemd'><filename>systemd</filename></link> class, this variable specifies whether the service you have @@ -8671,6 +11456,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <literallayout class='monospaced'> SYSTEMD_AUTO_ENABLE ??= "enable" </literallayout> + </para> + + <para> You can disable the service by setting the variable to "disable". </para> @@ -8678,8 +11466,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-SYSTEMD_PACKAGES'><glossterm>SYSTEMD_PACKAGES</glossterm> + <info> + SYSTEMD_PACKAGES[doc] = "For recipes that inherit the systemd class, this variable locates the systemd unit files when they are not found in the main recipe's package." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> When inheriting the <link linkend='ref-classes-systemd'><filename>systemd</filename></link> class, this variable locates the systemd unit files when @@ -8691,6 +11483,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <literallayout class='monospaced'> SYSTEMD_PACKAGES ?= "${PN}" </literallayout> + </para> + + <para> If these unit files are not in this recipe's main package, you need to use <filename>SYSTEMD_PACKAGES</filename> to list the package @@ -8701,8 +11496,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-SYSTEMD_SERVICE'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> When inheriting the <link linkend='ref-classes-systemd'><filename>systemd</filename></link> class, this variable specifies the systemd service name for @@ -8722,8 +11521,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-SYSVINIT_ENABLED_GETTYS'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> When using <ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-enabling-system-services'>SysVinit</ulink>, specifies a space-separated list of the virtual terminals @@ -8747,14 +11550,22 @@ 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> + <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 + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + This variable points to a directory were BitBake places temporary files, which consist mostly of task logs and scripts, when building a particular recipe. The variable is typically set as follows: <literallayout class='monospaced'> T = "${WORKDIR}/temp" </literallayout> + </para> + + <para> The <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link> is the directory into which BitBake unpacks and builds the recipe. @@ -8768,8 +11579,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-TARGET_ARCH'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The target machine's architecture. The OpenEmbedded build system supports many architectures. @@ -8785,6 +11600,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" mips mipsel </literallayout> + </para> + + <para> For additional information on machine architectures, see the <link linkend='var-TUNE_ARCH'><filename>TUNE_ARCH</filename></link> @@ -8794,8 +11612,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-TARGET_AS_ARCH'><glossterm>TARGET_AS_ARCH</glossterm> + <info> + TARGET_AS_ARCH[doc] = "Specifies architecture-specific assembler flags for the target system." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies architecture-specific assembler flags for the target system. <filename>TARGET_AS_ARCH</filename> is initialized from @@ -8810,8 +11632,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-TARGET_CC_ARCH'><glossterm>TARGET_CC_ARCH</glossterm> + <info> + TARGET_CC_ARCH[doc] = "Specifies architecture-specific C compiler flags for the target system." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies architecture-specific C compiler flags for the target system. <filename>TARGET_CC_ARCH</filename> is initialized from @@ -8830,8 +11656,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-TARGET_CC_KERNEL_ARCH'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> This is a specific kernel compiler flag for a CPU or Application Binary Interface (ABI) tune. The flag is used rarely and only for cases where a @@ -8851,8 +11681,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-TARGET_CFLAGS'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the flags to pass to the C compiler when building for the target. When building in the target context, @@ -8873,8 +11707,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-TARGET_CPPFLAGS'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> 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. @@ -8896,8 +11734,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-TARGET_CXXFLAGS'><glossterm>TARGET_CXXFLAGS</glossterm> + <info> + TARGET_CXXFLAGS[doc] = "Specifies the flags to pass to the C++ compiler when building for the target." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the flags to pass to the C++ compiler when building for the target. When building in the target context, @@ -8918,17 +11760,27 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-TARGET_FPU'><glossterm>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. + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + 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.</para> + If not, the kernel emulation gets used, which results in a performance penalty. + </para> </glossdef> </glossentry> <glossentry id='var-TARGET_LD_ARCH'><glossterm>TARGET_LD_ARCH</glossterm> + <info> + TARGET_LD_ARCH[doc] = "Specifies architecture-specific linker flags for the target system." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies architecture-specific linker flags for the target system. <filename>TARGET_LD_ARCH</filename> is initialized from @@ -8943,8 +11795,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-TARGET_LDFLAGS'><glossterm>TARGET_LDFLAGS</glossterm> + <info> + TARGET_LDFLAGS[doc] = "Specifies the flags to pass to the linker when building for the target." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the flags to pass to the linker when building for the target. When building in the target context, @@ -8965,36 +11821,169 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-TARGET_OS'><glossterm>TARGET_OS</glossterm> - <glossdef> - <para>Specifies the target's operating system. - The variable can be set to "linux" for <filename>eglibc</filename>-based systems and + <info> + TARGET_OS[doc] = "Specifies the target's operating system." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Specifies the target's operating system. + The variable can be set to "linux" for <filename>glibc</filename>-based systems and to "linux-uclibc" for <filename>uclibc</filename>. For ARM/EABI targets, there are also "linux-gnueabi" and - "linux-uclibc-gnueabi" values possible.</para> + "linux-uclibc-gnueabi" values possible. + </para> </glossdef> </glossentry> - <glossentry id='var-TCLIBC'><glossterm>TCLIBC</glossterm> + <glossentry id='var-TARGET_PREFIX'><glossterm>TARGET_PREFIX</glossterm> + <info> + TARGET_PREFIX[doc] = "The prefix used for the toolchain binary target tools." + </info> <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Specifies the prefix used for the toolchain binary target + tools. + </para> + <para> + Depending on the type of recipe and the build target, + <filename>TARGET_PREFIX</filename> is set as follows: + <itemizedlist> + <listitem><para> + For recipes building for the target machine, + the value is + "${<link linkend='var-TARGET_SYS'>TARGET_SYS</link>}-". + </para></listitem> + <listitem><para> + For <filename>native</filename> recipes, the build + system sets the variable to the value of + <filename>BUILD_PREFIX</filename>. + </para></listitem> + <listitem><para> + For <filename>nativesdk</filename> recipes, the + build system sets the variable to the value of + <filename>SDK_PREFIX</filename>. + </para></listitem> + </itemizedlist> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-TARGET_SYS'><glossterm>TARGET_SYS</glossterm> + <info> + TARGET_SYS[doc] = "The target system is comprised of TARGET_ARCH,TARGET_VENDOR and TARGET_OS." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Specifies the system, including the architecture and the + operating system, for which the build is occurring in + the context of the current recipe. + </para> + + <para> + The OpenEmbedded build system automatically sets this + variable based on + <link linkend='var-TARGET_ARCH'><filename>TARGET_ARCH</filename></link>, + <link linkend='var-TARGET_VENDOR'><filename>TARGET_VENDOR</filename></link>, + and + <link linkend='var-TARGET_OS'><filename>TARGET_OS</filename></link> + variables. + <note> + You do not need to set the + <filename>TARGET_SYS</filename> variable yourself. + </note> + </para> + + <para> + Consider these two examples: + <itemizedlist> + <listitem><para> + Given a <filename>native</filename> recipe on a + 32-bit, x86 machine running Linux, the value is + "i686-linux". + </para></listitem> + <listitem><para> + Given a recipe being built for a little-endian, + MIPS target running Linux, the value might be + "mipsel-linux". + </para></listitem> + </itemizedlist> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-TARGET_VENDOR'><glossterm>TARGET_VENDOR</glossterm> + <info> + TARGET_VENDOR[doc] = "The name of the target vendor." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Specifies the name of the target vendor. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-TCLIBCAPPEND'><glossterm>TCLIBCAPPEND</glossterm> + <info> + TCLIBCAPPEND[doc] = "Specifies a suffix appended to TMPDIR that identifies the libc variant for the build." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Specifies a suffix to be appended onto the + <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> + value. + The suffix identifies the <filename>libc</filename> variant + for building. + When you are building for multiple variants with the same + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>, + this mechanism ensures that output for different + <filename>libc</filename> variants is kept separate to + avoid potential conflicts. + </para> + + <para> + In the <filename>defaultsetup.conf</filename> file, the + default value of <filename>TCLIBCAPPEND</filename> is + "-${TCLIBC}". + However, distros such as poky, which normally only support + one <filename>libc</filename> variant, set + <filename>TCLIBCAPPEND</filename> to "" in their distro + configuration file resulting in no suffix being applied. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-TCLIBC'><glossterm>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 role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the GNU standard C library (<filename>libc</filename>) variant to use during the build process. This variable replaces <filename>POKYLIBC</filename>, which is no longer supported. </para> + <para> - You can select "eglibc" or "uclibc". - <note> - This release of the Yocto Project does not support the - <filename>glibc</filename> implementation of <filename>libc</filename>. - </note> + You can select "glibc" or "uclibc". </para> </glossdef> </glossentry> <glossentry id='var-TCMODE'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the toolchain selector. <filename>TCMODE</filename> controls the characteristics of the generated packages and images by telling the @@ -9018,41 +12007,51 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </para> <para> + The <filename>TCMODE</filename> variable is similar to + <link linkend='var-TCLIBC'><filename>TCLIBC</filename></link>, + which controls the variant of the GNU standard C library + (<filename>libc</filename>) used during the build process: + <filename>glibc</filename> or <filename>uclibc</filename>. + </para> + + <para> With additional layers, it is possible to use a pre-compiled external toolchain. One example is the Sourcery G++ Toolchain. The support for this toolchain resides in the separate + <trademark class='registered'>Mentor Graphics</trademark> <filename>meta-sourcery</filename> layer at <ulink url='http://github.com/MentorEmbedded/meta-sourcery/'></ulink>. - You can use <filename>meta-sourcery</filename> as a - template for adding support for other external toolchains. </para> <para> - The <filename>TCMODE</filename> variable points the build - system to a file in - <filename>conf/distro/include/tcmode-${TCMODE}.inc</filename>. - Thus, for <filename>meta-sourcery</filename>, - which has <filename>conf/distro/include/tcmode-external-sourcery.inc</filename>, - you would set the variable as follows: - <literallayout class='monospaced'> - TCMODE ?= "external-sourcery" - </literallayout> + The layer's <filename>README</filename> file contains + information on how to use the Sourcery G++ Toolchain as + an external toolchain. + In summary, you must be sure to add the layer to your + <filename>bblayers.conf</filename> file in front of the + <filename>meta</filename> layer and then set the + <filename>EXTERNAL_TOOLCHAIN</filename> + variable in your <filename>local.conf</filename> file + to the location in which you installed the toolchain. </para> <para> - The variable is similar to - <link linkend='var-TCLIBC'><filename>TCLIBC</filename></link>, - which controls the variant of the GNU standard C library - (<filename>libc</filename>) used during the build process: - <filename>eglibc</filename> or <filename>uclibc</filename>. + The fundamentals used for this example apply to any + external toolchain. + You can use <filename>meta-sourcery</filename> as a + template for adding support for other external toolchains. </para> </glossdef> </glossentry> <glossentry id='var-TEST_EXPORT_DIR'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The location the OpenEmbedded build system uses to export tests when the <link linkend='var-TEST_EXPORT_ONLY'><filename>TEST_EXPORT_ONLY</filename></link> @@ -9067,8 +12066,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-TEST_EXPORT_ONLY'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> 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 @@ -9078,8 +12081,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-TEST_IMAGE'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Automatically runs the series of automated tests for images when an image is successfully built. </para> @@ -9108,8 +12115,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-TEST_LOG_DIR'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Holds the SSH log and the boot log for QEMU machines. The <filename>TEST_LOG_DIR</filename> variable defaults to <filename>"${WORKDIR}/testimage"</filename>. @@ -9123,8 +12134,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-TEST_POWERCONTROL_CMD'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> 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 @@ -9139,8 +12154,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-TEST_POWERCONTROL_EXTRA_ARGS'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> 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>. @@ -9154,8 +12173,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-TEST_QEMUBOOT_TIMEOUT'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The time in seconds allowed for an image to boot before automated runtime tests begin to run against an image. @@ -9174,8 +12197,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-TEST_SERIALCONTROL_CMD'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> For automated hardware testing, specifies the command to use to connect to the serial console of the target machine under test. @@ -9196,8 +12223,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-TEST_SERIALCONTROL_EXTRA_ARGS'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> 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>. @@ -9211,8 +12242,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-TEST_SERVER_IP'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The IP address of the build machine (host machine). This IP address is usually automatically detected. However, if detection fails, this variable needs to be set @@ -9229,14 +12264,21 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-TEST_TARGET'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the target controller to use when running tests against a test image. The default controller to use is "qemu": <literallayout class='monospaced'> TEST_TARGET = "qemu" </literallayout> + </para> + + <para> A target controller is a class that defines how an image gets deployed on a target and how a target is started. A layer can extend the controllers by adding a module @@ -9294,8 +12336,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-TEST_TARGET_IP'><glossterm>TEST_TARGET_IP</glossterm> + <info> + TEST_TARGET_IP[doc] = "The IP address of your hardware under test." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The IP address of your hardware under test. The <filename>TEST_TARGET_IP</filename> variable has no effect when @@ -9320,8 +12366,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-TEST_SUITES'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> An ordered list of tests (modules) to run against an image when performing automated runtime testing. </para> @@ -9375,8 +12425,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-THISDIR'><glossterm>THISDIR</glossterm> + <info> + THISDIR[doc] = "The directory in which the file BitBake is currently parsing is located." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The directory in which the file BitBake is currently parsing is located. Do not manually set this variable. @@ -9384,9 +12438,28 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> + <glossentry id='var-TIME'><glossterm>TIME</glossterm> + <info> + TIME[doc] = "The time the build was started using HMS format." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + The time the build was started. + Times appear using the hour, minute, and second (HMS) + format (e.g. "140159" for one minute and fifty-nine + seconds past 1400 hours). + </para> + </glossdef> + </glossentry> + <glossentry id='var-TMPDIR'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> This variable is the base directory the OpenEmbedded build system uses for all build output and intermediate files (other than the shared state cache). @@ -9423,8 +12496,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-TOOLCHAIN_HOST_TASK'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> This variable lists packages the OpenEmbedded build system uses when building an SDK, which contains a cross-development environment. @@ -9453,8 +12530,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-TOOLCHAIN_TARGET_TASK'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> This variable lists packages the OpenEmbedded build system uses when it creates the target part of an SDK (i.e. the part built for the target hardware), which @@ -9475,8 +12556,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-TOPDIR'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The top-level <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. BitBake automatically sets this variable when you @@ -9489,8 +12574,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-TRANSLATED_TARGET_ARCH'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> A sanitized version of <link linkend='var-TARGET_ARCH'><filename>TARGET_ARCH</filename></link>. This variable is used where the architecture is needed in @@ -9507,8 +12596,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-TUNE_ARCH'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The GNU canonical architecture for a specific architecture (i.e. <filename>arm</filename>, <filename>armeb</filename>, @@ -9562,15 +12655,20 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-TUNE_ASARGS'><glossterm>TUNE_ASARGS</glossterm> + <info> + TUNE_ASARGS[doc] = "Specifies architecture-specific assembler flags for the target system." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies architecture-specific assembler flags for the target system. The set of flags is based on the selected tune features. <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: @@ -9578,41 +12676,55 @@ 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> + <info> + TUNE_CCARGS[doc] = "Specifies architecture-specific C compiler flags for the target system." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies architecture-specific C compiler flags for the target system. The set of flags is based on the selected tune features. <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> + <info> + TUNE_LDARGS[doc] = "Specifies architecture-specific linker flags for the target system." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies architecture-specific linker flags for the target system. The set of flags is based on the selected tune features. <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: @@ -9620,16 +12732,22 @@ 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> + <info> + TUNE_FEATURES[doc] = "Features used to "tune" a compiler for optimal use given a specific processor." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Features used to "tune" a compiler for optimal use given a specific processor. The features are defined within the tune files and allow @@ -9658,21 +12776,20 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-TUNE_PKGARCH'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> 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> @@ -9690,8 +12807,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-TUNEABI'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> An underlying Application Binary Interface (ABI) used by a particular tuning in a given toolchain layer. Providers that use prebuilt libraries can use the @@ -9714,8 +12835,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-TUNEABI_OVERRIDE'><glossterm>TUNEABI_OVERRIDE</glossterm> + <info> + TUNEABI_OVERRIDE[doc] = "If set, ignores TUNEABI_WHITELIST." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> If set, the OpenEmbedded system ignores the <link linkend='var-TUNEABI_WHITELIST'><filename>TUNEABI_WHITELIST</filename></link> variable. @@ -9737,8 +12862,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-TUNEABI_WHITELIST'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> A whitelist of permissible <link linkend='var-TUNEABI'><filename>TUNEABI</filename></link> values. @@ -9760,9 +12889,13 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-TUNECONFLICT'><glossterm>TUNECONFLICT[<replaceable>feature</replaceable>]</glossterm> + <glossentry id='var-TUNECONFLICTS'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies CPU or Application Binary Interface (ABI) tuning features that conflict with <replaceable>feature</replaceable>. </para> @@ -9783,8 +12916,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-TUNEVALID'><glossterm>TUNEVALID[<replaceable>feature</replaceable>]</glossterm> + <info> + TUNEVALID[doc] = "Descriptions, stored as flags, of valid tuning features." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies a valid CPU or Application Binary Interface (ABI) tuning feature. The specified feature is stored as a flag. @@ -9794,6 +12931,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <literallayout class='monospaced'> TUNEVALID[bigendian] = "Enable big-endian mode." </literallayout> + </para> + + <para> See the machine include files in the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> for these features. @@ -9806,8 +12946,12 @@ 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> + <info> + UBOOT_CONFIG[doc] = "Configures the UBOOT_MACHINE and can also define IMAGE_FSTYPES for individual cases." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Configures the <link linkend='var-UBOOT_MACHINE'><filename>UBOOT_MACHINE</filename></link> and can also define @@ -9845,8 +12989,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-UBOOT_ENTRYPOINT'><glossterm>UBOOT_ENTRYPOINT</glossterm> + <info> + UBOOT_ENTRYPOINT[doc] = "Specifies the entry point for the U-Boot image." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the entry point for the U-Boot image. During U-Boot image creation, the <filename>UBOOT_ENTRYPOINT</filename> variable is passed @@ -9857,8 +13005,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-UBOOT_LOADADDRESS'><glossterm>UBOOT_LOADADDRESS</glossterm> + <info> + UBOOT_LOADADDRESS[doc] = "Specifies the load address for the U-Boot image." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the load address for the U-Boot image. During U-Boot image creation, the <filename>UBOOT_LOADADDRESS</filename> variable is passed @@ -9869,8 +13021,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-UBOOT_LOCALVERSION'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Appends a string to the name of the local version of the U-Boot image. For example, assuming the version of the U-Boot image @@ -9885,8 +13041,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-UBOOT_MACHINE'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the value passed on the <filename>make</filename> command line when building a U-Boot image. @@ -9905,8 +13065,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-UBOOT_MAKE_TARGET'><glossterm>UBOOT_MAKE_TARGET</glossterm> + <info> + UBOOT_MAKE_TARGET[doc] = "Specifies the target called in the Makefile." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the target called in the <filename>Makefile</filename>. The default target is "all". @@ -9915,8 +13079,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-UBOOT_SUFFIX'><glossterm>UBOOT_SUFFIX</glossterm> + <info> + UBOOT_SUFFIX[doc] = "Points to the generated U-Boot extension." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Points to the generated U-Boot extension. For example, <filename>u-boot.sb</filename> has a <filename>.sb</filename> extension. @@ -9930,8 +13098,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-UBOOT_TARGET'><glossterm>UBOOT_TARGET</glossterm> + <info> + UBOOT_TARGET[doc] = "Specifies the target used for building U-Boot." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the target used for building U-Boot. The target is passed directly as part of the "make" command (e.g. SPL and AIS). @@ -9942,9 +13114,61 @@ 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-UPDATERCPN'><glossterm>UPDATERCPN</glossterm> + <info> + UPDATERCPN[doc] = "Specifies the package that contains the initscript that is to be enabled." + </info> <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + For recipes inheriting the + <link linkend='ref-classes-update-rc.d'><filename>update-rc.d</filename></link> + class, <filename>UPDATERCPN</filename> specifies + the package that contains the initscript that is to be + enabled. + </para> + + <para> + The default value is "${PN}". + Given that almost all recipes that install initscripts + package them in the main package for the recipe, you + rarely need to set this variable in individual recipes. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-USE_DEVFS'><glossterm>USE_DEVFS</glossterm> + <info> + USE_DEVFS[doc] = "Determines if devtmpfs is used for /dev population." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Determines if <filename>devtmpfs</filename> is used for + <filename>/dev</filename> population. + The default value used for <filename>USE_DEVFS</filename> + is "1" when no value is specifically set. + Typically, you would set <filename>USE_DEVFS</filename> + to "0" for a statically populated <filename>/dev</filename> + directory. + </para> + <para> + See the + "<ulink url='&YOCTO_DOCS_DEV_URL;#selecting-dev-manager'>Selecting a Device Manager</ulink>" + section in the Yocto Project Development Manual for + information on how to use this variable. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-USE_VT'><glossterm>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 role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> When using <ulink url='&YOCTO_DOCS_DEV_URL;#new-recipe-enabling-system-services'>SysVinit</ulink>, determines whether or not to run a @@ -9965,8 +13189,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-USER_CLASSES'><glossterm>USER_CLASSES</glossterm> + <info> + USER_CLASSES[doc] = "List of additional classes to use when building images that enable extra features." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> A list of classes to globally inherit. These classes are used by the OpenEmbedded build system to enable extra features (e.g. @@ -9989,8 +13217,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-USERADD_ERROR_DYNAMIC'><glossterm>USERADD_ERROR_DYNAMIC</glossterm> + <info> + USERADD_ERROR_DYNAMIC[doc] = "Forces the OpenEmbedded build system to produce an error if the user identification (uid) and group identification (gid) values are not defined in files/passwd and files/group files." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Forces the OpenEmbedded build system to produce an error if the user identification (<filename>uid</filename>) and group identification (<filename>gid</filename>) values @@ -10026,8 +13258,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-USERADD_GID_TABLES'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies a password file to use for obtaining static group identification (<filename>gid</filename>) values when the OpenEmbedded build system adds a group to the @@ -10057,41 +13293,13 @@ 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> + <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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> When inheriting the <link linkend='ref-classes-useradd'><filename>useradd</filename></link> class, this variable @@ -10123,8 +13331,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-USERADD_PARAM'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> When inheriting the <link linkend='ref-classes-useradd'><filename>useradd</filename></link> class, this variable @@ -10149,9 +13361,49 @@ 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>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 role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + 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>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 role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> When set to "useradd-staticids", causes the OpenEmbedded build system to base all user and group additions on a static @@ -10202,8 +13454,12 @@ 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> + <info> + WARN_QA[doc] = "Specifies the quality assurance checks whose failures are reported as warnings by the OpenEmbedded build system." + </info> <glossdef> - <para> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the quality assurance checks whose failures are reported as warnings by the OpenEmbedded build system. You set this variable in your distribution configuration @@ -10217,8 +13473,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossentry> <glossentry id='var-WORKDIR'><glossterm>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> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The pathname of the work directory in which the OpenEmbedded build system builds a recipe. This directory is located within the @@ -10272,8 +13532,33 @@ 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>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 role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + 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 17b8e97145..8299f9f3ca 100644 --- a/documentation/ref-manual/resources.xml +++ b/documentation/ref-manual/resources.xml @@ -80,10 +80,12 @@ <ulink url='&YOCTO_HOME_URL;'>The Yocto Project website</ulink>: </emphasis> The home site for the Yocto Project.</para></listitem> +<!-- <listitem><para><emphasis> <ulink url='http://www.intel.com/'>Intel Corporation</ulink>:</emphasis> 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> The upstream, generic, embedded distribution used as the basis @@ -93,19 +95,10 @@ <listitem><para><emphasis> <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> - A comprehensive guide to the BitBake tool. - In the - <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>, - you can find the BitBake User Manual in the - <filename>bitbake/doc/bitbake-user-manual</filename> directory. - </para></listitem> - <listitem><para><emphasis> - <ulink url='http://wiki.qemu.org/Index.html'>QEMU</ulink>: - </emphasis> An open source machine emulator and virtualizer. - </para></listitem> </itemizedlist> + For more links, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#other-information'>Other Information</ulink>" + section in the Yocto Project Development Manual. </para> </section> diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml index 6bb3381e72..2df36521c2 100644 --- a/documentation/ref-manual/technical-details.xml +++ b/documentation/ref-manual/technical-details.xml @@ -107,11 +107,8 @@ <para> BitBake also tries to execute any dependent tasks first. So for example, before building <filename>matchbox-desktop</filename>, BitBake - would build a cross compiler and <filename>eglibc</filename> if they had not already + would build a cross compiler and <filename>glibc</filename> if they had not already been built. - <note>This release of the Yocto Project does not support the <filename>glibc</filename> - GNU version of the Unix standard C library. By default, the OpenEmbedded build system - builds with <filename>eglibc</filename>.</note> </para> <para> @@ -228,7 +225,7 @@ The chain of events that occurs when <filename>gcc-cross</filename> is bootstrapped is as follows: <literallayout class='monospaced'> - gcc -> binutils-cross -> gcc-cross-initial -> linux-libc-headers -> eglibc-initial -> eglibc -> gcc-cross -> gcc-runtime + gcc -> binutils-cross -> gcc-cross-initial -> linux-libc-headers -> glibc-initial -> glibc -> gcc-cross -> gcc-runtime </literallayout> <itemizedlist> <listitem><para><filename>gcc</filename>: @@ -251,9 +248,9 @@ <listitem><para><filename>linux-libc-headers</filename>: Headers needed for the cross-compiler. </para></listitem> - <listitem><para><filename>eglibc-initial</filename>: + <listitem><para><filename>glibc-initial</filename>: An initial version of the Embedded GLIBC needed to bootstrap - <filename>eglibc</filename>. + <filename>glibc</filename>. </para></listitem> <listitem><para><filename>gcc-cross</filename>: The final stage of the bootstrap process for the @@ -305,7 +302,7 @@ 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 + glibc-initial -> nativesdk-glibc -> gcc-crosssdk -> gcc-cross-canadian </literallayout> <itemizedlist> <listitem><para><filename>gcc</filename>: @@ -328,11 +325,11 @@ <listitem><para><filename>linux-libc-headers</filename>: Headers needed for the cross-compiler. </para></listitem> - <listitem><para><filename>eglibc-initial</filename>: + <listitem><para><filename>glibc-initial</filename>: An initial version of the Embedded GLIBC needed to bootstrap - <filename>nativesdk-eglibc</filename>. + <filename>nativesdk-glibc</filename>. </para></listitem> - <listitem><para><filename>nativesdk-eglibc</filename>: + <listitem><para><filename>nativesdk-glibc</filename>: The Embedded GLIBC needed to bootstrap the <filename>gcc-crosssdk</filename>. </para></listitem> diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml index 1a211ca78a..a7bff18b01 100644 --- a/documentation/ref-manual/usingpoky.xml +++ b/documentation/ref-manual/usingpoky.xml @@ -283,12 +283,12 @@ <ulink url='&YOCTO_RELEASE_NOTES;'>Release Notes</ulink> for a look at all release-related issues. <itemizedlist> - <listitem><para><emphasis><filename>eglibc-initial</filename> fails to build</emphasis>: + <listitem><para><emphasis><filename>glibc-initial</filename> fails to build</emphasis>: If your development host system has the unpatched <filename>GNU Make 3.82</filename>, the <link linkend='ref-tasks-install'><filename>do_install</filename></link> - task fails for <filename>eglibc-initial</filename> during + task fails for <filename>glibc-initial</filename> during the build.</para> <para>Typically, every distribution that ships <filename>GNU Make 3.82</filename> as @@ -564,19 +564,22 @@ <para> The history for each package contains a text file that has name-value pairs with information about the package. - For example, <filename>buildhistory/packages/core2-poky-linux/busybox/busybox/latest</filename> + For example, <filename>buildhistory/packages/i586-poky-linux/busybox/busybox/latest</filename> contains the following: <literallayout class='monospaced'> - PV = 1.19.3 - PR = r3 - RDEPENDS = update-rc.d eglibc (>= 2.13) - RRECOMMENDS = busybox-syslog busybox-udhcpc - PKGSIZE = 564701 - FILES = /usr/bin/* /usr/sbin/* /usr/libexec/* /usr/lib/lib*.so.* \ - /etc /com /var /bin/* /sbin/* /lib/*.so.* /usr/share/busybox \ - /usr/lib/busybox/* /usr/share/pixmaps /usr/share/applications \ - /usr/share/idl /usr/share/omf /usr/share/sounds /usr/lib/bonobo/servers - FILELIST = /etc/busybox.links /etc/init.d/hwclock.sh /bin/busybox /bin/sh + PV = 1.22.1 + PR = r32 + RPROVIDES = + RDEPENDS = glibc (>= 2.20) update-alternatives-opkg + RRECOMMENDS = busybox-syslog busybox-udhcpc update-rc.d + PKGSIZE = 540168 + FILES = /usr/bin/* /usr/sbin/* /usr/lib/busybox/* /usr/lib/lib*.so.* \ + /etc /com /var /bin/* /sbin/* /lib/*.so.* /lib/udev/rules.d \ + /usr/lib/udev/rules.d /usr/share/busybox /usr/lib/busybox/* \ + /usr/share/pixmaps /usr/share/applications /usr/share/idl \ + /usr/share/omf /usr/share/sounds /usr/lib/bonobo/servers + FILELIST = /bin/busybox /bin/busybox.nosuid /bin/busybox.suid /bin/sh \ + /etc/busybox.links.nosuid /etc/busybox.links.suid </literallayout> Most of these name-value pairs correspond to variables used to produce the package. @@ -589,15 +592,16 @@ <para> There is also a file corresponding to the recipe from which the package came (e.g. - <filename>buildhistory/packages/core2-poky-linux/busybox/latest</filename>): + <filename>buildhistory/packages/i586-poky-linux/busybox/latest</filename>): <literallayout class='monospaced'> - PV = 1.19.3 - PR = r3 - DEPENDS = virtual/i586-poky-linux-gcc virtual/i586-poky-linux-compilerlibs \ - virtual/libc update-rc.d-native - PACKAGES = busybox-httpd busybox-udhcpd busybox-udhcpc busybox-syslog \ - busybox-mdev busybox-dbg busybox busybox-doc busybox-dev \ - busybox-staticdev busybox-locale + PV = 1.22.1 + PR = r32 + DEPENDS = initscripts kern-tools-native update-rc.d-native \ + virtual/i586-poky-linux-compilerlibs virtual/i586-poky-linux-gcc \ + virtual/libc virtual/update-alternatives + PACKAGES = busybox-ptest busybox-httpd busybox-udhcpd busybox-udhcpc \ + busybox-syslog busybox-mdev busybox-hwclock busybox-dbg \ + busybox-staticdev busybox-dev busybox-doc busybox-locale busybox </literallayout> </para> @@ -611,31 +615,44 @@ is set to <filename>${<link linkend='var-AUTOREV'>AUTOREV</link>}</filename>. Here is an example assuming - <filename>buildhistory/packages/emenlow-poky-linux/linux-yocto/latest_srcrev</filename>): + <filename>buildhistory/packages/qemux86-poky-linux/linux-yocto/latest_srcrev</filename>): <literallayout class='monospaced'> - # SRCREV_machine = "b5c37fe6e24eec194bb29d22fdd55d73bcc709bf" - SRCREV_machine = "b5c37fe6e24eec194bb29d22fdd55d73bcc709bf" - # SRCREV_emgd = "caea08c988e0f41103bbe18eafca20348f95da02" - SRCREV_emgd = "caea08c988e0f41103bbe18eafca20348f95da02" - # SRCREV_meta = "c2ed0f16fdec628242a682897d5d86df4547cf24" - SRCREV_meta = "c2ed0f16fdec628242a682897d5d86df4547cf24" + # SRCREV_machine = "38cd560d5022ed2dbd1ab0dca9642e47c98a0aa1" + SRCREV_machine = "38cd560d5022ed2dbd1ab0dca9642e47c98a0aa1" + # SRCREV_meta = "a227f20eff056e511d504b2e490f3774ab260d6f" + SRCREV_meta = "a227f20eff056e511d504b2e490f3774ab260d6f" </literallayout> You can use the <filename>buildhistory-collect-srcrevs</filename> - command to collect the stored <filename>SRCREV</filename> values - from build history and report them in a format suitable for use in - global configuration (e.g., <filename>local.conf</filename> - or a distro include file) to override floating - <filename>AUTOREV</filename> values to a fixed set of revisions. + command with the <filename>-a</filename> option to + collect the stored <filename>SRCREV</filename> values + from build history and report them in a format suitable for + use in global configuration (e.g., + <filename>local.conf</filename> or a distro include file) to + override floating <filename>AUTOREV</filename> values to a + fixed set of revisions. Here is some example output from this command: <literallayout class='monospaced'> - # emenlow-poky-linux - SRCREV_machine_pn-linux-yocto = "b5c37fe6e24eec194bb29d22fdd55d73bcc709bf" - SRCREV_emgd_pn-linux-yocto = "caea08c988e0f41103bbe18eafca20348f95da02" - SRCREV_meta_pn-linux-yocto = "c2ed0f16fdec628242a682897d5d86df4547cf24" - # core2-poky-linux - SRCREV_pn-kmod = "62081c0f68905b22f375156d4532fd37fa5c8d33" - SRCREV_pn-blktrace = "d6918c8832793b4205ed3bfede78c2f915c23385" - SRCREV_pn-opkg = "649" + $ buildhistory-collect-srcrevs -a + # i586-poky-linux + SRCREV_pn-glibc = "b8079dd0d360648e4e8de48656c5c38972621072" + SRCREV_pn-glibc-initial = "b8079dd0d360648e4e8de48656c5c38972621072" + SRCREV_pn-opkg-utils = "53274f087565fd45d8452c5367997ba6a682a37a" + SRCREV_pn-kmod = "fd56638aed3fe147015bfa10ed4a5f7491303cb4" + # x86_64-linux + SRCREV_pn-gtk-doc-stub-native = "1dea266593edb766d6d898c79451ef193eb17cfa" + SRCREV_pn-dtc-native = "65cc4d2748a2c2e6f27f1cf39e07a5dbabd80ebf" + SRCREV_pn-update-rc.d-native = "eca680ddf28d024954895f59a241a622dd575c11" + SRCREV_glibc_pn-cross-localedef-native = "b8079dd0d360648e4e8de48656c5c38972621072" + SRCREV_localedef_pn-cross-localedef-native = "c833367348d39dad7ba018990bfdaffaec8e9ed3" + SRCREV_pn-prelink-native = "faa069deec99bf61418d0bab831c83d7c1b797ca" + SRCREV_pn-opkg-utils-native = "53274f087565fd45d8452c5367997ba6a682a37a" + SRCREV_pn-kern-tools-native = "23345b8846fe4bd167efdf1bd8a1224b2ba9a5ff" + SRCREV_pn-kmod-native = "fd56638aed3fe147015bfa10ed4a5f7491303cb4" + # qemux86-poky-linux + SRCREV_machine_pn-linux-yocto = "38cd560d5022ed2dbd1ab0dca9642e47c98a0aa1" + SRCREV_meta_pn-linux-yocto = "a227f20eff056e511d504b2e490f3774ab260d6f" + # all-poky-linux + SRCREV_pn-update-rc.d = "eca680ddf28d024954895f59a241a622dd575c11" </literallayout> <note> Here are some notes on using the @@ -660,7 +677,7 @@ However, the script does place a comment before each set of values that specifies which triplet to which they belong as shown above - (e.g., <filename>emenlow-poky-linux</filename>). + (e.g., <filename>i586-poky-linux</filename>). </para></listitem> </itemizedlist> </note> @@ -717,17 +734,21 @@ Here is an example of <filename>image-info.txt</filename>: <literallayout class='monospaced'> DISTRO = poky - DISTRO_VERSION = 1.1+snapshot-20120207 - USER_CLASSES = image-mklibs image-prelink + DISTRO_VERSION = 1.7 + USER_CLASSES = buildstats image-mklibs image-prelink IMAGE_CLASSES = image_types - IMAGE_FEATURES = debug-tweaks x11-base apps-x11-core \ - package-management ssh-server-dropbear package-management - IMAGE_LINGUAS = en-us en-gb - IMAGE_INSTALL = packagegroup-core-boot packagegroup-base-extended + IMAGE_FEATURES = debug-tweaks + IMAGE_LINGUAS = + IMAGE_INSTALL = packagegroup-core-boot run-postinsts BAD_RECOMMENDATIONS = - ROOTFS_POSTPROCESS_COMMAND = buildhistory_get_image_installed ; rootfs_update_timestamp ; - IMAGE_POSTPROCESS_COMMAND = buildhistory_get_imageinfo ; - IMAGESIZE = 171816 + NO_RECOMMENDATIONS = + PACKAGE_EXCLUDE = + ROOTFS_POSTPROCESS_COMMAND = write_package_manifest; license_create_manifest; \ + write_image_manifest ; buildhistory_list_installed_image ; \ + buildhistory_get_image_installed ; ssh_allow_empty_password; \ + postinst_enable_logging; rootfs_update_timestamp ; ssh_disable_dns_lookup ; + IMAGE_POSTPROCESS_COMMAND = buildhistory_get_imageinfo ; + IMAGESIZE = 6900 </literallayout> Other than <filename>IMAGESIZE</filename>, which is the total size of the files in the image in Kbytes, the @@ -811,7 +832,7 @@ <literallayout class='monospaced'> DISTRO = poky DISTRO_VERSION = 1.3+snapshot-20130327 - SDK_NAME = poky-eglibc-i686-arm + SDK_NAME = poky-glibc-i686-arm SDK_VERSION = 1.3+snapshot SDKMACHINE = SDKIMAGE_FEATURES = dev-pkgs dbg-pkgs @@ -858,12 +879,12 @@ Here is an example: <literallayout class='monospaced'> $ ~/poky/poky/scripts/buildhistory-diff . HEAD^ - Changes to images/qemux86_64/eglibc/core-image-minimal (files-in-image.txt): + Changes to images/qemux86_64/glibc/core-image-minimal (files-in-image.txt): /etc/anotherpkg.conf was added /sbin/anotherpkg was added * (installed-package-names.txt): * anotherpkg was added - Changes to images/qemux86_64/eglibc/core-image-minimal (installed-package-names.txt): + Changes to images/qemux86_64/glibc/core-image-minimal (installed-package-names.txt): anotherpkg was added packages/qemux86_64-poky-linux/v86d: PACKAGES: added "v86d-extras" * PR changed from "r0" to "r1" @@ -888,6 +909,149 @@ </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 so you should probably not override + these to try to speed up a build. + However, for completeness regarding this list, it is worth + mentioning that you can manually override these variables + by setting them in your <filename>local.conf</filename> file. + </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/embedded_video.xsl b/documentation/template/embedded_video.xsl new file mode 100644 index 0000000000..dfb33c3441 --- /dev/null +++ b/documentation/template/embedded_video.xsl @@ -0,0 +1,22 @@ +<?xml version="1.0" encoding="UTF-8"?> +<xsl:stylesheet version="1.0" + xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + xmlns:d="http://docbook.org/ns/docbook"> + + <xsl:output method="html" /> + + <xsl:template match="/d:chapter/d:section/d:mediaobject"> + <xsl:for-each select="."> + <xsl:variable name="vid_url"> + <xsl:value-of select="./d:videoobject/d:videodata/@fileref" /> + </xsl:variable> + <div style="text-align: center; margin: auto"> + <object type="application/x-shockwave-flash" width="640" height="420" data="{$vid_url}?color2=FBE9EC&showsearch=0&version=3&modestbranding=1&fs=1"> + <param name="movie" value="{$vid_url}?color2=FBE9EC&showsearch=0&version=3&modestbranding=1&fs=1" /> + <param name="allowFullScreen" value="true" /> + <param name="allowscriptaccess" value="always" /> + </object> + </div> + </xsl:for-each> + </xsl:template> +</xsl:stylesheet> diff --git a/documentation/toaster-manual/figures/hosted-service.png b/documentation/toaster-manual/figures/hosted-service.png Binary files differnew file mode 100644 index 0000000000..01fea7b245 --- /dev/null +++ b/documentation/toaster-manual/figures/hosted-service.png diff --git a/documentation/toaster-manual/figures/simple-configuration.png b/documentation/toaster-manual/figures/simple-configuration.png Binary files differnew file mode 100644 index 0000000000..e8fce2bf18 --- /dev/null +++ b/documentation/toaster-manual/figures/simple-configuration.png diff --git a/documentation/toaster-manual/figures/toaster-title.png b/documentation/toaster-manual/figures/toaster-title.png Binary files differnew file mode 100644 index 0000000000..b7ea39cd8d --- /dev/null +++ b/documentation/toaster-manual/figures/toaster-title.png diff --git a/documentation/toaster-manual/toaster-manual-customization.xsl b/documentation/toaster-manual/toaster-manual-customization.xsl new file mode 100644 index 0000000000..dcf7805d4c --- /dev/null +++ b/documentation/toaster-manual/toaster-manual-customization.xsl @@ -0,0 +1,21 @@ +<?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/1.76.1/xhtml/docbook.xsl" /> +<!-- <xsl:import href="../template/1.76.1/docbook-xsl-1.76.1/xhtml/docbook.xsl" /> --> + + <xsl:include href="../template/permalinks.xsl"/> + <xsl:include href="../template/section.title.xsl"/> + <xsl:include href="../template/component.title.xsl"/> + <xsl:include href="../template/division.title.xsl"/> + <xsl:include href="../template/formal.object.heading.xsl"/> + <xsl:include href="../template/embedded_video.xsl"/> + + <xsl:param name="html.stylesheet" select="'toaster-manual-style.css'" /> + <xsl:param name="chapter.autolabel" select="1" /> + <xsl:param name="appendix.autolabel" select="A" /> + <xsl:param name="section.autolabel" select="1" /> + <xsl:param name="section.label.includes.component.label" select="1" /> + <xsl:param name="generate.id.attributes" select="1" /> + +</xsl:stylesheet> diff --git a/documentation/toaster-manual/toaster-manual-intro.xml b/documentation/toaster-manual/toaster-manual-intro.xml new file mode 100644 index 0000000000..ad9e08b50d --- /dev/null +++ b/documentation/toaster-manual/toaster-manual-intro.xml @@ -0,0 +1,172 @@ +<!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='toaster-manual-intro'> +<title>Introduction</title> + + <para> + Toaster is a web interface to the Yocto Project's + <ulink url='&YOCTO_DOCS_DEV_URL;#build-system-term'>OpenEmbedded build system</ulink>. + The interface enables you to configure and run your builds. + Information about builds is collected and stored in a database. + You can use Toaster to configure and start builds on multiple + remote build servers. + </para> + + <note> + <para> + This release of Toaster does allow you to configure and initiate + builds. + However, you cannot use Toaster to customize image recipes, which + still must either be done by hand or through + <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink>. + As Toaster matures, it eventually will equal and surpass Hob + functionality, at which time Hob will be deprecated. + </para> + + <para> + For more information on Hob, + see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#image-development-using-hob'>Image Development Using Hob</ulink>" + section in the Yocto Project Development Manual. + </para> + </note> + + <section id='intro-modes'> + <title>Toaster Operational Modes</title> + + <para> + You can use Toaster in Analysis Mode or Build Mode: + <itemizedlist> + <listitem><para><emphasis>Analysis Mode:</emphasis> + In Analysis Mode, you can record builds and statistics. + In this Mode, you directly access the + <filename>bitbake</filename> command, which you then use to + build images.</para> + <para>Analysis Mode requires you to have first started + Toaster and then to initiate your build using the + <filename>bitbake</filename> command from the shell. + Toaster must be started before the build or it will not + collect build data.</para> + <para>Toaster has the following capabilities in + Analysis Mode: + <itemizedlist> + <listitem><para> + See what was built (recipes and packages) and what + packages were installed into your final image. + </para></listitem> + <listitem><para> + Browse the directory structure of your image. + </para></listitem> + <listitem><para> + See the value of all variables in your build + configuration, and which files set each value. + </para></listitem> + <listitem><para> + Examine error, warning and trace messages to aid + in debugging. + </para></listitem> + <listitem><para> + See information about the BitBake tasks executed + and reused during your build, including those that + used shared state. + </para></listitem> + <listitem><para> + See dependency relationships between recipes, + packages and tasks + </para></listitem> + <listitem><para> + See performance information such as build time, + task time, CPU usage, and disk I/O. + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para><emphasis>Build Mode:</emphasis> + In Build Mode, Toaster handles the build configuration, + scheduling and execution. + In this mode, all your interaction with the build system + happens through the web interface. + You do not have direct access to the + <filename>bitbake</filename> command.</para> + <para>Using this mode, you configure and start your builds + within Toaster's GUI. + Each project can be configured for a specific version + of the build system. + As shipped, Toaster supports Yocto Project Releases 1.7 and + beyond.</para> + <para>Toaster has all the same capabilities in Build Mode + as it does in Analysis Mode plus the following: + <itemizedlist> + <listitem><para> + Browse layers listed in the various + <link linkend='layer-source'>layer sources</link> + that are available in your project (e.g. the + OpenEmbedded Metadata Index at + <ulink url='http://layers.openembedded.org/layerindex/'></ulink>). + </para></listitem> + <listitem><para> + Import your own layers for building. + </para></listitem> + <listitem><para> + Add and remove layers from your configuration. + </para></listitem> + <listitem><para> + Set configuration variables. + </para></listitem> + <listitem><para> + Select a target or multiple targets to build. + </para></listitem> + <listitem><para> + Start your builds. + </para></listitem> + </itemizedlist> + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='toaster-installation-options'> + <title>Installation Options</title> + + <para> + You can set Toaster up to run as a local instance or as a shared + hosted service. + Regardless of how you set up Toaster, both Analysis and Build + Modes are available. + </para> + + <para> + When Toaster is set up as a local instance, all the components + reside on a single build host. + Fundamentally, a local instance of Toaster is suited for a single + user developing on a single build host. + </para> + + <para> + <imagedata fileref="figures/simple-configuration.png" align="center" width="6in" depth="1.5in" /> + </para> + + <para> + Toaster as a hosted service is suited for multiple users + developing across several build hosts. + When Toaster is set up as a hosted service, its components can + be spread across several machines: + </para> + + <para> + <imagedata fileref="figures/hosted-service.png" align="center" width="6in" depth="3.5in" /> + </para> + </section> + +<!--THIS EXTRA INFORMATION PROBABLY WILL GO AWAY + For additional information on installing and running Toaster, see the + "<ulink url='https://wiki.yoctoproject.org/wiki/Toaster#Installation_and_Running'>Installation and Running</ulink>" + section of the "Toaster" wiki page. + For complete information on the API and its search operation + URI, parameters, and responses, see the + <ulink url='https://wiki.yoctoproject.org/wiki/REST_API_Contracts'>REST API Contracts</ulink> + Wiki page. + </para> +--> +</chapter> diff --git a/documentation/toaster-manual/toaster-manual-reference.xml b/documentation/toaster-manual/toaster-manual-reference.xml new file mode 100644 index 0000000000..fede4529a2 --- /dev/null +++ b/documentation/toaster-manual/toaster-manual-reference.xml @@ -0,0 +1,1073 @@ +<!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='toaster-manual-reference'> + +<title>Concepts and Reference</title> + + <para> + In order to configure and use Toaster, you should understand some + concepts and have some basic command reference material available. + This final chapter provides conceptual information on layer sources, + releases, and JSON configuration files. + Also provided is a quick look at some useful + <filename>manage.py</filename> commands that are Toaster-specific. + Information on <filename>manage.py</filename> commands does exist + across the Web and the information in this manual by no means + attempts to provide a command comprehensive reference. + </para> + + <section id='layer-source'> + <title>Layer Source</title> + + <para> + In general, a "layer source" is a source of information about + existing layers. + In particular, we are concerned with layers that you can use + with the Yocto Project and Toaster. + This chapter describes a particular type of layer source called + a "layer index." + </para> + + <para> + A layer index is a web application that contains information + about a set of custom layers. + A good example of an existing layer index is the + OpenEmbedded Metadata Index. + A public instance of this layer index exists at + <ulink url='http://layers.openembedded.org'></ulink>. + You can find the code for this layer index's web application at + <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/layerindex-web/'></ulink>. + </para> + + <para> + When you tie a layer source into Toaster, it can query the layer + source through a + <ulink url='http://en.wikipedia.org/wiki/Representational_state_transfer'>REST</ulink> + API, store the information about the layers in the Toaster + database, and then show the information to users. + Users are then able to view that information and build layers + from Toaster itself without worrying about cloning or editing + the BitBake layers configuration file + <filename>bblayers.conf</filename>. + </para> + + <para> + Tying a layer source into Toaster is convenient when you have + many custom layers that need to be built on a regular basis by + a community of developers. + In fact, Toaster comes pre-configured with the OpenEmbedded + Metadata Index. + <note> + You do not have to use a layer source to use Toaster. + Tying into a layer source is optional. + </note> + </para> + + <section id='layer-source-using-with-toaster'> + <title>Setting Up and Using a Layer Source</title> + + <para> + To use your own layer source, you need to set up the layer + source and then tie it into Toaster. + This section describes how to tie into a layer index in a manner + similar to the way Toaster ties into the OpenEmbedded Metadata + Index. + </para> + + <section id='understanding-your-layers'> + <title>Understanding Your Layers</title> + + <para> + The obvious first step for using a layer index is to have + several custom layers that developers build and access using + the Yocto Project on a regular basis. + This set of layers needs to exist and you need to be + familiar with where they reside. + You will need that information when you set up the + code for the web application that "hooks" into your set of + layers. + </para> + + <para> + For general information on layers, see the + "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>" + and + "<ulink url='&YOCTO_DOCS_BSP_URL;#using-the-yocto-projects-bsp-tools'>Using the Yocto Project's BSP Tools</ulink>" + sections in the Yocto Project Board Support Package (BSP) + Developer's Guide. + </para> + </section> + + <section id='configuring-toaster-to-hook-into-your-layer-source'> + <title>Configuring Toaster to Hook Into Your Layer Index</title> + + <para> + If you want Toaster to use your layer index, you must host + the web application in a server to which Toaster can + connect. + You also need to give Toaster the information about your + layer index. + In other words, you have to configure Toaster to use your + layer index. + This section describes two methods by which you can + configure and use your layer index. + </para> + + <para> + In the previous section, the code for the OpenEmbedded + Metadata Index (i.e. + <ulink url='http://layers.openembedded.org'></ulink>) was + referenced. + You can use this code, which is at + <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/layerindex-web/'></ulink>, + as a base to create your own layer index. + </para> + + <section id='use-the-administration-interface'> + <title>Use the Administration Interface</title> + + <para> + Access the administration interface through a + browser by entering the URL of your Toaster instance and + adding "<filename>/admin</filename>" to the end of the + URL. + </para> + + <para> + The administration interface has a "Layer sources" + section that includes an "Add layer source" button. + Click that button and provide the required information. + Make sure you select "layerindex" as the layer source type. + </para> + </section> + + <section id='select-the-toasterconf-json-file'> + <title>Use the <filename>toasterconf.json</filename> File</title> + + <para> + If you do not want to use the Administration + Interface, you can edit the + <link linkend='toaster-json-files'><filename>toasterconf.json</filename></link> + file and reload it to Toaster. + </para> + + <para> + When you set up Toaster in Build Mode, you are prompted + to select a Toaster configuration file. + This configuration file is used to set up the initial + configuration values within the Toaster database + including the layer sources. + Three versions of the configuration file exist: + <itemizedlist> + <listitem><para> + The first version of the file is found in the + <filename>conf</filename> directory of the + <filename>meta-yocto</filename> layer + (i.e. + <filename>meta-yocto/conf/toasterconf.json</filename>). + This version contains the default Yocto Project + configuration for Toaster. + You are prompted to select this file during the + Toaster set up process if you had cloned the + <filename>poky</filename> repository (i.e. + <filename>git://git.yoctoproject.org/poky</filename>). + </para></listitem> + <listitem><para> + The second version of the file is in the + <filename>conf</filename> directory of the + <filename>openembedded-core</filename> layer + (i.e. <filename>meta/conf/toasterconf.json</filename>). + This version contains the default OpenEmbedded + configuration for Toaster. + You are prompted to select this file during the + Toaster set up process if you had cloned the + <filename>openembedded-core</filename> repository + (i.e. + <filename>git://git.openembedded.org/openembedded-core</filename>). + </para></listitem> + <listitem><para> + The third version is a sample configuration + useful for when you want to set up a hosted + service in Build Mode. + You can find this version on the + <ulink url='https://wiki.yoctoproject.org/wiki/File:Toasterconf.json.txt.patch'>File:Toasterconf.json.txt.patch</ulink> + wiki page. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='edit-the-configuration-file'> + <title>Edit the Configuration File</title> + + <para> + Edit the version of the + <filename>toasterconf.json</filename> file you + used to set up your Toaster instance. + In the file, you will find a section for layer sources + such as the following: + <literallayout class='monospaced'> + "layersources": [ + { + "name": "Local Yocto Project", + "sourcetype": "local", + "apiurl": "../../", + "branches": ["HEAD", "master", "fido", "dizzy"], + "layers": [ + { + "name": "openembedded-core", + "local_path": "meta", + "vcs_url": "remote:origin", + "dirpath": "meta" + }, + { + "name": "meta-yocto", + "local_path": "meta-yocto", + "vcs_url": "remote:origin", + "dirpath": "meta-yocto" + }, + { + "name": "meta-yocto-bsp", + "local_path": "meta-yocto-bsp", + "vcs_url": "remote:origin", + "dirpath": "meta-yocto-bsp" + } + + ] + }, + { + "name": "OpenEmbedded", + "sourcetype": "layerindex", + "apiurl": "http://layers.openembedded.org/layerindex/api/", + "branches": ["master", "fido", "dizzy"] + }, + { + "name": "Imported layers", + "sourcetype": "imported", + "apiurl": "", + "branches": ["master", "fido", "dizzy", "HEAD"] + + } + ], + </literallayout> + You should add your own layer source to this section by + following the same format used for the "OpenEmbedded" + layer source shown above. + </para> + + <para> + Give your layer source a name, provide the URL of your + layer source API, use the source type "layerindex", and + indicate which branches from your layer source you want + to make available through Toaster. + For example, the OpenEmbedded layer source makes + available only its "master", "fido", and "dizzy" + branches. + </para> + + <para> + The branches must match the branch you + set when configuring your releases. + For example, if you configure one release in Toaster + by setting its branch to "branch-one" and you configure + another release in Toaster by setting its branch to + "branch-two", the branches in your layer source should + be "branch-one" and "branch-two" as well. + Doing so creates a connection between the releases + and the layer information from your layer source. + Thus, when users create a project with a given + release, they will see the appropriate layers from + your layer source. + This connection ensures that only layers that are + compatible with the selected project release can be + selected for building. + </para> + + <para> + Once you have added this information to the + <filename>toasterconf.json</filename> file, save your + changes. + </para> + + <para> + In a terminal window, navigate to the directory that + contains the Toaster database, which by default is the + root of the Yocto Project + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. + Once you are located in that directory, run the + "<filename>loadconf</filename>" command, which takes as + an argument the full path to the + <filename>toasterconf.json</filename> file you just edited. + For example, if you cloned the + <filename>poky</filename> repository and you edited the + <filename>meta-yocto/conf/toasterconf.json</filename> file, + you would type something like the following: + <literallayout class='monospaced'> + $ bitbake/lib/toaster/manage.py loadconf /home/scottrif/poky/meta-yocto/conf/toasterconf.json + </literallayout> + After entering this command, you need to update the + Toaster database with the information coming from your + new layer source. + To do that, you should run the + "<filename>lsupdates</filename>" command from the directory + that contains the Toaster database. + Here is an example: + <literallayout class='monospaced'> + $ bitbake/lib/toaster/manage.py lsupdates + </literallayout> + If Toaster can reach the API URL, you should see a message + telling you that Toaster is updating the layer source + information. + </para> + + <para> + Once the information has been updated, verify the new layer + information is available by using the Toaster web interface. + To do that, visit the "All compatible layers" page inside a + Toaster project. + The layers from your layer source should be listed there. + </para> + </section> + </section> + </section> + </section> + + <section id='toaster-releases'> + <title>Releases</title> + + <para> + When you create a Toaster project using the web interface, + you are asked to choose a "Release." + In the context of Toaster, the term "Release" refers to a set of + layers and a BitBake version the OpenEmbedded build system uses + to build something. + As shipped, Toaster is pre-configured with releases that + correspond to Yocto Project release branches. + However, you can modify, delete, and create new releases + according to your needs. + This section provides some background information on releases. + </para> + + <section id='toaster-releases-supported'> + <title>Pre-Configured Releases</title> + + <para> + As shipped, Toaster is configured to use a specific set of + releases. + Of course, you can always configure Toaster to use any + release. + For example, you might want your project to build against a + specific commit of any of the "out-of-the-box" releases. + Or, you might want your project to build against different + revisions of OpenEmbedded and BitBake. + </para> + + <para> + As shipped, Toaster is configured to work with the following + releases: + <itemizedlist> + <listitem><para><emphasis>Yocto Project 1.7 "Dizzy" or OpenEmbedded "Dizzy":</emphasis> + This release causes your Toaster projects to + build against the head of the dizzy branch at + <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/log/?h=dizzy'></ulink> + or + <ulink url='http://git.openembedded.org/openembedded-core/commit/?h=dizzy'></ulink>. + </para></listitem> + <listitem><para><emphasis>Yocto Project 1.8 "Fido" or OpenEmbedded "Fido":</emphasis> + This release causes your Toaster projects to + build against the head of the fido branch at + <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/log/?h=fido'></ulink> + or + <ulink url='http://git.openembedded.org/openembedded-core/commit/?h=fido'></ulink>. + </para></listitem> + <listitem><para><emphasis>Yocto Project "Master" or OpenEmbedded "Master":</emphasis> + This release causes your Toaster Projects to + build against the head of the master branch, which is + where active development takes place, at + <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/log/'></ulink> + or + <ulink url='http://git.openembedded.org/openembedded-core/log/'></ulink>. + </para></listitem> + <listitem><para><emphasis>Local Yocto Project or Local OpenEmbedded:</emphasis> + This release causes your Toaster Projects to + build against the head of the <filename>poky</filename> + or <filename>openembedded-core</filename> clone you + have local to the machine running Toaster. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='toaster-releases-comprised-of'> + <title>What Makes Up a Release?</title> + + <para> + A release consists of the following: + <itemizedlist> + <listitem><para><emphasis>Name:</emphasis> + The name of the release (<filename>name</filename>). + This release name never appears in the the Toaster + web interface. + Consequently, a user never sees the release name. + </para></listitem> + <listitem><para><emphasis>Description:</emphasis> + The textual description of the release + (<filename>description</filename>). + This description is what users encounter when creating + projects with the Toaster web interface. + When you configure your release, be sure to use + a description that sufficiently describes and is + understandable. + If Toaster has more than one release configured, the + release descriptions appear listed in a drop down menu + when a user creates a new project. + If Toaster has only one release configured, all + projects created using the web interface take that + release and the drop down menu does not display in the + Toaster web interface. + </para></listitem> + <listitem><para><emphasis>BitBake:</emphasis> + The Bitbake version (<filename>bitbake</filename>) + used to build layers set in the current release. + This version is described by a name, a Git URL, a + branch in the Git URL, and a directory path in the + Git repository. + As an example, consider the following snippet from + a Toaster JSON configuration file. + This BitBake version uses the master branch from the + OpenEmbedded repository: + <literallayout class='monospaced'> + "bitbake" : [ + { + "name": "master", + "giturl": "git://git.openembedded.org/bitbake", + "branch": "master", + "dirpath": "" + } + ] + </literallayout> + Here is more detail on each of the items that comprise + the BitBake version: + <itemizedlist> + <listitem><para><emphasis>Name:</emphasis> + A string + (<filename>name</filename>) used to refer to + the version of BitBake you are using with + Toaster. + This name is never exposed through Toaster. + </para></listitem> + <listitem><para><emphasis>Git URL:</emphasis> + The URL (<filename>giturl</filename>) + for the BitBake Git repository cloned + for Toaster projects. + </para></listitem> + <listitem><para><emphasis>Branch:</emphasis> + The Git branch, or revision, + (<filename>branch</filename>) of the BitBake + repository used with Toaster. + </para></listitem> + <listitem><para><emphasis>Directory Path:</emphasis> + The sub-directory of the BitBake repository + (<filename>dirpath</filename>). + If the Git URL includes more than one + repository, you need to set this directory. + If the URL does not include more than a single + repository, you can set + <filename>dirpath</filename> to a null string + (i.e. ""). + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para><emphasis>Branch:</emphasis> + The branch for the layer source + (<filename>branch</filename>) used with the release. + For example, for the OpenEmbedded layer source, the + "master", "fido", and "dizzy" branches are available. + </para></listitem> + <listitem><para><emphasis>Default Layers:</emphasis> + The set of default layers + (<filename>defaultlayers</filename>) automatically + added to the project configuration when a project is + created. + </para></listitem> + <listitem><para><emphasis>Layer Source Priorities</emphasis> + A specification of + <link linkend='layer-source'>layer source</link> + priorities (<filename>layersourcepriority</filename>). + In order for Toaster to work as intended, the + "Imported layers" layer source should have the highest + priority, which means that layers manually imported by + users with the "Import layer" functionality will + always be visible and available for selection. + </para></listitem> + <listitem><para><emphasis>Help Text:</emphasis> + Help text (<filename>helptext</filename>) that explains + what the release does when selected. + This help text appears below the release drop-down + menu when you create a Toaster project. + The help text should assist users in making the correct + decision regarding the release to use for a given + project. + </para></listitem> + </itemizedlist> + </para> + + <para> + To summarize what comprises a release, consider the following + example from a Toaster JSON file. + The configuration names the release "master" and uses the + "master" branch provided by the layer source of type + "layerindex", which is called "OpenEmbedded", and sets + the <filename>openembedded-core</filename> layer as the one + to be added by default to any projects created in Toaster. + The BitBake version used would be defined as shown earlier + in the previous list: + <literallayout class='monospaced'> + "releases": [ + { + "name": "master", + "description": "OpenEmbedded master", + "bitbake": "master", + "branch": "master", + "defaultlayers": [ "openembedded-core" ], + "layersourcepriority": { "Imported layers": 99, "Local OpenEmbedded" : 10, "OpenEmbedded" : 0 }, + "helptext": "Toaster will run your builds using the OpenEmbedded master branch, where active development takes place. This is not a stable branch, so your builds might not work as expected." + } + ] + </literallayout> + </para> + </section> + </section> + + <section id='toaster-json-files'> + <title>JSON Files</title> + + <para> + If you are going to be using Toaster in Build Mode, it must + be initially configured before use. + Configuration customizes layer source settings and Toaster defaults + for all users and is performed by the person responsible for + Toaster Configuration (i.e the Toaster Administrator). + The Toaster Administrator performs this configuration through the + Django administration interface. + </para> + + <para> + To make it easier to initially start Toaster, you can import a + pre-defined configuration file using the + <link linkend='toaster-command-loadconf'><filename>loadconf</filename></link> + command. + <note> + The configuration file is a JSON-formatted text file with + specific fields that Toaster recognizes. + It is not a data dump from the database, so it cannot be + loaded directly in the database. + </note> + </para> + + <para> + By convention, the supplied configuration files are named + <filename>toasterconf.json</filename>. + The Toaster Administrator can customize the file prior to loading + it into Toaster. + When you set up Toaster locally to run in Build Mode, the system + startup script actively looks for compatible configuration files + and prompts you to select a file to load if it detects that the + database has not been configured. + </para> + + <section id='json-file-choices'> + <title>Configuration File Choices</title> + + <para> + Three versions of the configuration file exist: + <itemizedlist> + <listitem><para> + The + <filename>meta-yocto/conf/toasterconf.json</filename> + in the <filename>conf</filename> directory of the + Yocto Project's <filename>meta-yocto</filename> layer. + This version contains the default Yocto Project + configuration for Toaster. + You are prompted to select this file during the Toaster + set up process if you cloned the + <filename>poky</filename> repository (i.e. + <filename>&YOCTO_GIT_URL;/poky</filename>). + </para></listitem> + <listitem><para> + The <filename>meta/conf/toasterconf.json</filename> + in the <filename>conf</filename> directory of the + OpenEmbedded's <filename>openembedded-core</filename> + layer. + This version contains the default OpenEmbedded + configuration for Toaster. + You are prompted to select this file during the Toaster + set up process if you had cloned the + <filename>openembedded-core</filename> repository (i.e. + <filename>git://git.openembedded.org/openembedded-core</filename>). + </para></listitem> + <listitem><para> + The <filename>Toasterconf.json.txt.patch</filename> + located on the + <ulink url='https://wiki.yoctoproject.org/wiki/File:Toasterconf.json.txt.patch'>File:Toasterconf.json.txt.patch</ulink> + wiki page. + This version of the file is useful as a sample + configuration for when you want to set up Toaster as a + hosted service in Build Mode. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='json-structure'> + <title>File Structure</title> + + <para> + The <filename>toasterconf.json</filename> file consists of + easily readable areas: configuration, layer sources, BitBake, + default release, and releases. + </para> + + <section id='json-config-area'> + <title>Configuration Area</title> + + <para> + This area of the JSON file sets which variables are exposed + to users through the Toaster web interface. + Users can easily edit these variables. + </para> + + <para> + The variables you set here are displayed in the + "Configuration variables" page in Toaster. + Minimally, you should set the + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> + variable, which appears to users as part of the project + page in Toaster. + </para> + + <para> + Here is the default <filename>config</filename> area: + <literallayout class='monospaced'> + "config": { + "MACHINE" : "qemux86", + "DISTRO" : "poky", + "IMAGE_FSTYPES": "ext3 jffs2 tar.bz2", + "IMAGE_INSTALL_append": "", + "PACKAGE_CLASSES": "package_rpm", + "SDKMACHINE" : "x86_64" + }, + </literallayout> + </para> + </section> + + <section id='json-layersources-area'> + <title>Layer Sources Area</title> + + <para> + This area of the JSON file defines the + <link linkend='layer-source'>layer sources</link> + Toaster uses. + Toaster reads layer information from layer sources. + Three types of layer sources exist that Toaster + recognizes: Local, LayerIndex, and Imported. + </para> + + <para> + The Local layer source reads layers from Git clones + available on your local drive. + Using a local layer source enables you to easily test + Toaster. + <note> + If you are setting up a hosted version of Toaster, + it does not make sense to have a local layer source. + </note> + </para> + + <para> + The LayerIndex layer source uses a REST API exposed by + instances of the Layer Index application (e.g the public + <ulink url='http://layers.openembedded.org/'></ulink>) + to read layer data. + </para> + + <para> + The Imported layer source is reserved for layer data + manually introduced by the user or Toaster Administrator + through the GUI. + This layer source lets users import their own layers + and build them with Toaster. + You should not remove the imported layer source. + </para> + + <para> + Here is the default <filename>layersources</filename> area: + <literallayout class='monospaced'> + "layersources": [ + { + "name": "Local Yocto Project", + "sourcetype": "local", + "apiurl": "../../", + "branches": ["HEAD", "master", "fido", "dizzy"], + "layers": [ + { + "name": "openembedded-core", + "local_path": "meta", + "vcs_url": "remote:origin", + "dirpath": "meta" + }, + { + "name": "meta-yocto", + "local_path": "meta-yocto", + "vcs_url": "remote:origin", + "dirpath": "meta-yocto" + }, + { + "name": "meta-yocto-bsp", + "local_path": "meta-yocto-bsp", + "vcs_url": "remote:origin", + "dirpath": "meta-yocto-bsp" + } + + ] + }, + { + "name": "OpenEmbedded", + "sourcetype": "layerindex", + "apiurl": "http://layers.openembedded.org/layerindex/api/", + "branches": ["master", "fido", "dizzy"] + }, + { + "name": "Imported layers", + "sourcetype": "imported", + "apiurl": "", + "branches": ["master", "fido", "dizzy", "HEAD"] + + } + ], + </literallayout> + </para> + </section> + + <section id='json-bitbake-area'> + <title>BitBake Area</title> + + <para> + This area of the JSON file defines the version of + BitBake Toaster uses. + As shipped, Toaster is configured to recognize four + versions of BitBake: master, fido, dizzy, and HEAD. + <note> + HEAD is a special option that builds whatever is + available on disk, without checking out any remote + Git repositories. + </note> + </para> + + <para> + Here is the default <filename>bitbake</filename> area: + <literallayout class='monospaced'> + "bitbake" : [ + { + "name": "master", + "giturl": "remote:origin", + "branch": "master", + "dirpath": "bitbake" + }, + { + "name": "fido", + "giturl": "remote:origin", + "branch": "fido", + "dirpath": "bitbake" + }, + { + "name": "dizzy", + "giturl": "remote:origin", + "branch": "dizzy", + "dirpath": "bitbake" + }, + { + "name": "HEAD", + "giturl": "remote:origin", + "branch": "HEAD", + "dirpath": "bitbake" + } + ], + </literallayout> + </para> + </section> + + <section id='json-default-area'> + <title>Default Area</title> + + <para> + This area of the JSON file establishes a default + release used by Toaster. + As shipped, Toaster uses the "master" release. + </para> + + <para> + Here is the statement in the JSON file that establishes + the default release: + <literallayout class='monospaced'> + "defaultrelease": "master", + </literallayout> + </para> + </section> + + <section id='json-releases-area'> + <title>Releases Area</title> + + <para> + This area of the JSON file defines the versions of the + OpenEmbedded build system Toaster recognizes. + As shipped, Toaster is configured to work with the four + releases described in the + "<link linkend='toaster-releases-supported'>Pre-Configured Releases</link>" + section. + </para> + + <para> + Here is the default <filename>releases</filename> area: + <literallayout class='monospaced'> + "releases": [ + { + "name": "master", + "description": "Yocto Project master", + "bitbake": "master", + "branch": "master", + "defaultlayers": [ "openembedded-core", "meta-yocto", "meta-yocto-bsp"], + "layersourcepriority": { "Imported layers": 99, "Local Yocto Project" : 10, "OpenEmbedded" : 0 }, + "helptext": "Toaster will run your builds using the tip of the <a href=\"http://git.yoctoproject.org/cgit/cgit.cgi/poky/log/\">Yocto Project master branch</a>, where active development takes place. This is not a stable branch, so your builds might not work as expected." + }, + { + "name": "fido", + "description": "Yocto Project 1.8 Fido", + "bitbake": "fido", + "branch": "fido", + "defaultlayers": [ "openembedded-core", "meta-yocto", "meta-yocto-bsp"], + "layersourcepriority": { "Imported layers": 99, "Local Yocto Project" : 10, "OpenEmbedded" : 0 }, + "helptext": "Toaster will run your builds with the tip of the <a href=\"http://git.yoctoproject.org/cgit/cgit.cgi/poky/log/?h=fido\">Yocto Project 1.8 \"Fido\"</a> branch." + }, + { + "name": "dizzy", + "description": "Yocto Project 1.7 Dizzy", + "bitbake": "dizzy", + "branch": "dizzy", + "defaultlayers": [ "openembedded-core", "meta-yocto", "meta-yocto-bsp"], + "layersourcepriority": { "Imported layers": 99, "Local Yocto Project" : 10, "OpenEmbedded" : 0 }, + "helptext": "Toaster will run your builds with the tip of the <a href=\"http://git.yoctoproject.org/cgit/cgit.cgi/poky/log/?h=dizzy\">Yocto Project 1.7 \"Dizzy\"</a> branch." + }, + { + "name": "local", + "description": "Local Yocto Project", + "bitbake": "HEAD", + "branch": "HEAD", + "defaultlayers": [ "openembedded-core", "meta-yocto", "meta-yocto-bsp"], + "layersourcepriority": { "Imported layers": 99, "Local Yocto Project" : 10, "OpenEmbedded" : 0 }, + "helptext": "Toaster will run your builds with the version of the Yocto Project you have cloned or downloaded to your computer." + } + ] + </literallayout> + </para> + </section> + </section> + </section> + + <section id='toaster-useful-commands'> + <title>Useful Commands</title> + + <para> + In addition to the web user interface and the scripts that start + and stop Toaster, command-line commands exist through the + <filename>manage.py</filename> management script. + You can find general documentation on + <filename>manage.py</filename> at the + <ulink url='https://docs.djangoproject.com/en/1.7/topics/settings/'>Django</ulink> + site. + However, several <filename>manage.py</filename> commands have been + created that are specific to Toaster and are used to control + configuration and back-end tasks. + You can locate these commands in the + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> + (e.g. <filename>poky</filename>) at + <filename>bitbake/lib/manage.py</filename>. + This section documents those commands. + <note> + <para> + When using <filename>manage.py</filename> commands given + a default configuration, you must be sure that your + working directory is set to the + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. + Using <filename>manage.py</filename> commands from the + Build Directory allows Toaster to find the + <filename>toaster.sqlite</filename> file, which is located + in the Build Directory. + </para> + + <para> + For non-default database configurations, it is possible + that you can use <filename>manage.py</filename> commands + from a directory other than the Build directory. + To do so, the + <filename>toastermain/settings.py</filename> file must be + configured to point to the correct database backend. + </para> + </note> + </para> + + <section id='toaster-command-buildslist'> + <title><filename>buildslist</filename></title> + + <para> + The <filename>buildslist</filename> command lists all builds + that Toaster has recorded. + Access the command as follows: + <literallayout class='monospaced'> + $ bitbake/lib/toaster/manage.py buildslist + </literallayout> + The command returns a list, which includes numeric + identifications, of the builds that Toaster has recorded in the + current database. + </para> + + <para> + You need to run the <filename>buildslist</filename> command + first to identify existing builds in the database before + using the + <link linkend='toaster-command-builddelete'><filename>builddelete</filename></link> + command. + Here is an example that assumes default repository and build + directory names: + <literallayout class='monospaced'> + $ cd ~/poky/build + $ python ../bitbake/lib/toaster/manage.py buildslist + </literallayout> + If your Toaster database had only one build, the above + <filename>buildslist</filename> command would return something + like the following: + <literallayout class='monospaced'> + 1: qemux86 poky core-image-minimal + </literallayout> + </para> + </section> + + <section id='toaster-command-builddelete'> + <title><filename>builddelete</filename></title> + + <para> + The <filename>builddelete</filename> command deletes data + associated with a build. + Access the command as follows: + <literallayout class='monospaced'> + $ bitbake/lib/toaster/manage.py builddelete <replaceable>build_id</replaceable> + </literallayout> + The command deletes all the build data for the specified + <replaceable>build_id</replaceable>. + This command is useful for removing old and unused data from + the database. + </para> + + <para> + Prior to running the <filename>builddelete</filename> + command, you need to get the ID associated with builds + by using the + <link linkend='toaster-command-buildslist'><filename>buildslist</filename></link> + command. + </para> + </section> + + <section id='toaster-command-perf'> + <title><filename>perf</filename></title> + + <para> + The <filename>perf</filename> command measures Toaster + performance. + Access the command as follows: + <literallayout class='monospaced'> + $ bitbake/lib/toaster/manage.py perf + </literallayout> + The command is a sanity check that returns page loading + times in order to identify performance problems. + </para> + </section> + + <section id='toaster-command-checksettings'> + <title><filename>checksettings</filename></title> + + <para> + The <filename>checksettings</filename> command verifies + existing Toaster settings. + Access the command as follows: + <literallayout class='monospaced'> + $ bitbake/lib/toaster/manage.py checksettings + </literallayout> + In Build Mode, Toaster uses settings that are based on the + database to configure the building tasks. + The <filename>checksettings</filename> command verifies that + the database settings are valid in the sense that they have + the minimal information needed to start a build. + </para> + + <para> + In order for the <filename>checksettings</filename> command + to work, the database must be correctly set up and not have + existing data. + To be sure the database is ready, you can run the following: + <literallayout class='monospaced'> + $ bitbake/lib/toaster/manage.py syncdb + $ bitbake/lib/toaster/manage.py migrate orm + $ bitbake/lib/toaster/manage.py migrate bldcontrol + </literallayout> + After running these commands, you can run the + <filename>checksettings</filename> command. + </para> + </section> + + <section id='toaster-command-loadconf'> + <title><filename>loadconf</filename></title> + + <para> + The <filename>loadconf</filename> command loads an + existing Toaster configuration file (JSON file). + You must run this on a new database that does not have any + data. + Running this command on an existing database that has data + results in errors. + Access the command as follows: + <literallayout class='monospaced'> + $ bitbake/lib/toaster/manage.py loadconf <replaceable>filepath</replaceable> + </literallayout> + The <filename>loadconf</filename> command configures a database + based on the supplied existing + <filename>toasterconf.json</filename> file. + For information on the <filename>toasterconf.json</filename>, + see the + "<link linkend='toaster-json-files'>JSON Files</link>" + section. + </para> + </section> + + <section id='toaster-command-runbuilds'> + <title><filename>runbuilds</filename></title> + + <para> + The <filename>runbuilds</filename> command launches + scheduled builds. + Access the command as follows: + <literallayout class='monospaced'> + $ bitbake/lib/toaster/manage.py runbuilds + </literallayout> + The <filename>runbuilds</filename> command checks if + scheduled builds exist in the database and then launches them + per schedule. + The command returns after the builds start but before they + complete. + The Toaster Logging Interface records and updates the database + when the builds complete. + </para> + </section> + </section> +</chapter> diff --git a/documentation/toaster-manual/toaster-manual-setup-and-use.xml b/documentation/toaster-manual/toaster-manual-setup-and-use.xml new file mode 100644 index 0000000000..a1546858d9 --- /dev/null +++ b/documentation/toaster-manual/toaster-manual-setup-and-use.xml @@ -0,0 +1,1024 @@ +<!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='toaster-manual-setup-and-use'> + +<title>Setting Up and Using Toaster</title> + + <section id='using-toaster-in-analysis-mode'> + <title>Using Toaster in Analysis Mode</title> + + <para> + This section describes how to use Toaster in Analysis Mode + after setting Toaster up as a local instance or as a hosted + service. + </para> + + <section id='setting-up-locally-and-running-in-analysis-mode'> + <title>Setting Up Locally and Running in Analysis Mode</title> + + <para> + Follow these steps to set up a local instance of Toaster and + then run in Analysis Mode: + <orderedlist> + <listitem><para><emphasis>Prepare your Build System:</emphasis> + Be sure your system has the Toaster requirements + by following the steps in the + "<link linkend='toaster-establishing-toaster-system-dependencies'>Establishing Toaster System Dependencies</link>" + section. + </para></listitem> + <listitem><para><emphasis>Get Set Up to Use the Yocto Project:</emphasis> + Get the requirements set up so that you can use the + Yocto Project to build images. + See the + "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>What You Need and How You Get It</ulink>" + section in the Yocto Project Quick Start for information. + </para></listitem> + <listitem><para><emphasis>Source your Build Environment Setup Script:</emphasis> + From your + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> + (e.g. <filename>poky/build</filename>), source the build + environment setup script + <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></listitem> + <listitem><para><emphasis>Start Toaster:</emphasis> + From the + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>, + start Toaster: + <literallayout class='monospaced'> + $ source toaster start + </literallayout> + </para></listitem> + <listitem><para><emphasis>Start Your Build Using BitBake:</emphasis> + Use the <filename>bitbake</filename> command to start your + build. + Here is an example that builds the + <filename>core-image-minimal</filename> image: + <literallayout class='monospaced'> + $ bitbake core-image-minimal + </literallayout> + </para></listitem> + <listitem><para><emphasis>Open Your Browser:</emphasis> + Open your browser and visit + <filename>http://host:port/toastergui</filename>. + For host and port values, see the output of the + <filename>source toaster start</filename> command. + For information on how to use Toaster, see the + "<link linkend='using-the-toaster-web-interface'>Using the Toaster Web Interface</link>" + section. + </para></listitem> + </orderedlist> + </para> + + <para> + + </para> + </section> + + <section id='setting-up-a-hosted-service-and-running-in-analysis-mode'> + <title>Setting Up a Hosted Service and Running in Analysis Mode</title> + + <para> + A hosted service resides on a shared server and allows + multiple users to take advantage of Toaster. + </para> + + <para> + In a production environment, you might want to have multiple + local instances of the Toaster Logging Interface running on + various remote build machines, and have those local instances + access and use a single web server. + To do this, you need to do the following: + <itemizedlist> + <listitem><para> + Maintain a common SQL database. + </para></listitem> + <listitem><para> + Set up separate instances of BitBake servers + and Toaster Logging Interfaces for each of those + separate BitBake servers. + </para></listitem> + </itemizedlist> + </para> + + <para> + The common SQL database allows the Web server to show data from + all the various BitBake builds. + Setting the SQL database outside of any + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> + maintains a separation between the various builds. + The BitBake servers, the SQL server, and the Web server or + servers can be run on separate machines. + </para> + + <para> + Follow these steps to set up and run a hosted service and run + Toaster in Analysis Mode: + <note> + The steps assume a Toaster installation path of + <filename>/opt/bitbake/</filename>. + </note> + <orderedlist> + <listitem><para><emphasis>Prepare your Build System:</emphasis> + Be sure your system has the Toaster requirements + by following the steps in the + "<link linkend='toaster-establishing-toaster-system-dependencies'>Establishing Toaster System Dependencies</link>" + section. + </para></listitem> + <listitem><para><emphasis>Get Set Up to Use the Yocto Project:</emphasis> + Get the requirements set up so that you can use the + Yocto Project to build images. + See the + "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>What You Need and How You Get It</ulink>" + section in the Yocto Project Quick Start for information. + </para></listitem> + <listitem><para><emphasis>Install and Set up the Database Server:</emphasis> + You can use any SQL server out of the box. + It is recommended that you use + <filename>mysql-server</filename> because it has + the advantages of advanced SQL features along with a + fast and reliable database. + However, setting up <filename>mysql-server</filename> + is more complex and might require a Database + Administrator to tune it.</para> + <para>Another supported database backend is + <filename>sqlite3</filename>. + With <filename>sqlite3</filename>, you have the + advantage of no configuration and an easy installation. + However, Toaster still requires direct access to the + backend. + The <filename>sqlite</filename> backend is also slower + as compared to <filename>mysql-server</filename>, and + has no transactional support.</para> + <para>You should set up proper username and password + access on the shared database for everyone that will + be using Toaster. + You need administrator rights for the root account, + which is not the same thing as root access on the + machine. + Here is an example that installs + <filename>mysql-server</filename> and sets up + some user accounts and the database. + <literallayout class='monospaced'> + $ apt-get install mysql-server + $ mysql -u root + mysql> CREATE USER 'newuser'@'localhost' IDENTIFIED BY 'password'; + mysql> GRANT ALL PRIVILEGES ON * . * TO 'newuser'@'localhost'; + mysql> GRANT ALL PRIVILEGES ON * . * TO 'newuser'@'localhost'; + mysql> CREATE DATABASE 'toaster'; + </literallayout> + You need a separate clone of the + <ulink url='&YOCTO_DOCS_DEV_URL;#source-repositories'>Source Repositories</ulink> + for the Database Server. + This clone is only used for getting the latest Toaster + files. + You can set this up using the following Git command. + Be sure to set up the directory outside of any + Build Directories. + <literallayout class='monospaced'> + $ git clone git://git.yoctoproject.org/poky + </literallayout> + In the separately cloned tree for the Database Server, + edit the + <filename>bitbake/lib/toaster/toastermain/settings.py</filename> + file so that the <filename>DATABASES</filename> value + points to the previously created database server. + Use the username and password established + earlier. + Here is an example: + <literallayout class='monospaced'> + $ cat /opt/bitbake/lib/toaster/toastermain/settings.py + ... + DATABASES = { + 'default': { + 'ENGINE': 'django.db.backends.mysql', + 'NAME': 'toaster', + 'USER': 'newuser', + 'PASSWORD': 'password', + 'HOST': '192.168.0.25', + 'PORT': '3306', + } + ... + </literallayout> + </para></listitem> + <listitem><para><emphasis>Install and Set Up the Web Server:</emphasis> + For a production environment, it is recommended that + you install and set up a front-end web server. + This server allows for load balancing and + multi-threading over Toaster and + <ulink url='https://docs.djangoproject.com/en/1.7/howto/deployment/wsgi/'><filename>django</filename> WSGI</ulink>. + Here is an example that uses Apache web server. + <literallayout class='monospaced'> + $ apt-get install apache2 libapache2-mod-wsgi + $ a2enmod wsgi + $ cat /etc/apache2/sites-available/000-default.conf + + ... + + # the WSGIPythonPath is global + WSGIPythonPath /opt/bitbake/lib/toaster/ + + ... + + #snip - in VirtualHost + WSGIScriptAlias / /opt/bitbake/lib/toaster/toastermain/wsgi.py + + <Directory //opt/bitbake/lib/toaster/toastermain/> + <Files wsgi.py> + Require all granted + </Files> + </Directory> + + ... + </literallayout> + You need to collect static media from Toaster and + continue configuring Apache to serve that static + media: + <literallayout class='monospaced'> + $ mkdir /var/www.html/static && cd /var/www.html/static + $ /opt/bitbake/lib/toaster/manage.py collectstatic + $ cat /etc/apache2/sites-available/000-default.conf + + ... + + # in VirtualHost, AHEAD of the WSGIScriptAlias definition + Alias /static/ /var/www.html/static/ + + <Directory /var/www.html/static/> + Require all granted + </Directory> + + ... + + WSGIScript Alias / /opt/bitbake/lib/toaster/toastermain/wsgi.py + + ... + </literallayout> + </para></listitem> + <listitem><para><emphasis>Start Toaster:</emphasis> + Synchronize the databases for toaster, and then start + up the web server. + Here is an example that continues with the assumed + components from the previous steps: + <literallayout class='monospaced'> + $ /opt/bitbake/lib/toaster/manage.py syncdb + $ /opt/bitbake/lib/toaster/manage.py migrate orm + $ /opt/bitbake/lib/toaster/manage.py migrate bldcontrol + + $ service apache2 restart + </literallayout> + You can find general documentation on + <filename>manage.py</filename> at the + <ulink url='https://docs.djangoproject.com/en/1.7/ref/django-admin/'>Django</ulink> + site. + For reference information on Toaster-specific + <filename>manage.py</filename> commands, + see the + "<link linkend='toaster-useful-commands'>Useful Commands</link>" + section. + </para></listitem> + <listitem><para><emphasis>Enable Build Logging to the Common SQL Server for Each Build Directory you are Using:</emphasis> + You need to make sure that the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-toaster'><filename>toaster</filename></ulink> + class and build history are enabled. + This is done in a + <filename>toaster.conf</filename> file that is + created automatically by the toaster + <filename>start</filename> command, + and that lives inside the + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> + in <filename>/conf/toaster.conf</filename>.</para> + <para>That file should include the following line: + <literallayout class='monospaced'> + INHERIT += "toaster buildhistory" + </literallayout> + For information on build history, see the + "<ulink url='&YOCTO_DOCS_REF_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>" + section in the Yocto Project Development + Manual.</para> + <para>You also need to point to the database that you set + up in step 3. + You can do this by exporting the <filename>DATABASE_URL</filename> + variable as follows: + <literallayout class='monospaced'> + export DATABASE_URL=mysql://newuser:password@192.168.0.25:3306/toaster + </literallayout> + This example assumes that you are using + <filename>mysql-server</filename>. + The IP address should be the IP address of your + database server. + </para></listitem> + <listitem><para><emphasis>Source your Build Environment Setup Script:</emphasis> + From your + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> + on each of the build systems, + (e.g. <filename>poky/build</filename>), source the + build environment setup 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></listitem> + <listitem><para><emphasis>Start the BitBake Server:</emphasis> + Start the BitBake server using the following command: + <literallayout class='monospaced'> + $ bitbake --postread conf/toaster.conf --server-only -t xmlrpc -B localhost:0 && export BBSERVER=localhost:-1 + </literallayout> + </para></listitem> + <listitem><para><emphasis>Start the Logging Server:</emphasis> + Start the Toaster Logging Interface using the following + command: + <literallayout class='monospaced'> + $ nohup bitbake --observe-only -u toasterui >toaster_ui.log & + </literallayout> + <note> + No hard-coded ports are used in the BitBake options + as there is enough code to run + <filename>autodiscovery</filename> for BitBake + ports. + Doing so prevents collisions. + </note> + </para></listitem> + <listitem><para><emphasis>Start Builds Using BitBake:</emphasis> + Use the <filename>bitbake</filename> command to start a + build on a build system. + Here is an example that builds the + <filename>core-image-minimal</filename> image: + <literallayout class='monospaced'> + $ bitbake core-image-minimal + </literallayout> + When you are finished with a build in a given + Build Directory, be sure to <filename>kill</filename> + the BitBake server for that build area: + <literallayout class='monospaced'> + $ bitbake -m + </literallayout> + </para></listitem> + </orderedlist> + </para> + + <para> + For information on how to use the Toaster web interface, + see the + "<link linkend='using-the-toaster-web-interface'>Using the Toaster Web Interface</link>" + section. + </para> + </section> + </section> + + <section id='using-toaster-in-build-mode'> + <title>Using Toaster in Build Mode</title> + + <para> + This section describes how to use Toaster in Build Mode + after setting Toaster up as a local instance or as a hosted + service. + </para> + + <section id='setting-up-locally-and-running-in-build-mode'> + <title>Setting Up Locally and Running in Build Mode</title> + + <para> + Follow these steps to set up a local instance of Toaster and + then run in Build Mode: + <orderedlist> + <listitem><para><emphasis>Prepare your Build System:</emphasis> + Be sure your system has the Toaster requirements + by following the steps in the + "<link linkend='toaster-establishing-toaster-system-dependencies'>Establishing Toaster System Dependencies</link>" + section. + </para></listitem> + <listitem><para><emphasis>Get Set Up to Use the Yocto Project:</emphasis> + Get the requirements set up so that you can use the + Yocto Project to build images. + See the + "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>What You Need and How You Get It</ulink>" + section in the Yocto Project Quick Start for information. + </para></listitem> + <listitem><para><emphasis>Start Toaster:</emphasis> + From the root of the source directory (e.g + <filename>poky/</filename>), run the following command: + <literallayout class='monospaced'> + $ bitbake/bin/toaster + </literallayout> + </para></listitem> + <listitem><para><emphasis>Create a Superuser:</emphasis> + Django will ask you if you want to create a superuser. + You can skip this step, but it is recommended that you + create a superuser. + You can use the superuser to access the Django + administration interface and make changes to the + Toaster configuration. + </para></listitem> + <listitem><para><emphasis>Select the Build Log Directory:</emphasis> + Toaster asks you to specify the directory where you + want to store the build log files. + Choosing a directory for these files makes sure they + are always available to you. + If you do not choose a directory, the logs can + disappear (e.g. deleting the Build Directory).</para> + <para>When Toaster prompts you for the Build Log + directory, you can select the suggested default + or provide a path to a different directory. + </para></listitem> + <listitem><para><emphasis>Specify the Layer Checkout Directory:</emphasis> + Toaster asks you to specify the directory into which + layers are checked out. + Toaster clones any layers needed for your builds + inside this directory.</para> + <para>When Toaster prompts you for the Layer + checkout directory, you can select the suggested + default or provide a path to a different directory. + </para></listitem> + <listitem><para><emphasis>Specify the Build Directory Path:</emphasis> + Toaster asks you to specify the path to the + Build Directory. + You can select the suggested default or provide a + path to a different directory. + </para></listitem> + <listitem><para><emphasis>Choose Whether or not to Import a Default Toaster Configuration File:</emphasis> + Toaster asks you if you want to import a default + Toaster configuration file. + Toaster configurations are stored in + JSON files called + <filename>toasterconf.json</filename>. + For information on JSON files, see the + "<link linkend='toaster-json-files'>JSON Files</link>" + section.</para> + <para>You can skip importing a configuration file + by entering "0" at the prompt. + However, it is recommended that you import one of the + configuration files listed during this step. + You can always amend the imported configuration during + a later stage through the Django administration + interface.</para> + <para>For general information on Django, see the + available + <ulink url='https://docs.djangoproject.com/en/1.7/'>documentation</ulink>. + You can also find information on Toaster-specific + <filename>manage.py</filename> commands in the + "<link linkend='toaster-useful-commands'>Useful Commands</link>" + section. + </para></listitem> + <listitem><para><emphasis>Open the Browser:</emphasis> + If no browser window appears, open your favorite + browser and enter the following: + <literallayout class='monospaced'> + http://localhost:8000/toastergui + </literallayout> + You can now use the Toaster web interface. + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='setting-up-a-hosted-service-and-running-in-build-mode'> + <title>Setting Up a Hosted Service and Running in Build Mode</title> + + <para> + Follow these steps to set up a hosted service and run Toaster + in Build Mode: + <orderedlist> + <listitem><para><emphasis>Prepare your Build System:</emphasis> + Be sure your system has the Toaster requirements + by following the steps in the + "<link linkend='toaster-establishing-toaster-system-dependencies'>Establishing Toaster System Dependencies</link>" + section. + </para></listitem> + <listitem><para><emphasis>Get Set Up to Use the Yocto Project:</emphasis> + Get the requirements set up so that you can use the + Yocto Project to build images. + See the + "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>What You Need and How You Get It</ulink>" + section in the Yocto Project Quick Start for information. + </para></listitem> + <listitem><para><emphasis>Be Sure Management is Enabled:</emphasis> + If you are running Toaster under Apache, you need to + be sure management is enabled. + To enable management, set + <filename>MANAGED</filename> to "True" by adding + the following to the + <filename>bitbake/lib/toaster/settings.py</filename> + file: + <literallayout class='monospaced'> + MANAGED="True" + </literallayout> + </para></listitem> + <listitem><para><emphasis>Set Up Toaster for Normal Usage:</emphasis> + You need to configure each build environment, layer + sources, and BitBake versions.</para> + <para>Verify that your releases have been loaded correctly by + using the Toaster web interface to create a new + project. + Check the "Releases" dropdown menu to be sure your + newly specified releases exist.</para> + <para>If you want to use the administration interface + for this step, here is a set of example commands + with some descriptions as an example: + <literallayout class='monospaced'> + # Create the user under which the builds will run + $ adduser poky + + # Bring up the administration interface + $xdg-open http://<replaceable>server-address</replaceable>/admin/ + + # Login with the admin user previously created + + # Go to the BuildEnvironment object in Build Environments and + # set address to local host, sourcedir to /home/poky, and + # builddir to /home/pokybuild. + # + # Save your changes and exit + + # Go to Home, Layer Sources and select add Layer Source + # Name: OpenEmbedded, Sourcetype: layerindex, + # Apiurl: http://layers openembedded.org/layerindex/api/ + # Save your changes and exit + + # Go to Home, Bitbake Versions, Add bitbake version; + # Take version information from: http://git.openembedded.org/bitbake/refs/heads, + # This example assumes "master" version. + # set Name: master, Giturl git://git.openembedded.org/bitbake + # branch master, dirpath / + # Save your changes and exit + </literallayout> + You also need to configure the project releases, the + default variables, and update information from the + layer index. + Continuing with the example: + <literallayout class='monospaced'> + # Go to Home, Releases, Add release + # set Name: master, Description: Current master release, select Bitbake Version, + # and Branch: master + # Save your changes and exit + + # Go to Home, Toaster Settings, select the Setting for DEFAULT_RELEASE + # set Helptext: This selects the default release., Value: master + # Save your changes and exit + + # Go to Home, Bitbake Versions, Add bitbake version; + # take version information from : http://git.openembedded.org/bitbake/refs/heads, + # this manual assumes the master version + # set Name: master, Giturl git://git.openembedded.org/bitbake + # branch master, dirpath / + # Save your changes and exit + + # Update the information + # bitbake/lib/toaster/manage.py lsupdates + </literallayout> + For reference information on Toaster-specific + <filename>manage.py</filename> commands, see the + "<link linkend='toaster-useful-commands'>Useful Commands</link>" + section. + </para></listitem> + <listitem><para><emphasis>Install and Set up the Database Server:</emphasis> + You can use any SQL server out of the box. + It is recommended that you use + <filename>mysql-server</filename> because it has + the advantages of advanced SQL features along with a + fast and reliable database. + However, setting up <filename>mysql-server</filename> + is more complex and might require a Database + Administrator to tune it.</para> + <para>Another supported database backend is + <filename>sqlite3</filename>. + With <filename>sqlite3</filename>, you have the + advantage of no configuration and an easy installation. + However, Toaster still requires direct access to the + backend. + The <filename>sqlite</filename> backend is also slower + as compared to <filename>mysql-server</filename>, and + has no transactional support.</para> + <para>You should set up proper username and password + access on the shared database for everyone that will + be using Toaster. + You need administrator rights for the root account, + which is not the same thing as root access on the + machine. + Here is an example that installs + <filename>mysql-server</filename> and sets up + some user accounts and the database. + <literallayout class='monospaced'> + $ apt-get install mysql-server + $ mysql -u root + mysql> CREATE USER 'newuser'@'localhost' IDENTIFIED BY 'password'; + mysql> GRANT ALL PRIVILEGES ON * . * TO 'newuser'@'localhost'; + mysql> GRANT ALL PRIVILEGES ON * . * TO 'newuser'@'localhost'; + mysql> CREATE DATABASE 'toaster'; + </literallayout> + You need a separate clone of the + <ulink url='&YOCTO_DOCS_DEV_URL;#source-repositories'>Source Repositories</ulink> + for the Database Server. + This clone is only used for getting the latest Toaster + files. + You can set this up using the following Git command. + Be sure to set up the directory outside of any + Build Directories. + <literallayout class='monospaced'> + $ git clone git://git.yoctoproject.org/poky + </literallayout> + In the separately cloned tree for the Database Server, + edit the + <filename>bitbake/lib/toaster/toastermain/settings.py</filename> + file so that the <filename>DATABASES</filename> value + points to the previously created database server. + Use the username and password established + earlier. + Here is an example: + <literallayout class='monospaced'> + $ cat /opt/bitbake/lib/toaster/toastermain/settings.py + ... + DATABASES = { + 'default': { + 'ENGINE': 'django.db.backends.mysql', + 'NAME': 'toaster', + 'USER': 'newuser', + 'PASSWORD': 'password', + 'HOST': '192.168.0.25', + 'PORT': '3306', + } + ... + </literallayout> + </para></listitem> + <listitem><para><emphasis>Create the Database</emphasis> + Use the following commands to create the default + database structure: + <literallayout class='monospaced'> + $ bitbake/lib/toaster/manage.py syncdb + $ bitbake/lib/toaster/manage.py migrate orm + $ bitbake/lib/toaster/manage.py migrate bldcontrol + </literallayout> + The interface asks you if you want to create a + superuser. + Do not skip this step. + You will use the superuser account to access the + administration interface and make changes to the + Toaster configuration. + </para></listitem> + <listitem><para><emphasis>Select Where the Build Process Takes Place:</emphasis> + You need to create three directories for storing + build artifacts, downloading sources, and running + builds. + All three directories need to be writable by + the user, which is "poky" in this example. + The build artifacts directory needs to readable by the + apache user. + You also need free disk space in the range of + 100 Gbytes. + Following are three suggested directories: + <literallayout class='monospaced'> + /home/poky/buildartifacts/ + /home/poky/build/ + /home/poky/sources/ + </literallayout> + </para></listitem> + <listitem><para><emphasis>Set Up the <filename>toasterconf.json</filename> File:</emphasis> + <ulink url='https://wiki.yoctoproject.org/wiki/File:Toasterconf.json.txt.patch'>Download the hosted <filename>toasterconf.json</filename> file</ulink> + from the Yocto Project wiki and edit it to suit your + environment. + For information on the relevant sections of the file, + see the + "<link linkend='toaster-json-files'>JSON Files</link>" + section.</para> + <para>After editing the file, load it by running + the following: + <literallayout class='monospaced'> + $ bitbake/lib/toaster/manage.py loadconf path-to-toasterconf.json-file + </literallayout> + For reference information on Toaster-specific + <filename>manage.py</filename>, see the + "<link linkend='toaster-useful-commands'>Useful Commands</link>" + section. + </para></listitem> + <listitem><para><emphasis>Check the Toaster Settings:</emphasis> + Configure the build environment by running the + following: + <literallayout class='monospaced'> + $ bitbake/lib/toaster/manage.py checksettings + </literallayout> + When prompted, paste in the directory paths created + previously during Step 7. + For reference information on Toaster-specific + <filename>manage.py</filename>, see the + "<link linkend='toaster-useful-commands'>Useful Commands</link>" + section. + </para></listitem> + <listitem><para><emphasis>Install and Set Up the Web Server:</emphasis> + For a production environment, it is recommended that + you install and set up a front-end web server. + This server allows for load balancing and + multi-threading over Toaster and + <ulink url='https://docs.djangoproject.com/en/1.7/howto/deployment/wsgi/'><filename>django</filename> WSGI</ulink>. + Here is an example that uses Apache web server: + <literallayout class='monospaced'> + $ apt-get install apache2 libapache2-mod-wsgi + $ a2enmod wsgi + $ cat /etc/apache2/sites-available/000-default.conf + + ... + + # the WSGIPythonPath is global + WSGIPythonPath /opt/bitbake/lib/toaster/ + + ... + + #snip - in VirtualHost + WSGIScriptAlias / /opt/bitbake/lib/toaster/toastermain/wsgi.py + + <Directory //opt/bitbake/lib/toaster/toastermain/> + <Files wsgi.py> + Require all granted + </Files> + </Directory> + + ... + </literallayout> + You need to collect static media from Toaster and + continue configuring Apache to serve that static + media: + <literallayout class='monospaced'> + $ mkdir /var/www.html/static && cd /var/www.html/static + $ /opt bitbake/lib/toaster/manage.py collectstatic + $ cat /etc/apache2/sites-available/000-default.conf + + ... + + # in VirtualHost, AHEAD of the WSGIScriptAlias definition + Alias /static/ /var/www.html/static/ + + <Directory /var/www.html/static/> + Require all granted + </Directory> + + ... + + WSGIScript Alias / /opt/bitbake/lib/toaster/toastermain/wsgi.py + + ... + </literallayout> + </para></listitem> + <listitem><para><emphasis>Start Toaster:</emphasis> + Synchronize the databases for Toaster, and then start + up the web server. + Here is an example that continues with the assumed + components from the previous steps: + <literallayout class='monospaced'> + $ /opt/bitbake/lib/toaster/manage.py syncdb + $ /opt/bitbake/lib/toaster/manage.py migrate orm + $ /opt/bitbake/lib/toaster/manage.py migrate bldcontrol + + $ service apache2 restart + </literallayout> + For reference information on the + <filename>manage.py</filename> commands used here, + see the + "<link linkend='toaster-useful-commands'>Useful Commands</link>" + section. + </para></listitem> + <listitem><para><emphasis>Set up Build Control and Open the Web Interface:</emphasis> + You need to run the build control manager. + You can do this as shown in the following example: + <literallayout class='monospaced'> + # as the "poky" user, start the runbuilds command in a loop (or put it in crontab!) + $ sudo -i -u poky + $ while true; do /opt/bitbake/lib/toaster/manage.py runbuilds; sleep 10; done + + # open up the web interface + $ xdg-open http://[server-address]/toastergui/ + </literallayout> + It is suggested that you enable build control by + setting <filename>runbuilds</filename> in the + <filename>crontab</filename> as follows: + <literallayout class='monospaced'> + $ crontab -l + * * * * * /opt/bitbake/lit/toaster/manage.py runbuilds + </literallayout> + </para></listitem> + <listitem><para><emphasis>Open the Browser:</emphasis> + Once the Apache server is running, connect to it with + your favorite browser and verify that the Toaster + interface comes up: + <literallayout class='monospaced'> + http://localhost:8000/toastergui + </literallayout> + You can track accesses and errors in the Apache + service logs. + </para></listitem> + </orderedlist> + </para> + </section> + </section> + + <section id='using-the-toaster-web-interface'> + <title>Using the Toaster Web Interface</title> + + <para> + The Toaster web interface allows you to do the following: + <itemizedlist> + <listitem><para> + Browse published layers in the + <ulink url='http://layers.openembedded.org'>OpenEmbedded Metadata Index</ulink> + that are available for your selected version of the build + system. + </para></listitem> + <listitem><para> + Import your own layers for building. + </para></listitem> + <listitem><para> + Add and remove layers from your configuration. + </para></listitem> + <listitem><para> + Set configuration variables. + </para></listitem> + <listitem><para> + Select a target or multiple targets to build. + </para></listitem> + <listitem><para> + Start your builds. + </para></listitem> + <listitem><para> + See what was built (recipes and packages) and what + packages were installed into your final image. + </para></listitem> + <listitem><para> + Browse the directory structure of your image. + </para></listitem> + <listitem><para> + See the value of all variables in your build configuration, + and which files set each value. + </para></listitem> + <listitem><para> + Examine error, warning and trace messages to aid in + debugging. + </para></listitem> + <listitem><para> + See information about the BitBake tasks executed and + reused during your build, including those that used + shared state. + </para></listitem> + <listitem><para> + See dependency relationships between recipes, packages + and tasks. + </para></listitem> + <listitem><para> + See performance information such as build time, task time, + CPU usage, and disk I/O. + </para></listitem> + </itemizedlist> + Following are several videos that show how to use the Toaster GUI: + <itemizedlist> + <listitem><para><emphasis>Build Configuration:</emphasis> + This + <ulink url='https://www.youtube.com/watch?v=qYgDZ8YzV6w'>video</ulink> + overviews and demonstrates build configuration for Toaster. + </para></listitem> + <listitem><para><emphasis>Toaster Homepage and Table Controls:</emphasis> + This + <ulink url='https://www.youtube.com/watch?v=QEARDnrR1Xw'>video</ulink> + goes over the Toaster entry page, and provides + an overview of the data manipulation capabilities of + Toaster, which include search, sorting and filtering by + different criteria. + </para></listitem> + <listitem><para><emphasis>Build Dashboard:</emphasis> + This + <ulink url='https://www.youtube.com/watch?v=KKqHYcnp2gE'>video</ulink> + shows you the build dashboard, a page providing an + overview of the information available for a selected build. + </para></listitem> + <listitem><para><emphasis>Image Information:</emphasis> + This + <ulink url='https://www.youtube.com/watch?v=XqYGFsmA0Rw'>video</ulink> + walks through the information Toaster provides + about images: packages installed and root file system. + </para></listitem> + <listitem><para><emphasis>Configuration:</emphasis> + This + <ulink url='https://www.youtube.com/watch?v=UW-j-T2TzIg'>video</ulink> + provides Toaster build configuration information. + </para></listitem> + <listitem><para><emphasis>Tasks:</emphasis> + This + <ulink url='https://www.youtube.com/watch?v=D4-9vGSxQtw'>video</ulink> + shows the information Toaster provides about the + tasks run by the build system. + </para></listitem> + <listitem><para><emphasis>Recipes and Packages Built:</emphasis> + This + <ulink url='https://www.youtube.com/watch?v=x-6dx4huNnw'>video</ulink> + shows the information Toaster provides about recipes + and packages built. + </para></listitem> + <listitem><para><emphasis>Performance Data:</emphasis> + This + <ulink url='https://www.youtube.com/watch?v=qWGMrJoqusQ'>video</ulink> + shows the build performance data provided by + Toaster. + </para></listitem> + </itemizedlist> + </para> + </section> + +<!-- + <section id='toaster-gui-vids-1'> + <title>Toaster Homepage and Table Controls</title> + + <para> + This video goes over the Toaster entry page, and provides + an overview of the data manipulation capabilities of Toaster, + which include search, sorting and filtering by different + criteria. + <mediaobject> + <videoobject> + <videodata width="640" height="480" fileref="http://www.youtube.com/v/QEARDnrR1Xw"></videodata> + </videoobject> + </mediaobject> + </para> + </section> + + <section id='toaster-gui-vids-2'> + <title>Build Dashboard</title> + + <para> + This video shows you the build dashboard, a page providing an + overview of the information available for a selected build. + <mediaobject> + <videoobject> + <videodata width="640px" height="480px" fileref="http://www.youtube.com/v/KKqHYcnp2gE"></videodata> + </videoobject> + </mediaobject> + </para> + </section> + + <section id='toaster-gui-vids-3'> + <title>Image Information</title> + + <para> + This video walks through the information Toaster provides + about images: packages installed and root file system. + <mediaobject> + <videoobject> + <videodata width="640px" height="480px" fileref="http://www.youtube.com/v/XqYGFsmA0Rw"></videodata> + </videoobject> + </mediaobject> + </para> + </section> + + <section id='toaster-gui-vids-4'> + <title>Configuration</title> + + <para> + This video shows the information Toaster provides about build + configuration. + <mediaobject> + <videoobject> + <videodata width="640px" height="480px" fileref="http://www.youtube.com/v/UW-j-T2TzIg"></videodata> + </videoobject> + </mediaobject> + </para> + </section> + + <section id='toaster-gui-vids-5'> + <title>Tasks</title> + + <para> + This video shows the information Toaster provides about the + tasks run by the build system. + <mediaobject> + <videoobject> + <videodata width="640px" height="480px" fileref="http://www.youtube.com/v/D4-9vGSxQtw"></videodata> + </videoobject> + </mediaobject> + </para> + </section> + + <section id='toaster-gui-vids-6'> + <title>Recipes and Packages Built</title> + + <para> + This video shows the information Toaster provides about recipes + and packages built. + <mediaobject> + <videoobject> + <videodata width="640px" height="480px" fileref="http://www.youtube.com/v/x-6dx4huNnw"></videodata> + </videoobject> + </mediaobject>qYgDZ8YzV6w + </para> + </section> + <section id='toaster-gui-vids-7'> + <title>Performance Data</title> + + <para> + This video shows the build performance data provided by + Toaster. + <mediaobject> + <videoobject> + <videodata width="640px" height="480px" fileref="http://www.youtube.com/v/qWGMrJoqusQ"></videodata> + </videoobject> + </mediaobject> + </para> + </section> +--> +</chapter> diff --git a/documentation/toaster-manual/toaster-manual-start.xml b/documentation/toaster-manual/toaster-manual-start.xml new file mode 100644 index 0000000000..65340a1b5e --- /dev/null +++ b/documentation/toaster-manual/toaster-manual-start.xml @@ -0,0 +1,141 @@ +<!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='toaster-manual-start'> + +<title>Preparing to Use Toaster</title> + + <para> + This chapter describes how you need to prepare your system in order to + use Toaster. + </para> + + <section id='toaster-setting-up-the-basic-system-requirements'> + <title>Setting Up the Basic System Requirements</title> + + <para> + You first need to be sure your build system is set up to run + the Yocto Project. + See the + "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>What You Need and How You Get It</ulink>" + section in the Yocto Project Quick Start for information on how + to set up your system for the Yocto Project. + </para> + </section> + + <section id='toaster-establishing-toaster-system-dependencies'> + <title>Establishing Toaster System Dependencies</title> + + <para> + Toaster requires extra Python dependencies and + <ulink url='http://www.libslack.org/daemon/'><filename>daemon</filename></ulink> + in order to run. + A Toaster requirements file named + <filename>toaster-requirements.txt</filename> defines the + Python dependencies. + The requirements file is located in the + <filename>bitbake</filename> directory, which is located in the + root directory of the + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> + (e.g. <filename>poky/bitbake/toaster-requirements.txt</filename>). + The dependencies appear in a <filename>pip</filename>, + install-compatible format. + </para> + + <section id='toaster-optional-virtual-environment'> + <title>Optionally Setting Up a Python Virtual Environment</title> + + <para> + It is highly recommended that you use a Python virtual + environment that allows you to maintain a dedicated Python + executable and its own set of installed modules. + Doing so separates the executable from the Python and modules + provided by the operating system and therefore avoids any + version conflicts. + </para> + + <para> + Follow these steps to set up your virtual environment. + These steps assume a Ubuntu distribution: + <orderedlist> + <listitem><para><emphasis>Install <filename>virtualenv</filename>:</emphasis> + Install the supported + <filename>python-virtualenv</filename> package from your + distribution rather than using <filename>pip</filename>. + <literallayout class='monospaced'> + $ sudo apt-get install python-virtualenv + </literallayout> + </para></listitem> + <listitem><para><emphasis>Create and Activate a Virtual Environment:</emphasis> + <literallayout class='monospaced'> + $ virtualenv venv + $ source venv/bin/activate + </literallayout> + </para></listitem> + </orderedlist> + <note> + If you do choose to set up a virtual environment in + which to run Toaster, you must initialize that + virtual environment each time you want to start + Toaster. + Use the following to initialize the environment just + before you start Toaster: + <literallayout class='monospaced'> + $ source venv/bin/activate + </literallayout> + </note> + </para> + </section> + + <section id='toaster-load-packages'> + <title>Install Toaster Packages</title> + + <para> + You need to install the packages that Toaster requires. + Use this command: + <literallayout class='monospaced'> + $ pip install -r bitbake/toaster-requirements.txt + </literallayout> + </para> + </section> + + <section id='toaster-install-daemon'> + <title>Install <filename>daemon</filename></title> + + <para> + Toaster depends on + <ulink url='http://www.libslack.org/daemon/'><filename>daemon</filename></ulink>. + Depending on your distribution, how you install + <filename>daemon</filename> differs: + <itemizedlist> + <listitem><para><emphasis>Debian-Based Systems:</emphasis> + If you are running a Debian-based distribution, + install <filename>daemon</filename> using the + following command: + <literallayout class='monospaced'> + $ sudo apt-get install daemon + </literallayout> + </para></listitem> + <listitem><para><emphasis>Non-Debian-Based Systems:</emphasis> + If you are not running a Debian-based distribution + (Redhat-based distribution such as Fedora), + you need to download the file relevant to the + architecture and then install + <filename>daemon</filename> manually. + Following are the commands for 64-bit distributions: + <literallayout class='monospaced'> + $ wget http://libslack.org/daemon/download/daemon-0.6.4-1.x86_64.rpm + $ sudo rpm -i daemon-0.6.4-1.x86_64.rpm + </literallayout> + Here are the commands for a 32-bit distribution: + <literallayout class='monospaced'> + $ wget http://libslack.org/daemon/download/daemon-0.6.4-1.i686.rpm + $ sudo rpm -i daemon-0.6.4-1.i686.rpm + </literallayout> + </para></listitem> + </itemizedlist> + </para> + </section> + </section> +</chapter> diff --git a/documentation/toaster-manual/toaster-manual-style.css b/documentation/toaster-manual/toaster-manual-style.css new file mode 100644 index 0000000000..6d6b9fb65d --- /dev/null +++ b/documentation/toaster-manual/toaster-manual-style.css @@ -0,0 +1,984 @@ +/* + Generic XHTML / DocBook XHTML CSS Stylesheet. + + Browser wrangling and typographic design by + Oyvind Kolas / pippin@gimp.org + + Customised for Poky by + Matthew Allum / mallum@o-hand.com + + Thanks to: + Liam R. E. Quin + William Skaggs + Jakub Steiner + + Structure + --------- + + The stylesheet is divided into the following sections: + + Positioning + Margins, paddings, width, font-size, clearing. + Decorations + Borders, style + Colors + Colors + Graphics + Graphical backgrounds + Nasty IE tweaks + Workarounds needed to make it work in internet explorer, + currently makes the stylesheet non validating, but up until + this point it is validating. + Mozilla extensions + Transparency for footer + Rounded corners on boxes + +*/ + + + /*************** / + / Positioning / +/ ***************/ + +body { + font-family: Verdana, Sans, sans-serif; + + min-width: 640px; + width: 80%; + margin: 0em auto; + padding: 2em 5em 5em 5em; + color: #333; +} + +h1,h2,h3,h4,h5,h6,h7 { + font-family: Arial, Sans; + color: #00557D; + clear: both; +} + +h1 { + font-size: 2em; + text-align: left; + padding: 0em 0em 0em 0em; + margin: 2em 0em 0em 0em; +} + +h2.subtitle { + margin: 0.10em 0em 3.0em 0em; + padding: 0em 0em 0em 0em; + font-size: 1.8em; + padding-left: 20%; + font-weight: normal; + font-style: italic; +} + +h2 { + margin: 2em 0em 0.66em 0em; + padding: 0.5em 0em 0em 0em; + font-size: 1.5em; + font-weight: bold; +} + +h3.subtitle { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; + font-size: 142.14%; + text-align: right; +} + +h3 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 140%; + font-weight: bold; +} + +h4 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 120%; + font-weight: bold; +} + +h5 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 110%; + font-weight: bold; +} + +h6 { + margin: 1em 0em 0em 0em; + padding: 1em 0em 0em 0em; + font-size: 110%; + font-weight: bold; +} + +.authorgroup { + background-color: transparent; + background-repeat: no-repeat; + padding-top: 256px; + background-image: url("figures/toaster-title.png"); + background-position: left top; + margin-top: -256px; + padding-right: 50px; + margin-left: 0px; + text-align: right; + width: 740px; +} + +h3.author { + margin: 0em 0me 0em 0em; + padding: 0em 0em 0em 0em; + font-weight: normal; + font-size: 100%; + color: #333; + clear: both; +} + +.author tt.email { + font-size: 66%; +} + +.titlepage hr { + width: 0em; + clear: both; +} + +.revhistory { + padding-top: 2em; + clear: both; +} + +.toc, +.list-of-tables, +.list-of-examples, +.list-of-figures { + padding: 1.33em 0em 2.5em 0em; + color: #00557D; +} + +.toc p, +.list-of-tables p, +.list-of-figures p, +.list-of-examples p { + padding: 0em 0em 0em 0em; + padding: 0em 0em 0.3em; + margin: 1.5em 0em 0em 0em; +} + +.toc p b, +.list-of-tables p b, +.list-of-figures p b, +.list-of-examples p b{ + font-size: 100.0%; + font-weight: bold; +} + +.toc dl, +.list-of-tables dl, +.list-of-figures dl, +.list-of-examples dl { + margin: 0em 0em 0.5em 0em; + padding: 0em 0em 0em 0em; +} + +.toc dt { + margin: 0em 0em 0em 0em; + padding: 0em 0em 0em 0em; +} + +.toc dd { + margin: 0em 0em 0em 2.6em; + padding: 0em 0em 0em 0em; +} + +div.glossary dl, +div.variablelist dl { +} + +.glossary dl dt, +.variablelist dl dt, +.variablelist dl dt span.term { + font-weight: normal; + width: 20em; + text-align: right; +} + +.variablelist dl dt { + margin-top: 0.5em; +} + +.glossary dl dd, +.variablelist dl dd { + margin-top: -1em; + margin-left: 25.5em; +} + +.glossary dd p, +.variablelist dd p { + margin-top: 0em; + margin-bottom: 1em; +} + + +div.calloutlist table td { + padding: 0em 0em 0em 0em; + margin: 0em 0em 0em 0em; +} + +div.calloutlist table td p { + margin-top: 0em; + margin-bottom: 1em; +} + +div p.copyright { + text-align: left; +} + +div.legalnotice p.legalnotice-title { + margin-bottom: 0em; +} + +p { + line-height: 1.5em; + margin-top: 0em; + +} + +dl { + padding-top: 0em; +} + +hr { + border: solid 1px; +} + + +.mediaobject, +.mediaobjectco { + text-align: center; +} + +img { + border: none; +} + +ul { + padding: 0em 0em 0em 1.5em; +} + +ul li { + padding: 0em 0em 0em 0em; +} + +ul li p { + text-align: left; +} + +table { + width :100%; +} + +th { + padding: 0.25em; + text-align: left; + font-weight: normal; + vertical-align: top; +} + +td { + padding: 0.25em; + vertical-align: top; +} + +p a[id] { + margin: 0px; + padding: 0px; + display: inline; + background-image: none; +} + +a { + text-decoration: underline; + color: #444; +} + +pre { + overflow: auto; +} + +a:hover { + text-decoration: underline; + /*font-weight: bold;*/ +} + +/* This style defines how the permalink character + appears by itself and when hovered over with + the mouse. */ + +[alt='Permalink'] { color: #eee; } +[alt='Permalink']:hover { color: black; } + + +div.informalfigure, +div.informalexample, +div.informaltable, +div.figure, +div.table, +div.example { + margin: 1em 0em; + padding: 1em; + page-break-inside: avoid; +} + + +div.informalfigure p.title b, +div.informalexample p.title b, +div.informaltable p.title b, +div.figure p.title b, +div.example p.title b, +div.table p.title b{ + padding-top: 0em; + margin-top: 0em; + font-size: 100%; + font-weight: normal; +} + +.mediaobject .caption, +.mediaobject .caption p { + text-align: center; + font-size: 80%; + padding-top: 0.5em; + padding-bottom: 0.5em; +} + +.epigraph { + padding-left: 55%; + margin-bottom: 1em; +} + +.epigraph p { + text-align: left; +} + +.epigraph .quote { + font-style: italic; +} +.epigraph .attribution { + font-style: normal; + text-align: right; +} + +span.application { + font-style: italic; +} + +.programlisting { + font-family: monospace; + font-size: 80%; + white-space: pre; + margin: 1.33em 0em; + padding: 1.33em; +} + +.tip, +.warning, +.caution, +.note { + margin-top: 1em; + margin-bottom: 1em; + +} + +/* force full width of table within div */ +.tip table, +.warning table, +.caution table, +.note table { + border: none; + width: 100%; +} + + +.tip table th, +.warning table th, +.caution table th, +.note table th { + padding: 0.8em 0.0em 0.0em 0.0em; + margin : 0em 0em 0em 0em; +} + +.tip p, +.warning p, +.caution p, +.note p { + margin-top: 0.5em; + margin-bottom: 0.5em; + padding-right: 1em; + text-align: left; +} + +.acronym { + text-transform: uppercase; +} + +b.keycap, +.keycap { + padding: 0.09em 0.3em; + margin: 0em; +} + +.itemizedlist li { + clear: none; +} + +.filename { + font-size: medium; + font-family: Courier, monospace; +} + + +div.navheader, div.heading{ + position: absolute; + left: 0em; + top: 0em; + width: 100%; + background-color: #cdf; + width: 100%; +} + +div.navfooter, div.footing{ + position: fixed; + left: 0em; + bottom: 0em; + background-color: #eee; + width: 100%; +} + + +div.navheader td, +div.navfooter td { + font-size: 66%; +} + +div.navheader table th { + /*font-family: Georgia, Times, serif;*/ + /*font-size: x-large;*/ + font-size: 80%; +} + +div.navheader table { + border-left: 0em; + border-right: 0em; + border-top: 0em; + width: 100%; +} + +div.navfooter table { + border-left: 0em; + border-right: 0em; + border-bottom: 0em; + width: 100%; +} + +div.navheader table td a, +div.navfooter table td a { + color: #777; + text-decoration: none; +} + +/* normal text in the footer */ +div.navfooter table td { + color: black; +} + +div.navheader table td a:visited, +div.navfooter table td a:visited { + color: #444; +} + + +/* links in header and footer */ +div.navheader table td a:hover, +div.navfooter table td a:hover { + text-decoration: underline; + background-color: transparent; + color: #33a; +} + +div.navheader hr, +div.navfooter hr { + display: none; +} + + +.qandaset tr.question td p { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; +} + +.qandaset tr.answer td p { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; +} +.answer td { + padding-bottom: 1.5em; +} + +.emphasis { + font-weight: bold; +} + + + /************* / + / decorations / +/ *************/ + +.titlepage { +} + +.part .title { +} + +.subtitle { + border: none; +} + +/* +h1 { + border: none; +} + +h2 { + border-top: solid 0.2em; + border-bottom: solid 0.06em; +} + +h3 { + border-top: 0em; + border-bottom: solid 0.06em; +} + +h4 { + border: 0em; + border-bottom: solid 0.06em; +} + +h5 { + border: 0em; +} +*/ + +.programlisting { + border: solid 1px; +} + +div.figure, +div.table, +div.informalfigure, +div.informaltable, +div.informalexample, +div.example { + border: 1px solid; +} + + + +.tip, +.warning, +.caution, +.note { + border: 1px solid; +} + +.tip table th, +.warning table th, +.caution table th, +.note table th { + border-bottom: 1px solid; +} + +.question td { + border-top: 1px solid black; +} + +.answer { +} + + +b.keycap, +.keycap { + border: 1px solid; +} + + +div.navheader, div.heading{ + border-bottom: 1px solid; +} + + +div.navfooter, div.footing{ + border-top: 1px solid; +} + + /********* / + / colors / +/ *********/ + +body { + color: #333; + background: white; +} + +a { + background: transparent; +} + +a:hover { + background-color: #dedede; +} + + +h1, +h2, +h3, +h4, +h5, +h6, +h7, +h8 { + background-color: transparent; +} + +hr { + border-color: #aaa; +} + + +.tip, .warning, .caution, .note { + border-color: #fff; +} + + +.tip table th, +.warning table th, +.caution table th, +.note table th { + border-bottom-color: #fff; +} + + +.warning { + background-color: #f0f0f2; +} + +.caution { + background-color: #f0f0f2; +} + +.tip { + background-color: #f0f0f2; +} + +.note { + background-color: #f0f0f2; +} + +.glossary dl dt, +.variablelist dl dt, +.variablelist dl dt span.term { + color: #044; +} + +div.figure, +div.table, +div.example, +div.informalfigure, +div.informaltable, +div.informalexample { + border-color: #aaa; +} + +pre.programlisting { + color: black; + background-color: #fff; + border-color: #aaa; + border-width: 2px; +} + +.guimenu, +.guilabel, +.guimenuitem { + background-color: #eee; +} + + +b.keycap, +.keycap { + background-color: #eee; + border-color: #999; +} + + +div.navheader { + border-color: black; +} + + +div.navfooter { + border-color: black; +} + + + /*********** / + / graphics / +/ ***********/ + +/* +body { + background-image: url("images/body_bg.jpg"); + background-attachment: fixed; +} + +.navheader, +.note, +.tip { + background-image: url("images/note_bg.jpg"); + background-attachment: fixed; +} + +.warning, +.caution { + background-image: url("images/warning_bg.jpg"); + background-attachment: fixed; +} + +.figure, +.informalfigure, +.example, +.informalexample, +.table, +.informaltable { + background-image: url("images/figure_bg.jpg"); + background-attachment: fixed; +} + +*/ +h1, +h2, +h3, +h4, +h5, +h6, +h7{ +} + +/* +Example of how to stick an image as part of the title. + +div.article .titlepage .title +{ + background-image: url("figures/white-on-black.png"); + background-position: center; + background-repeat: repeat-x; +} +*/ + +div.preface .titlepage .title, +div.colophon .title, +div.chapter .titlepage .title, +div.article .titlepage .title +{ +} + +div.section div.section .titlepage .title, +div.sect2 .titlepage .title { + background: none; +} + + +h1.title { + background-color: transparent; + background-repeat: no-repeat; + height: 256px; + text-indent: -9000px; + overflow:hidden; +} + +h2.subtitle { + background-color: transparent; + text-indent: -9000px; + overflow:hidden; + width: 0px; + display: none; +} + + /*************************************** / + / pippin.gimp.org specific alterations / +/ ***************************************/ + +/* +div.heading, div.navheader { + color: #777; + font-size: 80%; + padding: 0; + margin: 0; + text-align: left; + position: absolute; + top: 0px; + left: 0px; + width: 100%; + height: 50px; + background: url('/gfx/heading_bg.png') transparent; + background-repeat: repeat-x; + background-attachment: fixed; + border: none; +} + +div.heading a { + color: #444; +} + +div.footing, div.navfooter { + border: none; + color: #ddd; + font-size: 80%; + text-align:right; + + width: 100%; + padding-top: 10px; + position: absolute; + bottom: 0px; + left: 0px; + + background: url('/gfx/footing_bg.png') transparent; +} +*/ + + + + /****************** / + / nasty ie tweaks / +/ ******************/ + +/* +div.heading, div.navheader { + width:expression(document.body.clientWidth + "px"); +} + +div.footing, div.navfooter { + width:expression(document.body.clientWidth + "px"); + margin-left:expression("-5em"); +} +body { + padding:expression("4em 5em 0em 5em"); +} +*/ + + /**************************************** / + / mozilla vendor specific css extensions / +/ ****************************************/ +/* +div.navfooter, div.footing{ + -moz-opacity: 0.8em; +} + +div.figure, +div.table, +div.informalfigure, +div.informaltable, +div.informalexample, +div.example, +.tip, +.warning, +.caution, +.note { + -moz-border-radius: 0.5em; +} + +b.keycap, +.keycap { + -moz-border-radius: 0.3em; +} +*/ + +table tr td table tr td { + display: none; +} + + +hr { + display: none; +} + +table { + border: 0em; +} + + .photo { + float: right; + margin-left: 1.5em; + margin-bottom: 1.5em; + margin-top: 0em; + max-width: 17em; + border: 1px solid gray; + padding: 3px; + background: white; +} + .seperator { + padding-top: 2em; + clear: both; + } + + #validators { + margin-top: 5em; + text-align: right; + color: #777; + } + @media print { + body { + font-size: 8pt; + } + .noprint { + display: none; + } + } + + +.tip, +.note { + background: #f0f0f2; + color: #333; + padding: 20px; + margin: 20px; +} + +.tip h3, +.note h3 { + padding: 0em; + margin: 0em; + font-size: 2em; + font-weight: bold; + color: #333; +} + +.tip a, +.note a { + color: #333; + text-decoration: underline; +} + +.footnote { + font-size: small; + color: #333; +} + +/* Changes the announcement text */ +.tip h3, +.warning h3, +.caution h3, +.note h3 { + font-size:large; + color: #00557D; +} diff --git a/documentation/toaster-manual/toaster-manual.xml b/documentation/toaster-manual/toaster-manual.xml new file mode 100644 index 0000000000..f3cc8850bd --- /dev/null +++ b/documentation/toaster-manual/toaster-manual.xml @@ -0,0 +1,73 @@ +<!DOCTYPE book 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; ] > + +<book id='toaster-manual' lang='en' + xmlns:xi="http://www.w3.org/2003/XInclude" + xmlns="http://docbook.org/ns/docbook" + > + <bookinfo> + + <mediaobject> + <imageobject> + <imagedata fileref='figures/toaster-title.png' + format='SVG' + align='left' scalefit='1' width='100%'/> + </imageobject> + </mediaobject> + + <title> + Toaster User Manual + </title> + + <authorgroup> + <author> + <firstname>Scott</firstname> <surname>Rifenbark</surname> + <affiliation> + <orgname>Intel Corporation</orgname> + </affiliation> + <email>scott.m.rifenbark@intel.com</email> + </author> + </authorgroup> + + <revhistory> + <revision> + <revnumber>1.8</revnumber> + <date>April 2015</date> + <revremark>Released with the Yocto Project 1.8 Release.</revremark> + </revision> + </revhistory> + + <copyright> + <year>©RIGHT_YEAR;</year> + <holder>Linux Foundation</holder> + </copyright> + + <legalnotice> + <para> + Permission is granted to copy, distribute and/or modify this document under + the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England & Wales</ulink> as published by Creative Commons. + </para> + <note> + For the latest version of this manual associated with this + Yocto Project release, see the + <ulink url='&YOCTO_DOCS_TOAST_URL;'>Toaster User Manual</ulink> + from the Yocto Project website. + </note> + + </legalnotice> + + </bookinfo> + + <xi:include href="toaster-manual-intro.xml"/> + + <xi:include href="toaster-manual-start.xml"/> + + <xi:include href="toaster-manual-setup-and-use.xml"/> + + <xi:include href="toaster-manual-reference.xml"/> + +</book> +<!-- +vim: expandtab tw=80 ts=4 +--> diff --git a/documentation/tools/mega-manual.sed b/documentation/tools/mega-manual.sed index 47be450157..2bd5e616ba 100644 --- a/documentation/tools/mega-manual.sed +++ b/documentation/tools/mega-manual.sed @@ -2,30 +2,32 @@ # 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.7.1\/[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.7.1\/yocto-project-qs\/yocto-project-qs.html#/\"link\" href=\"#/g -s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.7.1\/poky-ref-manual\/poky-ref-manual.html#/\"link\" href=\"#/g +# 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) 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.7.1\/[a-z]*-[a-z]*\/[a-z]*-[a-z]*.html#/\"link\" href=\"#/g +# 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.7.1\/adt-manual\/adt-manual.html#/\"link\" href=\"#/g -s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.7.1\/bsp-guide\/bsp-guide.html#/\"link\" href=\"#/g -s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.7.1\/dev-manual\/dev-manual.html#/\"link\" href=\"#/g -s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.7.1\/kernel-dev\/kernel-dev.html#/\"link\" href=\"#/g -s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.7.1\/profile-manual\/profile-manual.html#/\"link\" href=\"#/g -s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.7.1\/ref-manual\/ref-manual.html#/\"link\" href=\"#/g -s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.7.1\/yocto-project-qs\/yocto-project-qs.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\/toaster-manual\/toaster-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.1\/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.1\/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.1\/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.1\/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.1\/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.1\/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.1\/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 +s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.8\/toaster-manual\/toaster-manual.html\" target=\"_top\">Toaster User Manual<\/a>/Toaster User Manual/g diff --git a/documentation/tools/update-documentation-conf b/documentation/tools/update-documentation-conf new file mode 100644 index 0000000000..3f8d280093 --- /dev/null +++ b/documentation/tools/update-documentation-conf @@ -0,0 +1,168 @@ +#!/usr/bin/env python + +# documentation.conf update script +# +# Author: Paul Eggleton <paul.eggleton@linux.intel.com> +# +# Copyright (C) 2015 Intel Corporation +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License version 2 as +# published by the Free Software Foundation. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License along +# with this program; if not, write to the Free Software Foundation, Inc., +# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. + + +import sys +import os +import argparse +import re +from lxml import etree +import logging + +def logger_create(name): + logger = logging.getLogger(name) + loggerhandler = logging.StreamHandler() + loggerhandler.setFormatter(logging.Formatter("%(levelname)s: %(message)s")) + logger.addHandler(loggerhandler) + logger.setLevel(logging.INFO) + return logger +logger = logger_create('docconfupdater') + +def main(): + parser = argparse.ArgumentParser(description="documentation.conf updater") + parser.add_argument('basepath', help='Path to OE-Core base directory') + parser.add_argument('-q', '--quiet', help='Print only warnings/errors', action='store_true') + + args = parser.parse_args() + + if args.quiet: + logger.setLevel(logging.WARN) + + if not os.path.isdir(args.basepath): + logger.error('Specified base path %s not found') + return 1 + + doc_conf = os.path.join(args.basepath, 'meta', 'conf', 'documentation.conf') + if not os.path.exists(doc_conf): + logger.error('Unable to find %s' % doc_conf) + return 1 + + allowed_flags = ['doc'] + flag_re = re.compile(r'\[(.+?)\]') + + infos = {} + tree = etree.parse('ref-manual/ref-variables.xml') + root = tree.getroot() + for glossary in root.findall('glossary'): + for glossdiv in glossary.findall('glossdiv'): + for glossentry in glossdiv.findall('glossentry'): + info = glossentry.find('info') + if info is not None: + infoline = ' '.join(info.text.split()) + infolinesplit = infoline.split('=', 1) + if len(infoline) < 2: + logger.warn('Invalid info line (no = character), ignoring: %s' % infoline) + continue + flags = flag_re.findall(infolinesplit[0]) + if not flags: + logger.warn('Invalid info line (no varflag), ignoring: %s' % infoline) + continue + for flag in flags: + if flag not in allowed_flags: + logger.warn('Invalid info line (varflag %s not in allowed list), ignoring: %s' % (flag, infoline)) + continue + infos[infolinesplit[0].rstrip()] = infolinesplit[1].lstrip() + + if not infos: + logger.error('ERROR: Unable to find any info tags in the glossary') + return 1 + + def sortkey(key): + # Underscores sort undesirably, so replace them + return key.split('[')[0].replace('_', '-') + + changed = False + lines = [] + invars = False + lastletter = None + added = [] + with open(doc_conf, 'r') as dcf: + for line in dcf: + if not invars: + if line.startswith('#') and 'DESCRIPTIONS FOR VARIABLES' in line: + invars = True + elif not line.startswith('#'): + linesplit = line.split('=', 1) + if len(linesplit) > 1: + key = linesplit[0].rstrip() + lastletter = key[0] + # Find anything in the dict that should come before the current key + for dkey in sorted(infos.keys()): + if sortkey(dkey) < sortkey(key): + lines.append('%s = %s\n' % (dkey, infos[dkey])) + added.append(dkey) + del infos[dkey] + changed = True + newvalue = infos.get(key, None) + if newvalue: + del infos[key] + if newvalue != linesplit[1].strip(): + lines.append('%s = %s\n' % (key, newvalue)) + changed = True + continue + elif key in added: + # We already added a new value for this key, so skip it + continue + elif lastletter: + # Ensure we write out anything anything left over for this letter + for dkey in sorted(infos.keys()): + if dkey[0] == lastletter: + lines.append('%s = %s\n' % (dkey, infos[dkey])) + del infos[dkey] + changed = True + elif dkey[0] > lastletter: + # List is sorted, so we're done + break + lastletter = None + lines.append(line) + + if not invars: + logger.error('ERROR: Unable to find variables section in documentation.conf') + return 1 + + if infos: + changed = True + # Write out anything left over + lines.append('\n\n') + for key in sorted(infos.keys()): + lines.append('%s = %s\n' % (key, infos[key])) + + if changed: + logger.info('Updating %s' % doc_conf) + with open(doc_conf, 'w') as dcf: + for line in lines: + dcf.write(line) + else: + logger.info('No changes required') + + return 0 + + +if __name__ == "__main__": + try: + ret = main() + except Exception: + ret = 1 + import traceback + traceback.print_exc(5) + sys.exit(ret) + + 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-eclipse-customization.xsl b/documentation/yocto-project-qs/yocto-project-qs-eclipse-customization.xsl index f8f8930f27..a022ec4d70 100644 --- a/documentation/yocto-project-qs/yocto-project-qs-eclipse-customization.xsl +++ b/documentation/yocto-project-qs/yocto-project-qs-eclipse-customization.xsl @@ -6,7 +6,7 @@ version="1.0"> <xsl:import - href="http://docbook.sourceforge.net/release/xsl/current/eclipse/eclipse3.xsl" /> + href="http://docbook.sourceforge.net/release/xsl/1.76.1/eclipse/eclipse3.xsl" /> <xsl:import href="yocto-project-qs-titlepage.xsl"/> <xsl:param name="chunker.output.indent" select="'yes'"/> diff --git a/documentation/yocto-project-qs/yocto-project-qs.xml b/documentation/yocto-project-qs/yocto-project-qs.xml index 7a083bc064..521c741e34 100644 --- a/documentation/yocto-project-qs/yocto-project-qs.xml +++ b/documentation/yocto-project-qs/yocto-project-qs.xml @@ -1,8 +1,8 @@ -<!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; ] > -<article id='intro'> +<article id='yocto-project-qs-intro'> <articleinfo> <title>Yocto Project Quick Start</title> @@ -99,12 +99,13 @@ <section id='yp-intro'> <title>Introducing the Yocto Project Development Environment</title> <para> - The Yocto Project through the OpenEmbedded build system provides an open source development - environment targeting the ARM, MIPS, PowerPC and x86 architectures for a variety of - platforms including x86-64 and emulated ones. - You can use components from the Yocto Project to design, develop, build, debug, simulate, - and test the complete software stack using Linux, the X Window System, GNOME Mobile-based - application frameworks, and Qt frameworks. + The Yocto Project through the OpenEmbedded build system provides an + open source development environment targeting the ARM, MIPS, PowerPC + and x86 architectures for a variety of platforms including x86-64 and + emulated ones. + You can use components from the Yocto Project to design, develop, + build, debug, simulate, and test the complete software stack using + Linux, the X Window System, GTK+ frameworks, and Qt frameworks. </para> <mediaobject> @@ -152,12 +153,15 @@ </para> <para> - Another important Yocto Project feature is the Sato reference User Interface. - This optional GNOME mobile-based UI, which is intended for devices with - restricted screen sizes, sits neatly on top of a device using the - GNOME Mobile Stack and provides a well-defined user experience. - Implemented in its own layer, it makes it clear to developers how they can implement - their own user interface on top of a Linux image created with the Yocto Project. + Another important Yocto Project feature is the Sato reference User + Interface. + This optional UI that is based on GTK+ is intended for devices with + restricted screen sizes. + The UI sits neatly on top of a device using the + GTK+ stack and provides a well-defined user experience. + Implemented in its own layer, it makes it clear to developers how they + can implement their own user interface on top of a Linux image created + with the Yocto Project. </para> </section> @@ -289,6 +293,20 @@ <literallayout class='monospaced'> $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL; libsdl1.2-dev xterm </literallayout> + <note> + If your build system has the + <filename>oss4-dev</filename> package installed, you + might experience QEMU build failures due to the package + installing its own custom + <filename>/usr/include/linux/soundcard.h</filename> on + the Debian system. + If you run into this situation, either of the following + solutions exist: + <literallayout class='monospaced'> + $ sudo apt-get build-dep qemu + $ sudo apt-get remove oss4-dev + </literallayout> + </note> </para> </section> @@ -359,6 +377,10 @@ Current and archived releases are available for download. Nightly and developmental builds are also maintained at <ulink url="&YOCTO_AB_NIGHTLY_URL;"></ulink>. + One final site you can visit for information on Yocto Project + releases is the + <ulink url='&YOCTO_WIKI_URL;/wiki/Releases'>Releases</ulink> + wiki. However, for this document a released version of Yocto Project is used. </para> @@ -369,22 +391,24 @@ <title>A Quick Test Run</title> <para> - Now that you have your system requirements in order, you can give the Yocto Project a try. + Now that you have your system requirements in order, you can give + the Yocto Project a try. This section presents some steps that let you do the following: - </para> - - <itemizedlist> - <listitem> - <para> + <itemizedlist> + <listitem><para> Build an image and run it in the QEMU emulator. - </para> - </listitem> - <listitem> - <para> + </para></listitem> + <listitem><para> Use a pre-built image and run it in the QEMU emulator. - </para> - </listitem> - </itemizedlist> + </para></listitem> + </itemizedlist> + <note> + This section does not provide detail, but rather provides minimal, + working commands and examples designed to just get you started. + For more details, see the appropriate manuals in the + <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project manual set</ulink>. + </note> + </para> <section id='building-image'> <title>Building an Image</title> @@ -463,8 +487,9 @@ a local repository named <filename>poky</filename> that is a clone of the upstream Yocto Project <filename>poky</filename> repository.</para></listitem> - <listitem><para>The third command checks out a local branch and - names it <filename>&DISTRO_NAME;</filename>. + <listitem><para>The third command checks out the current + Yocto Project release into a local branch whose name matches + the release (i.e. <filename>&DISTRO_NAME;</filename>). The local branch tracks the upstream branch of the same name. Creating your own branch based on the released branch ensures you are using the latest files for that release. @@ -509,15 +534,17 @@ </para> <para> - 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 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 - cores used. - Doing so can significantly shorten your build time. + Three other variables of interest are the + <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></ulink>, + <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink>, + and + <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_NUMBER_PARSE_THREADS'><filename>BB_NUMBER_PARSE_THREADS</filename></ulink> + variables. + By default, the OpenEmbedded build system sets these variables + based on the number of processor cores your build host uses. + Thus, you typically do not need to uncomment these variables in + your <filename>local.conf</filename> file to gain optimal build + times. </para> <para> @@ -531,39 +558,54 @@ section in the Yocto Project Reference Manual. </para> - <para> - Continue with the following command to build an OS image for the target, which is - <filename>core-image-sato</filename> in this example. - For information on the <filename>-k</filename> option use the - <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;#bitbake-user-manual-command'>BitBake Command</ulink>" - section in the BitBake User Manual. - <literallayout class='monospaced'> + <para> + Continue with the following command to build an OS image for the + target, which is <filename>core-image-sato</filename> in this + example. + For information on the <filename>-k</filename> option use the + <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;#bitbake-user-manual-command'>BitBake Command</ulink>" + section in the BitBake User Manual. + For information on other targets, see the + "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" + chapter in the Yocto Project Reference Manual. + <literallayout class='monospaced'> $ bitbake -k core-image-sato - </literallayout> - <note> - BitBake requires Python 2.6 or 2.7. For more information on - this requirement, see the - "<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 using the QEMU emulator: - <literallayout class='monospaced'> + </literallayout> + <note> + BitBake requires Python 2.7. For more information on + this requirement, see the + "<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 using the QEMU emulator: + <literallayout class='monospaced'> $ runqemu qemux86 - </literallayout> - <note> - <para> - Depending on the number of processors and cores, the amount - of RAM, the speed of your Internet connection and other - factors, the build process could take several hours the - first time you run it. - Subsequent builds run much faster since parts of the build - are cached. - </para> - </note> - </para> + </literallayout> + <note> + <para> + Depending on the number of processors and cores, the amount + of RAM, the speed of your Internet connection and other + factors, the build process could take several hours the + first time you run it. + Subsequent builds run much faster since parts of the build + are cached. + </para> + </note> + If you want to learn more about running QEMU, see the + "<ulink url="&YOCTO_DOCS_DEV_URL;#dev-manual-qemu">Using the Quick EMUlator (QEMU)</ulink>" + chapter in the Yocto Project Development Manual. + </para> + + <para> + For information on how to use a pre-built binary, continue reading + into the next section. + Otherwise, you might be interested in reading the early chapters + of the + <ulink url='&YOCTO_DOCS_DEV_URL;'>Yocto Project Development Manual</ulink>. + </para> </section> <section id='using-pre-built'> @@ -625,7 +667,7 @@ </para> <literallayout class='monospaced'> - poky-eglibc-<replaceable>host_system</replaceable>-<replaceable>image_type</replaceable>-<replaceable>arch</replaceable>-toolchain-<replaceable>release_version</replaceable>.sh + poky-glibc-<replaceable>host_system</replaceable>-<replaceable>image_type</replaceable>-<replaceable>arch</replaceable>-toolchain-<replaceable>release_version</replaceable>.sh Where: <replaceable>host_system</replaceable> is a string representing your development system: @@ -654,7 +696,7 @@ development host system and a i586-tuned target architecture based off the SDK for <filename>core-image-sato</filename>: <literallayout class='monospaced'> - poky-eglibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh + poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh </literallayout> </para> @@ -683,7 +725,7 @@ <para> <literallayout class='monospaced'> - $ ~/Downloads/poky-eglibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh + $ ~/Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh </literallayout> </para> @@ -819,6 +861,13 @@ </para> </section> </section> + + <para> + For more detailed information on using the Yocto Project for + image and application develop, the best place to continue reading is + in the + <ulink url='&YOCTO_DOCS_DEV_URL;'>Yocto Project Development Manual</ulink>. + </para> </section> <section id='super-user'> @@ -898,18 +947,10 @@ <filename>conf/local.conf</filename> configuration file in the Build Directory. You need to manually edit this file to specify the machine you - are building and to optimize your build time. - Here are the minimal changes to make: + are building: <literallayout class='monospaced'> - BB_NUMBER_THREADS = "8" - PARALLEL_MAKE = "-j 8" MACHINE ?= "beaglebone" </literallayout> - Briefly, set - <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></ulink> - and - <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink> to - twice your host processor's number of cores. </para> <para> |
