diff options
Diffstat (limited to 'import-layers/yocto-poky/documentation')
52 files changed, 10289 insertions, 5099 deletions
diff --git a/import-layers/yocto-poky/documentation/Makefile b/import-layers/yocto-poky/documentation/Makefile index 418d3ca8c..9077c8121 100644 --- a/import-layers/yocto-poky/documentation/Makefile +++ b/import-layers/yocto-poky/documentation/Makefile @@ -133,7 +133,7 @@ TARFILES = dev-style.css dev-manual.html \ 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/build-workspace-directory.png \ + figures/recipe-workflow.png \ figures/devtool-add-flow.png figures/devtool-modify-flow.png \ figures/devtool-upgrade-flow.png \ eclipse @@ -249,7 +249,8 @@ TARFILES = mega-manual.html mega-style.css figures/yocto-environment.png \ figures/compatible-layers.png figures/import-layer.png figures/new-project.png \ figures/sdk-environment.png figures/sdk-installed-standard-sdk-directory.png \ figures/sdk-devtool-add-flow.png figures/sdk-installed-extensible-sdk-directory.png \ - figures/sdk-devtool-modify-flow.png figures/sdk-eclipse-dev-flow.png + figures/sdk-devtool-modify-flow.png figures/sdk-eclipse-dev-flow.png \ + figures/sdk-devtool-upgrade-flow.png endif MANUALS = $(DOC)/$(DOC).html @@ -269,7 +270,8 @@ TARFILES = ref-manual.html ref-style.css figures/poky-title.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/building-an-image.png + figures/sdk-generation.png figures/building-an-image.png \ + figures/build-workspace-directory.png MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse FIGURES = figures STYLESHEET = $(DOC)/*.css @@ -282,6 +284,7 @@ TARFILES = sdk-manual.html sdk-style.css figures/sdk-title.png \ figures/sdk-environment.png figures/sdk-installed-standard-sdk-directory.png \ figures/sdk-installed-extensible-sdk-directory.png figures/sdk-devtool-add-flow.png \ figures/sdk-devtool-modify-flow.png figures/sdk-eclipse-dev-flow.png \ + figures/sdk-devtool-upgrade-flow.png \ eclipse MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse FIGURES = figures diff --git a/import-layers/yocto-poky/documentation/bsp-guide/bsp-guide.xml b/import-layers/yocto-poky/documentation/bsp-guide/bsp-guide.xml index c00b3458c..1bbdb70fe 100644 --- a/import-layers/yocto-poky/documentation/bsp-guide/bsp-guide.xml +++ b/import-layers/yocto-poky/documentation/bsp-guide/bsp-guide.xml @@ -108,6 +108,11 @@ <date>April 2016</date> <revremark>Released with the Yocto Project 2.1 Release.</revremark> </revision> + <revision> + <revnumber>2.2</revnumber> + <date>October 2016</date> + <revremark>Released with the Yocto Project 2.2 Release.</revremark> + </revision> </revhistory> <copyright> diff --git a/import-layers/yocto-poky/documentation/bsp-guide/bsp.xml b/import-layers/yocto-poky/documentation/bsp-guide/bsp.xml index b0562c7d4..4d0ace048 100644 --- a/import-layers/yocto-poky/documentation/bsp-guide/bsp.xml +++ b/import-layers/yocto-poky/documentation/bsp-guide/bsp.xml @@ -1467,20 +1467,19 @@ 5) MIPS (32-bit) 6) MIPS64 (64-bit) 3 - Would you like to use the default (4.1) kernel? (y/n) [default: y] + Would you like to use the default (4.8) kernel? (y/n) [default: 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-4.1.git... - Please choose a machine branch to base your new BSP branch on: [default: standard/base] + Getting branches from remote repo git://git.yoctoproject.org/linux-yocto-4.8.git... + Please choose a machine branch to base this BSP on: [default: standard/base] 1) standard/arm-versatile-926ejs 2) standard/base - 3) standard/beagleboard - 4) standard/beaglebone - 5) standard/edgerouter - 6) standard/fsl-mpc8315e-rdb - 7) standard/mti-malta32 - 8) standard/mti-malta64 - 9) standard/qemuarm64 - 10) standard/qemuppc + 3) standard/beaglebone + 4) standard/edgerouter + 5) standard/fsl-mpc8315e-rdb + 6) standard/mti-malta32 + 7) standard/mti-malta64 + 8) standard/qemuarm64 + 9) standard/qemuppc 1 Would you like SMP support? (y/n) [default: y] Does your BSP have a touchscreen? (y/n) [default: n] @@ -1495,7 +1494,7 @@ In the example, we use the ARM architecture. </para></listitem> <listitem><para>The script then prompts you for the kernel. - The default 4.4 kernel is acceptable. + The default 4.8 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> diff --git a/import-layers/yocto-poky/documentation/dev-manual/dev-manual-common-tasks.xml b/import-layers/yocto-poky/documentation/dev-manual/dev-manual-common-tasks.xml index f926f1d47..086d0bad9 100644 --- a/import-layers/yocto-poky/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/import-layers/yocto-poky/documentation/dev-manual/dev-manual-common-tasks.xml @@ -1254,27 +1254,57 @@ <para> You can always write a recipe from scratch. - However, two choices exist that can help you quickly get a + However, three 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 + <listitem><para> + <emphasis><filename>devtool add</filename>:</emphasis> + A command that assists in creating a recipe and + an environment conducive to development. + </para></listitem> + <listitem><para> + <emphasis><filename>recipetool create</filename>:</emphasis> + A command 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> + <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> + <section id='new-recipe-creating-the-base-recipe-using-devtool'> + <title>Creating the Base Recipe Using <filename>devtool add</filename></title> + + <para> + The <filename>devtool add</filename> command uses the same + logic for auto-creating the recipe as + <filename>recipetool create</filename>, which is listed + below. + Additionally, however, <filename>devtool add</filename> + sets up an environment that makes it easy for you to + patch the source and to make changes to the recipe as + is often necessary when adding a recipe to build a new + piece of software to be included in a build. + </para> + + <para> + You can find a complete description of the + <filename>devtool add</filename> command in the + "<link linkend='use-devtool-to-integrate-new-code'>Use <filename>devtool add</filename> to Add an Application</link>" + section. + </para> + </section> + <section id='new-recipe-creating-the-base-recipe-using-recipetool'> - <title>Creating the Base Recipe Using <filename>recipetool</filename></title> + <title>Creating the Base Recipe Using <filename>recipetool create</filename></title> <para> - <filename>recipetool</filename> automates creation of - a base recipe given a set of source code files. + <filename>recipetool create</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. @@ -1566,12 +1596,29 @@ or tabs after the slash character. </note> </para></listitem> - <listitem><para><emphasis>Using Variables: <filename>${...}</filename></emphasis> - - Use the <filename>${<replaceable>varname</replaceable>}</filename> syntax to + <listitem><para> + <emphasis>Using Variables: <filename>${...}</filename></emphasis> - + Use the <filename>${<replaceable>VARNAME</replaceable>}</filename> syntax to access the contents of a variable: <literallayout class='monospaced'> SRC_URI = "${SOURCEFORGE_MIRROR}/libpng/zlib-${PV}.tar.gz" </literallayout> + <note> + It is important to understand that the value of a + variable expressed in this form does not get + substituted automatically. + The expansion of these expressions happens + on-demand later (e.g. usually when a function that + makes reference to the variable executes). + This behavior ensures that the values are most + appropriate for the context in which they are + finally used. + On the rare occasion that you do need the variable + expression to be expanded immediately, you can use + the <filename>:=</filename> operator instead of + <filename>=</filename> when you make the + assignment, but this is not generally needed. + </note> </para></listitem> <listitem><para><emphasis>Quote All Assignments: <filename>"<replaceable>value</replaceable>"</filename></emphasis> - Use double quotes around the value in all variable @@ -1779,11 +1826,12 @@ </para> <para> - The per-recipe temporary work directory is constructed as follows and - depends on several factors: + The path to the per-recipe temporary work directory depends + on the context in which it is being built. + The quickest way to find this path is to have BitBake return it + by running the following: <literallayout class='monospaced'> - BASE_WORKDIR ?= "${TMPDIR}/work" - WORKDIR = "${BASE_WORKDIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}" + $ bitbake -e <replaceable>basename</replaceable> | grep ^WORKDIR= </literallayout> As an example, assume a Source Directory top-level folder named <filename>poky</filename>, a default Build Directory at @@ -1817,28 +1865,6 @@ "<ulink url='&YOCTO_DOCS_REF_URL;#closer-look'>A Closer Look at the Yocto Project Development Environment</ulink>" chapter of the Yocto Project Reference Manual. </para> - - <para> - You can also reference the following variables in the - Yocto Project Reference Manual's glossary for more information: - <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> <section id='new-recipe-fetching-code'> @@ -1959,7 +1985,7 @@ Here is an example: <literallayout class='monospaced'> SRC_URI = "${DEBIAN_MIRROR}/main/a/apmd/apmd_3.2.2.orig.tar.gz;name=tarball \ - ${DEBIAN_MIRROR}/main/a/apmd/apmd_${PV}.diff.gz;name=patch + ${DEBIAN_MIRROR}/main/a/apmd/apmd_${PV}.diff.gz;name=patch" SRC_URI[tarball.md5sum] = "b1e6309e8331e0f4e6efd311c2d97fa8" SRC_URI[tarball.sha256sum] = "7f7d9f60b7766b852881d40b8ff91d8e39fccb0d1d913102a5c75a2dbb52332d" @@ -2241,6 +2267,83 @@ </section> + <section id='new-dependencies'> + <title>Dependencies</title> + + <para> + Most software packages have a short list of other packages + that they require, which are called dependencies. + These dependencies fall into two main categories: build-time + dependencies, which are required when the software is built; + and runtime dependencies, which are required to be installed + on the target in order for the software to run. + </para> + + <para> + Within a recipe, you specify build-time dependencies using the + <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink> + variable. + Although nuances exist, items specified in + <filename>DEPENDS</filename> should be names of other recipes. + It is important that you specify all build-time dependencies + explicitly. + If you do not, due to the parallel nature of BitBake's + execution, you can end up with a race condition where the + dependency is present for one task of a recipe (e.g. + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-configure'><filename>do_configure</filename></ulink>) + and then gone when the next task runs (e.g. + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile</filename></ulink>). + </para> + + <para> + Another consideration is that configure scripts might + automatically check for optional dependencies and enable + corresponding functionality if those dependencies are found. + This behavior means that to ensure deterministic results and + thus avoid more race conditions, you need to either explicitly + specify these dependencies as well, or tell the configure + script explicitly to disable the functionality. + If you wish to make a recipe that is more generally useful + (e.g. publish the recipe in a layer for others to use), + instead of hard-disabling the functionality, you can use the + <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></ulink> + variable to allow functionality and the corresponding + dependencies to be enabled and disabled easily by other + users of the recipe. + </para> + + <para> + Similar to build-time dependencies, you specify runtime + dependencies through a variable - + <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>, + which is package-specific. + All variables that are package-specific need to have the name + of the package added to the end as an override. + Since the main package for a recipe has the same name as the + recipe, and the recipe's name can be found through the + <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename> + variable, then you specify the dependencies for the main + package by setting <filename>RDEPENDS_${PN}</filename>. + If the package were named <filename>${PN}-tools</filename>, + then you would set <filename>RDEPENDS_${PN}-tools</filename>, + and so forth. + </para> + + <para> + Some runtime dependencies will be set automatically at + packaging time. + These dependencies include any shared library dependencies + (i.e. if a package "example" contains "libexample" and + another package "mypackage" contains a binary that links to + "libexample" then the OpenEmbedded build system will + automatically add a runtime dependency to "mypackage" on + "example"). + See the + "<ulink url='&YOCTO_DOCS_REF_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>" + in the Yocto Project Reference Manual for further details. + </para> + </section> + <section id='new-recipe-configuring-the-recipe'> <title>Configuring the Recipe</title> @@ -2251,7 +2354,7 @@ configure script with some options, or by modifying a build configuration file. <note> - As of Yocto Project Release 7.1, some of the core recipes + As of Yocto Project Release 1.7, some of the core recipes that package binary configuration scripts now disable the scripts due to the scripts previously requiring error-prone path substitution. @@ -2297,6 +2400,8 @@ However, you might still want to make some adjustments. For example, you can set <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></ulink> + or + <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></ulink> to pass any needed configure options that are specific to the recipe.</para></listitem> <listitem><para><emphasis>CMake:</emphasis> @@ -2770,6 +2875,56 @@ </para> </section> + <section id='new-sharing-files-between-recipes'> + <title>Sharing Files Between Recipes</title> + + <para> + Recipes often need to use files provided by other recipes on + the build host. + For example, an application linking to a common library needs + access to the library itself and its associated headers. + The way this access is accomplished is by populating sysroot + with files. + One sysroot exists per "machine" for which the image is + being built. + In practical terms, this means a sysroot exists for the target + machine, and a sysroot exists for the build host. + <note> + You could find the term "staging" used within the Yocto + project regarding files populating sysroot. + The term "staging" was used for previous releases of + the Yocto Project. + </note> + </para> + + <para> + Recipes should never populate the sysroot directly (i.e. write + files into sysroot). + Instead, files should be installed into standard locations + during the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink> + task within the + <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename> + directory. + A subset of these files automatically populates the sysroot. + The reason for this limitation is that almost all files that + populate the sysroot are cataloged in manifests in order to + ensure the files can be removed later when a recipe is either + modified or removed. + Thus, the sysroot is able to remain free from stale files. + </para> + + <para> + For information on variables you can use to help control how + files sysroot is populated, see the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></ulink>, + <ulink url='&YOCTO_DOCS_REF_URL;#var-SYSROOT_DIRS_NATIVE'><filename>SYSROOT_DIRS_NATIVE</filename></ulink>, + and + <ulink url='&YOCTO_DOCS_REF_URL;#var-SYSROOT_DIRS_BLACKLIST'><filename>SYSROOT_DIRS_BLACKLIST</filename></ulink> + variables. + </para> + </section> + <section id='properly-versioning-pre-release-recipes'> <title>Properly Versioning Pre-Release Recipes</title> @@ -3011,8 +3166,10 @@ You do not need to add a <filename>do_compile</filename> step since by default BitBake starts the <filename>make</filename> command to compile the application. If you need additional <filename>make</filename> options, you should store them in the - <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OEMAKE'>EXTRA_OEMAKE</ulink></filename> - variable. + <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></ulink> + or + <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></ulink> + variables. BitBake passes these options into the GNU <filename>make</filename> invocation. Note that a <filename>do_install</filename> task is still required. Otherwise, BitBake runs an empty <filename>do_install</filename> task by default. @@ -3048,7 +3205,7 @@ PV = "1.5.1+git${SRCPV}" - S = "${WORKDIR}/git/" + S = "${WORKDIR}/git" EXTRA_OEMAKE = "'CC=${CC}' 'RANLIB=${RANLIB}' 'AR=${AR}' 'CFLAGS=${CFLAGS} -I${S}/include -DWITHOUT_XATTR' 'BUILDDIR=${S}'" @@ -3179,38 +3336,114 @@ <ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink> variables in the Yocto Project Reference Manual's variable glossary. + <note><title>Notes</title> + <itemizedlist> + <listitem><para> + Using + <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink> + is a good idea even for components distributed + in binary form, and is often necessary for + shared libraries. + For a shared library, listing the library + dependencies in + <filename>DEPENDS</filename> makes sure that + the libraries are available in the staging + sysroot when other recipes link against the + library, which might be necessary for + successful linking. + </para></listitem> + <listitem><para> + Using <filename>DEPENDS</filename> also + allows runtime dependencies between packages + to be added automatically. + See the + "<ulink url='&YOCTO_DOCS_REF_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>" + section in the Yocto Project Reference Manual + for more information. + </para></listitem> + </itemizedlist> + </note> </para> <para> - If you can't use the <filename>bin_package</filename> + If you cannot use the <filename>bin_package</filename> class, you need to be sure you are doing the following: <itemizedlist> - <listitem><para>Create a recipe where the + <listitem><para> + Create a recipe where the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-configure'><filename>do_configure</filename></ulink> + and + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile</filename></ulink> + tasks do nothing: + It is usually sufficient to just not define these + tasks in the recipe, because the default + implementations do nothing unless a Makefile is + found in + <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink><filename>}</filename>. + </para> + + <para>If + <filename>${S}</filename> might contain a Makefile, + or if you inherit some class that replaces <filename>do_configure</filename> and - <filename>do_compile</filename> tasks do nothing: + <filename>do_compile</filename> with custom + versions, then you can use the + <filename>[</filename><ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>noexec</filename></ulink><filename>]</filename> + flag to turn the tasks into no-ops, as follows: <literallayout class='monospaced'> do_configure[noexec] = "1" do_compile[noexec] = "1" </literallayout> - Alternatively, you can make these tasks an empty - function. + Unlike + <ulink url='&YOCTO_DOCS_BB_URL;#deleting-a-task'><filename>deleting the tasks</filename></ulink>, + using the flag preserves the dependency chain from + the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>do_fetch</filename></ulink>, <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-unpack'><filename>do_unpack</filename></ulink>, + and + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-patch'><filename>do_patch</filename></ulink> + tasks to the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink> + task. </para></listitem> <listitem><para>Make sure your <filename>do_install</filename> task installs the binaries appropriately. </para></listitem> <listitem><para>Ensure that you set up - <filename>FILES</filename> (usually - <filename>FILES_${PN}</filename>) to point to the - files you have installed, which of course depends - on where you have installed them and whether - those files are in different locations than the - defaults. + <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink> + (usually + <filename>FILES_${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>) + to point to the files you have installed, which of + course depends on where you have installed them + and whether those files are in different locations + than the defaults. </para></listitem> </itemizedlist> </para> </section> </section> + + <section id="following-recipe-style-guidelines"> + <title>Following Recipe Style Guidelines</title> + + <para> + When writing recipes, it is good to conform to existing + style guidelines. + The + <ulink url='http://www.openembedded.org/wiki/Styleguide'>OpenEmbedded Styleguide</ulink> + wiki page provides rough guidelines for preferred recipe style. + </para> + + <para> + It is common for existing recipes to deviate a bit from this + style. + However, aiming for at least a consistent style is a good idea. + Some practices, such as omitting spaces around + <filename>=</filename> operators in assignments or ordering + recipe components in an erratic way, are widely seen as poor + style. + </para> + </section> </section> <section id="platdev-newmachine"> @@ -3388,6 +3621,106 @@ </section> </section> + <section id='platdev-building-targets-with-multiple-configurations'> + <title>Building Targets with Multiple Configurations</title> + + <para> + Bitbake also has functionality that allows you to build + multiple targets at the same time, where each target uses + a different configuration. + </para> + + <para> + In order to accomplish this, you setup each of the configurations + you need to use in parallel by placing the configuration files in + your current build directory alongside the usual + <filename>local.conf</filename> file. + </para> + + <para> + Follow these guidelines to create an environment that supports + multiple configurations: + <itemizedlist> + <listitem><para> + <emphasis>Create Configuration Files</emphasis>: + You need to create a single configuration file for each + configuration for which you want to add support. + These files would contain lines such as the following: + <literallayout class='monospaced'> + MACHINE = "A" + </literallayout> + The files would contain any other variables that can + be set and built in the same directory. + <note> + You can change the + <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink> + to not conflict. + </note></para> + + <para> + Furthermore, the configuration file must be located in the + current build directory in a directory named + <filename>multiconfig</filename> under the build's + <filename>conf</filename> directory where + <filename>local.conf</filename> resides. + The reason for this restriction is because the + <filename>BBPATH</filename> variable is not constructed + until the layers are parsed. + Consequently, using the configuration file as a + pre-configuration file is not possible unless it is + located in the current working directory. + </para></listitem> + <listitem><para> + <emphasis>Add the BitBake Multi-Config Variable to you Local Configuration File</emphasis>: + Use the + <filename>BBMULTICONFIG</filename> + variable in your <filename>conf/local.conf</filename> + configuration file to specify each separate configuration. + For example, the following line tells BitBake it should load + <filename>conf/multiconfig/configA.conf</filename>, + <filename>conf/multiconfig/configB.conf</filename>, and + <filename>conf/multiconfig/configC.conf</filename>. + <literallayout class='monospaced'> + BBMULTICONFIG = "configA configB configC" + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Launch BitBake</emphasis>: + Use the following BitBake command form to launch the + build: + <literallayout class='monospaced'> + $ bitbake [multiconfig:<replaceable>multiconfigname</replaceable>:]<replaceable>target</replaceable> [[[multiconfig:<replaceable>multiconfigname</replaceable>:]<replaceable>target</replaceable>] ... ] + </literallayout> + Following is an example that supports building a minimal + image for configuration A alongside a standard + <filename>core-image-sato</filename>, which takes its + configuration from <filename>local.conf</filename>: + <literallayout class='monospaced'> + $ bitbake multiconfig:configA:core-image-minimal core-image-sato + </literallayout> + </para></listitem> + </itemizedlist> + </para> + + <para> + Support for multiple configurations in this current release of + the Yocto Project (&DISTRO_NAME; &DISTRO;) has some known issues: + <itemizedlist> + <listitem><para> + No inter-multi-configuration dependencies exist. + </para></listitem> + <listitem><para> + Shared State (sstate) optimizations do not exist. + Consequently, if the build uses the same object twice + in, for example, two different + <filename>TMPDIR</filename> directories, the build + will either load from an existing sstate cache at the + start or build the object twice. + </para></listitem> + </itemizedlist> + </para> + </section> + <section id="platdev-working-with-libraries"> <title>Working With Libraries</title> @@ -3726,6 +4059,236 @@ </section> </section> + <section id='enabling-gobject-introspection-support'> + <title>Enabling GObject Introspection Support</title> + + <para> + <ulink url='https://wiki.gnome.org/Projects/GObjectIntrospection'>GObject introspection</ulink> + is the standard mechanism for accessing GObject-based software + from runtime environments. + GObject is a feature of the GLib library that provides an object + framework for the GNOME desktop and related software. + GObject Introspection adds information to GObject that allows + objects created within it to be represented across different + programming languages. + If you want to construct GStreamer pipelines using Python, or + control UPnP infrastructure using Javascript and GUPnP, + GObject introspection is the only way to do it. + </para> + + <para> + This section describes the Yocto Project support for generating + and packaging GObject introspection data. + GObject introspection data is a description of the + API provided by libraries built on top of GLib framework, + and, in particular, that framework's GObject mechanism. + GObject Introspection Repository (GIR) files go to + <filename>-dev</filename> packages, + <filename>typelib</filename> files go to main packages as they + are packaged together with libraries that are introspected. + </para> + + <para> + The data is generated when building such a library, by linking + the library with a small executable binary that asks the library + to describe itself, and then executing the binary and + processing its output. + </para> + + <para> + Generating this data in a cross-compilation environment + is difficult because the library is produced for the target + architecture, but its code needs to be executed on the build host. + This problem is solved with the OpenEmbedded build system by + running the code through QEMU, which allows precisely that. + Unfortunately, QEMU does not always work perfectly as mentioned + in the xxx section. + </para> + + <section id='enabling-the-generation-of-introspection-data'> + <title>Enabling the Generation of Introspection Data</title> + + <para> + Enabling the generation of introspection data (GIR files) + in your library package involves the following: + <orderedlist> + <listitem><para> + Inherit the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-gobject-introspection'><filename>gobject-introspection</filename></ulink> + class. + </para></listitem> + <listitem><para> + Make sure introspection is not disabled anywhere in + the recipe or from anything the recipe includes. + Also, make sure that "gobject-introspection-data" is + not in + <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename></ulink> + and that "qemu-usermode" is not in + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename></ulink>. + If either of these conditions exist, nothing will + happen. + </para></listitem> + <listitem><para> + Try to build the recipe. + If you encounter build errors that look like + something is unable to find + <filename>.so</filename> libraries, check where these + libraries are located in the source tree and add + the following to the recipe: + <literallayout class='monospaced'> + GIR_EXTRA_LIBS_PATH = "${B}/<replaceable>something</replaceable>/.libs" + </literallayout> + <note> + See recipes in the <filename>oe-core</filename> + repository that use that + <filename>GIR_EXTRA_LIBS_PATH</filename> variable + as an example. + </note> + </para></listitem> + <listitem><para> + Look for any other errors, which probably mean that + introspection support in a package is not entirely + standard, and thus breaks down in a cross-compilation + environment. + For such cases, custom-made fixes are needed. + A good place to ask and receive help in these cases + is the + <ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Yocto Project mailing lists</ulink>. + </para></listitem> + </orderedlist> + <note> + Using a library that no longer builds against the latest + Yocto Project release and prints introspection related + errors is a good candidate for the previous procedure. + </note> + </para> + </section> + + <section id='disabling-the-generation-of-introspection-data'> + <title>Disabling the Generation of Introspection Data</title> + + <para> + You might find that you do not want to generate + introspection data. + Or, perhaps QEMU does not work on your build host and + target architecture combination. + If so, you can use either of the following methods to + disable GIR file generations: + <itemizedlist> + <listitem><para> + Add the following to your distro configuration: + <literallayout class='monospaced'> + DISTRO_FEATURES_BACKFILL_CONSIDERED = "gobject-introspection-data" + </literallayout> + Adding this statement disables generating + introspection data using QEMU but will still enable + building introspection tools and libraries + (i.e. building them does not require the use of QEMU). + </para></listitem> + <listitem><para> + Add the following to your machine configuration: + <literallayout class='monospaced'> + MACHINE_FEATURES_BACKFILL_CONSIDERED = "qemu-usermode" + </literallayout> + Adding this statement disables the use of QEMU + when building packages for your machine. + Currently, this feature is used only by introspection + recipes and has the same effect as the previously + described option. + <note> + Future releases of the Yocto Project might have + other features affected by this option. + </note> + </para></listitem> + </itemizedlist> + If you disable introspection data, you can still + obtain it through other means such as copying the data + from a suitable sysroot, or by generating it on the + target hardware. + The OpenEmbedded build system does not currently + provide specific support for these techniques. + </para> + </section> + + <section id='testing-that-introspection-works-in-an-image'> + <title>Testing that Introspection Works in an Image</title> + + <para> + Use the following procedure to test if generating + introspection data is working in an image: + <orderedlist> + <listitem><para> + Make sure that "gobject-introspection-data" is not in + <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename></ulink> + and that "qemu-usermode" is not in + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename></ulink>. + </para></listitem> + <listitem><para> + Build <filename>core-image-sato</filename>. + </para></listitem> + <listitem><para> + Launch a Terminal and then start Python in the + terminal. + </para></listitem> + <listitem><para> + Enter the following in the terminal: + <literallayout class='monospaced'> + >>> from gi.repository import GLib + >>> GLib.get_host_name() + </literallayout> + </para></listitem> + <listitem><para> + For something a little more advanced, enter the + following: + <literallayout class='monospaced'> + http://python-gtk-3-tutorial.readthedocs.org/en/latest/introduction.html + </literallayout> + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='known-issues'> + <title>Known Issues</title> + + <para> + The following know issues exist for + GObject Introspection Support: + <itemizedlist> + <listitem><para> + <filename>qemu-ppc64</filename> immediately crashes. + Consequently, you cannot build introspection data on + that architecture. + </para></listitem> + <listitem><para> + x32 is not supported by QEMU. + Consequently, introspection data is disabled. + </para></listitem> + <listitem><para> + musl causes transient GLib binaries to crash on + assertion failures. + Consequently, generating introspection data is + disabled. + </para></listitem> + <listitem><para> + Because QEMU is not able to run the binaries correctly, + introspection is disabled for some specific packages + under specific architectures (e.g. + <filename>gcr</filename>, + <filename>libsecret</filename>, and + <filename>webkit</filename>). + </para></listitem> + <listitem><para> + QEMU usermode might not work properly when running + 64-bit binaries under 32-bit host machines. + In particular, "qemumips64" is known to not work under + i686. + </para></listitem> + </itemizedlist> + </para> + </section> + </section> + <section id='dev-optionally-using-an-external-toolchain'> <title>Optionally Using an External Toolchain</title> @@ -3802,10 +4365,10 @@ it is based on is by definition incomplete. Its purpose is to allow the generation of customized images, and as such was designed to be completely extensible through a - plugin interface. + plug-in interface. See the - "<link linkend='openembedded-kickstart-plugins'>Plugins</link>" - section for information on these plugins. + "<link linkend='openembedded-kickstart-plugins'>Plug-ins</link>" + section for information on these plug-ins. </para> <para> @@ -4367,21 +4930,21 @@ </section> <section id='openembedded-kickstart-plugins'> - <title>Plugins</title> + <title>Plug-ins</title> <para> - Plugins allow <filename>wic</filename> functionality to + Plug-ins allow <filename>wic</filename> functionality to be extended and specialized by users. This section documents the plugin interface, which is - currently restricted to source plugins. + currently restricted to source plug ins. </para> <para> - Source plugins provide a mechanism to customize + Source plug ins provide a mechanism to customize various aspects of the image generation process in <filename>wic</filename>, mainly the contents of partitions. - The plugins provide a mechanism for mapping values + The plug ins provide a mechanism for mapping values specified in <filename>.wks</filename> files using the <filename>--source</filename> keyword to a particular plugin implementation that populates a @@ -7304,27 +7867,48 @@ <title>Build Considerations</title> <para> - This section describes build considerations that you need - to be aware of in order to provide support for runtime + This section describes build considerations of which you + need to be aware in order to provide support for runtime package management. </para> <para> - When BitBake generates packages it needs to know + When BitBake generates packages, it needs to know what format or formats to use. In your configuration, you use the <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink> - variable to specify the format. - <note> - You can choose to have more than one format but you must - provide at least one. - </note> + variable to specify the format: + <orderedlist> + <listitem><para> + Open the <filename>local.conf</filename> file + inside your + <link linkend='build-directory'>Build Directory</link> + (e.g. <filename>~/poky/build/conf/local.conf</filename>). + </para></listitem> + <listitem><para> + Select the desired package format as follows: + <literallayout class='monospaced'> + PACKAGE_CLASSES ?= “package_<replaceable>packageformat</replaceable>” + </literallayout> + where <replaceable>packageformat</replaceable> + can be "ipk", "rpm", and "deb", which are the + supported package formats. + <note> + Because the Yocto Project supports three + different package formats, you can set the + variable with more than one argument. + However, the OpenEmbedded build system only + uses the first argument when creating an image + or Software Development Kit (SDK). + </note> + </para></listitem> + </orderedlist> </para> <para> If you would like your image to start off with a basic - package database of the packages in your current build - as well as have the relevant tools available on the + package database containing the packages in your current + build as well as to have the relevant tools available on the target for runtime package management, you can include "package-management" in the <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink> @@ -7359,27 +7943,33 @@ <literallayout class='monospaced'> $ bitbake <replaceable>some-package</replaceable> package-index </literallayout> - This is because BitBake does not properly schedule the - <filename>package-index</filename> target fully after any - other target has completed. + The reason for this restriction is because BitBake does not + properly schedule the <filename>package-index</filename> + target fully after any other target has completed. Thus, be sure to run the package update step separately. </para> <para> - As described below in the - "<link linkend='runtime-package-management-target-ipk'>Using IPK</link>" - section, if you are using IPK as your package format, you - can make use of the - <filename>distro-feed-configs</filename> recipe provided - by <filename>meta-oe</filename> in order to configure your - target to use your IPK databases. + You can use the + <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_FEED_ARCHS'><filename>PACKAGE_FEED_ARCHS</filename></ulink>, + <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_FEED_BASE_PATHS'><filename>PACKAGE_FEED_BASE_PATHS</filename></ulink>, + and + <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_FEED_URIS'><filename>PACKAGE_FEED_URIS</filename></ulink> + variables to pre-configure target images to use a package + feed. + If you do not define these variables, then manual steps + as described in the subsequent sections are necessary to + configure the target. + You should set these variables before building the image + in order to produce a correctly configured image. </para> <para> When your build is complete, your packages reside in the - <filename>${TMPDIR}/deploy/<replaceable>package-format</replaceable></filename> + <filename>${TMPDIR}/deploy/<replaceable>packageformat</replaceable></filename> directory. - For example, if <filename>${TMPDIR}</filename> + For example, if + <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink><filename>}</filename> is <filename>tmp</filename> and your selected package type is IPK, then your IPK packages are available in <filename>tmp/deploy/ipk</filename>. @@ -7390,121 +7980,38 @@ <title>Host or Server Machine Setup</title> <para> - Typically, packages are served from a server using - HTTP. - However, other protocols are possible. - If you want to use HTTP, then setup and configure a - web server, such as Apache 2 or lighttpd, on the machine - serving the packages. + Although other protocols are possible, a server using HTTP + typically serves packages. + If you want to use HTTP, then set up and configure a + web server such as Apache 2, lighttpd, or + SimpleHTTPServer on the machine serving the packages. </para> <para> - As previously mentioned, the build machine can act as the - package server. - In the following sections that describe server machine - setups, the build machine is assumed to also be the server. + To keep things simple, this section describes how to set + up a SimpleHTTPServer web server to share package feeds + from the developer's machine. + Although this server might not be the best for a production + environment, the setup is simple and straight forward. + Should you want to use a different server more suited for + production (e.g. Apache 2, Lighttpd, or Nginx), take the + appropriate steps to do so. </para> - <section id='package-server-apache'> - <title>Serving Packages via Apache 2</title> - - <para> - This example assumes you are using the Apache 2 - server: - <orderedlist> - <listitem><para> - Add the directory to your Apache - configuration, which you can find at - <filename>/etc/httpd/conf/httpd.conf</filename>. - Use commands similar to these on the - development system. - These example commands assume a top-level - <link linkend='source-directory'>Source Directory</link> - named <filename>poky</filename> in your home - directory. - The example also assumes an RPM package type. - If you are using a different package type, such - as IPK, use "ipk" in the pathnames: - <literallayout class='monospaced'> - <VirtualHost *:80> - .... - Alias /rpm ~/poky/build/tmp/deploy/rpm - <Directory "~/poky/build/tmp/deploy/rpm"> - Options +Indexes - </Directory> - </VirtualHost> - </literallayout></para></listitem> - <listitem><para> - Reload the Apache configuration as described - in this step. - For all commands, be sure you have root - privileges. - </para> - - <para> - If your development system is using Fedora or - CentOS, use the following: - <literallayout class='monospaced'> - # service httpd reload - </literallayout> - For Ubuntu and Debian, use the following: - <literallayout class='monospaced'> - # /etc/init.d/apache2 reload - </literallayout> - For OpenSUSE, use the following: - <literallayout class='monospaced'> - # /etc/init.d/apache2 reload - </literallayout></para></listitem> - <listitem><para> - If you are using Security-Enhanced Linux - (SELinux), you need to label the files as - being accessible through Apache. - Use the following command from the development - host. - This example assumes RPM package types: - <literallayout class='monospaced'> - # chcon -R -h -t httpd_sys_content_t tmp/deploy/rpm - </literallayout></para></listitem> - </orderedlist> - </para> - </section> - - <section id='package-server-lighttpd'> - <title>Serving Packages via lighttpd</title> - - <para> - If you are using lighttpd, all you need - to do is to provide a link from your - <filename>${TMPDIR}/deploy/<replaceable>package-format</replaceable></filename> - directory to lighttpd's document-root. - You can determine the specifics of your lighttpd - installation by looking through its configuration file, - which is usually found at: - <filename>/etc/lighttpd/lighttpd.conf</filename>. - </para> - - <para> - For example, if you are using IPK, lighttpd's - document-root is set to - <filename>/var/www/lighttpd</filename>, and you had - packages for a target named "BOARD", - then you might create a link from your build location - to lighttpd's document-root as follows: - <literallayout class='monospaced'> - # ln -s $(PWD)/tmp/deploy/ipk /var/www/lighttpd/BOARD-dir - </literallayout> - </para> - - <para> - At this point, you need to start the lighttpd server. - The method used to start the server varies by - distribution. - However, one basic method that starts it by hand is: - <literallayout class='monospaced'> - # lighttpd -f /etc/lighttpd/lighttpd.conf - </literallayout> - </para> - </section> + <para> + From within the build directory where you have built an + image based on your packaging choice (i.e. the + <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink> + setting), simply start the server. + The following example assumes a build directory of + <filename>~/poky/build/tmp/deploy/rpm</filename> and a + <filename>PACKAGE_CLASSES</filename> setting of + "package_rpm": + <literallayout class='monospaced'> + $ cd ~/poky/build/tmp/deploy/rpm + $ python -m SimpleHTTPServer + </literallayout> + </para> </section> <section id='runtime-package-management-target'> @@ -7513,42 +8020,46 @@ <para> Setting up the target differs depending on the package management system. - This section provides information for RPM and IPK. + This section provides information for RPM, IPK, and DEB. </para> <section id='runtime-package-management-target-rpm'> <title>Using RPM</title> <para> - The application for performing runtime package - management of RPM packages on the target is called - <filename>smart</filename>. + The <filename>smart</filename> application performs + runtime package management of RPM packages. + You must perform an initial setup for + <filename>smart</filename> on the target machine + if the + <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_FEED_ARCHS'><filename>PACKAGE_FEED_ARCHS</filename></ulink>, + <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_FEED_BASE_PATHS'><filename>PACKAGE_FEED_BASE_PATHS</filename></ulink>, and + <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_FEED_URIS'><filename>PACKAGE_FEED_URIS</filename></ulink> + variables have not been set or the target image was + built before the variables were set. </para> <para> - On the target machine, you need to inform - <filename>smart</filename> of every package database - you want to use. - As an example, suppose your target device can use the - following three package databases from a server named - <filename>server.name</filename>: + As an example, assume the target is able to use the + following package databases: <filename>all</filename>, <filename>i586</filename>, - and <filename>qemux86</filename>. - Given this example, issue the following commands on the - target: + and <filename>qemux86</filename> from a server named + <filename>my.server</filename>. + You must inform <filename>smart</filename> of the + availability of these databases by issuing 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 i585 type=rpm-md baseurl=http://my.server/rpm/i586 + # smart channel --add qemux86 type=rpm-md baseurl=http://my.server/rpm/qemux86 + # smart channel --add all type=rpm-md baseurl=http://my.server/rpm/all </literallayout> - Also from the target machine, fetch the repository - information using this command: + From the target machine, fetch the repository: <literallayout class='monospaced'> # smart update </literallayout> - You can now use the <filename>smart query</filename> - and <filename>smart install</filename> commands to - find and install packages from the repositories. + After everything is set up, <filename>smart</filename> + is able to find, install, and upgrade packages from + the specified repository. </para> </section> @@ -7556,61 +8067,99 @@ <title>Using IPK</title> <para> - The application for performing runtime package - management of IPK packages on the target is called - <filename>opkg</filename>. + The <filename>opkg</filename> application performs + runtime package management of IPK packages. + You must perform an initial setup for + <filename>opkg</filename> on the target machine + if the + <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_FEED_ARCHS'><filename>PACKAGE_FEED_ARCHS</filename></ulink>, + <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_FEED_BASE_PATHS'><filename>PACKAGE_FEED_BASE_PATHS</filename></ulink>, and + <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_FEED_URIS'><filename>PACKAGE_FEED_URIS</filename></ulink> + variables have not been set or the target image was + built before the variables were set. + </para> + + <para> + The <filename>opkg</filename> application uses + configuration files to find available package + databases. + Thus, you need to create a configuration file inside + the <filename>/etc/opkg/</filename> direction, which + informs <filename>opkg</filename> of any repository + you want to use. </para> <para> - In order to inform <filename>opkg</filename> of the - package databases you want to use, simply create one - or more <filename>*.conf</filename> files in the - <filename>/etc/opkg</filename> directory on the target. - The <filename>opkg</filename> application uses them - to find its available package databases. - As an example, suppose you configured your HTTP server - on your machine named - <filename>www.mysite.com</filename> to serve files - from a <filename>BOARD-dir</filename> directory under - its document-root. - In this case, you might create a configuration - file on the target called - <filename>/etc/opkg/base-feeds.conf</filename> that - contains: + As an example, suppose you are serving packages from a + <filename>ipk/</filename> directory containing the + <filename>i586</filename>, + <filename>all</filename>, and + <filename>qemux86</filename> databases through an + HTTP server named <filename>my.server</filename>. + On the target, create a configuration file + (e.g. <filename>my_repo.conf</filename>) inside the + <filename>/etc/opkg/</filename> directory containing + the following: + <literallayout class='monospaced'> + src/gz all http://my.server/ipk/all + src/gz i586 http://my.server/ipk/i586 + src/gz qemux86 http://my.server/ipk/qemux86 + </literallayout> + Next, instruct <filename>opkg</filename> to fetch + the repository information: <literallayout class='monospaced'> - src/gz all http://www.mysite.com/BOARD-dir/all - src/gz armv7a http://www.mysite.com/BOARD-dir/armv7a - src/gz beaglebone http://www.mysite.com/BOARD-dir/beaglebone + # opkg update </literallayout> + The <filename>opkg</filename> application is now able + to find, install, and upgrade packages from the + specified repository. </para> + </section> + + <section id='runtime-package-management-target-deb'> + <title>Using DEB</title> <para> - As a way of making it easier to generate and make - these IPK configuration files available on your - target, simply define - <ulink url='&YOCTO_DOCS_REF_URL;#var-FEED_DEPLOYDIR_BASE_URI'><filename>FEED_DEPLOYDIR_BASE_URI</filename></ulink> - to point to your server and the location within the - document-root which contains the databases. - For example: if you are serving your packages over - HTTP, your server's IP address is 192.168.7.1, and - your databases are located in a directory called - <filename>BOARD-dir</filename> underneath your HTTP - server's document-root, you need to set - <filename>FEED_DEPLOYDIR_BASE_URI</filename> to - <filename>http://192.168.7.1/BOARD-dir</filename> and - a set of configuration files will be generated for you - in your target to work with this feed. + The <filename>apt</filename> application performs + runtime package management of DEB packages. + This application uses a source list file to find + available package databases. + You must perform an initial setup for + <filename>apt</filename> on the target machine + if the + <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_FEED_ARCHS'><filename>PACKAGE_FEED_ARCHS</filename></ulink>, + <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_FEED_BASE_PATHS'><filename>PACKAGE_FEED_BASE_PATHS</filename></ulink>, and + <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_FEED_URIS'><filename>PACKAGE_FEED_URIS</filename></ulink> + variables have not been set or the target image was + built before the variables were set. </para> <para> - On the target machine, fetch (or refresh) the - repository information using this command: + To inform <filename>apt</filename> of the repository + you want to use, you might create a list file (e.g. + <filename>my_repo.list</filename>) inside the + <filename>/etc/apt/sources.list.d/</filename> + directory. + As an example, suppose you are serving packages from a + <filename>deb/</filename> directory containing the + <filename>i586</filename>, + <filename>all</filename>, and + <filename>qemux86</filename> databases through an + HTTP server named <filename>my.server</filename>. + The list file should contain: <literallayout class='monospaced'> - # opkg update + deb http://my.server/deb/all ./ + deb http://my.server/deb/i586 ./ + deb http://my.server/deb/qemux86 ./ </literallayout> - You can now use the <filename>opkg list</filename> and - <filename>opkg install</filename> commands to find and - install packages from the repositories. + Next, instruct the <filename>apt</filename> + application to fetch the repository information: + <literallayout class='monospaced'> + # apt-get update + </literallayout> + After this step, <filename>apt</filename> is able + to find, install, and upgrade packages from the + specified repository. </para> </section> </section> @@ -8561,19 +9110,19 @@ within a separately started QEMU or any other virtual machine manager. </para></listitem> - <listitem><para><emphasis>"GummibootTarget":</emphasis> - Choose "GummibootTarget" if your hardware is + <listitem><para><emphasis>"Systemd-bootTarget":</emphasis> + Choose "Systemd-bootTarget" if your hardware is an EFI-based machine with - <filename>gummiboot</filename> as bootloader and + <filename>systemd-boot</filename> as bootloader and <filename>core-image-testmaster</filename> (or something similar) is installed. Also, your hardware under test must be in a DHCP-enabled network that gives it the same IP address for each reboot.</para> - <para>If you choose "GummibootTarget", there are + <para>If you choose "Systemd-bootTarget", there are additional requirements and considerations. See the - "<link linkend='selecting-gummiboottarget'>Selecting GummibootTarget</link>" + "<link linkend='selecting-systemd-boottarget'>Selecting Systemd-bootTarget</link>" section, which follows, for more information. </para></listitem> <listitem><para><emphasis>"BeagleBoneTarget":</emphasis> @@ -8619,12 +9168,12 @@ </para> </section> - <section id='selecting-gummiboottarget'> - <title>Selecting GummibootTarget</title> + <section id='selecting-systemd-boottarget'> + <title>Selecting Systemd-bootTarget</title> <para> If you did not set <filename>TEST_TARGET</filename> to - "GummibootTarget", then you do not need any information + "Systemd-bootTarget", then you do not need any information in this section. You can skip down to the "<link linkend='qemu-image-running-tests'>Running Tests</link>" @@ -8633,14 +9182,14 @@ <para> If you did set <filename>TEST_TARGET</filename> to - "GummibootTarget", you also need to perform a one-time + "Systemd-bootTarget", you also need to perform a one-time setup of your master image by doing the following: <orderedlist> <listitem><para><emphasis>Set <filename>EFI_PROVIDER</filename>:</emphasis> Be sure that <filename>EFI_PROVIDER</filename> is as follows: <literallayout class='monospaced'> - EFI_PROVIDER = "gummiboot" + EFI_PROVIDER = "systemd-boot" </literallayout> </para></listitem> <listitem><para><emphasis>Build the master image:</emphasis> @@ -8704,7 +9253,7 @@ <para> The final thing you need to do when setting - <filename>TEST_TARGET</filename> to "GummibootTarget" is + <filename>TEST_TARGET</filename> to "Systemd-bootTarget" is to set up the test image: <orderedlist> <listitem><para><emphasis>Set up your <filename>local.conf</filename> file:</emphasis> @@ -8713,7 +9262,7 @@ <literallayout class='monospaced'> IMAGE_FSTYPES += "tar.gz" INHERIT += "testimage" - TEST_TARGET = "GummibootTarget" + TEST_TARGET = "Systemd-bootTarget" TEST_TARGET_IP = "192.168.2.3" </literallayout> </para></listitem> @@ -8974,18 +9523,17 @@ in your <filename>local.conf</filename> file. Be sure to provide the IP address you need: <literallayout class='monospaced'> - TEST_EXPORT_ONLY = "1" - TEST_TARGET = "simpleremote" + INHERIT +="testexport" TEST_TARGET_IP = "192.168.7.2" TEST_SERVER_IP = "192.168.7.1" </literallayout> You can then export the tests with the following: <literallayout class='monospaced'> - $ bitbake core-image-sato -c testimage + $ bitbake core-image-sato -c testexport </literallayout> Exporting the tests places them in the <link linkend='build-directory'>Build Directory</link> in - <filename>tmp/testimage/core-image-sato</filename>, which + <filename>tmp/testexport/core-image-sato</filename>, which is controlled by the <filename>TEST_EXPORT_DIR</filename> variable. </para> @@ -8993,37 +9541,9 @@ <para> You can now run the tests outside of the build environment: <literallayout class='monospaced'> - $ cd tmp/testimage/core-image-sato + $ cd tmp/testexport/core-image-sato $ ./runexported.py testdata.json </literallayout> - <note> - This "export" feature does not deploy or boot the target - image. - Your target (be it a Qemu or hardware one) - has to already be up and running when you call - <filename>runexported.py</filename> - </note> - </para> - - <para> - The exported data (i.e. <filename>testdata.json</filename>) - contains paths to the Build Directory. - Thus, the contents of the directory can be moved - to another machine as long as you update some paths in the - JSON. - Usually, you only care about the - <filename>${DEPLOY_DIR}/rpm</filename> directory - (assuming the RPM and Smart tests are enabled). - Consequently, running the tests on other machine - means that you have to move the contents and call - <filename>runexported.py</filename> with - "--deploy-dir <replaceable>path</replaceable>" as - follows: - <literallayout class='monospaced'> - ./runexported.py --deploy-dir /new/path/on/this/machine testdata.json - </literallayout> - <filename>runexported.py</filename> accepts other arguments - as well as described using <filename>--help</filename>. </para> </section> @@ -9138,7 +9658,7 @@ The target controller object used to deploy and start an image on a particular target (e.g. QemuTarget, SimpleRemote, and - GummibootTarget). + Systemd-bootTarget). Tests usually use the following: <itemizedlist> <listitem><para><emphasis><filename>ip</filename>:</emphasis> @@ -9198,6 +9718,78 @@ </para> </section> </section> + + <section id='installing-packages-in-the-dut-without-the-package-manager'> + <title>Installing Packages in the DUT Without the Package Manager</title> + + <para> + When a test requires a package built by BitBake, it is possible + to install that package. + Installing the package does not require a package manager be + installed in the device under test (DUT). + It does, however, require an SSH connection and the target must + be using the <filename>sshcontrol</filename> class. + <note> + This method uses <filename>scp</filename> to copy files + from the host to the target, which causes permissions and + special attributes to be lost. + </note> + </para> + + <para> + A JSON file is used to define the packages needed by a test. + This file must be in the same path as the file used to define + the tests. + Furthermore, the filename must map directly to the test + module name with a <filename>.json</filename> extension. + </para> + + <para> + The JSON file must include an object with the test name as + keys of an object or an array. + This object (or array of objects) uses the following data: + <itemizedlist> + <listitem><para>"pkg" - A mandatory string that is the + name of the package to be installed. + </para></listitem> + <listitem><para>"rm" - An optional boolean, which defaults + to "false", that specifies to remove the package after + the test. + </para></listitem> + <listitem><para>"extract" - An optional boolean, which + defaults to "false", that specifies if the package must + be extracted from the package format. + When set to "true", the package is not automatically + installed into the DUT. + </para></listitem> + </itemizedlist> + </para> + + <para> + Following is an example JSON file that handles test "foo" + installing package "bar" and test "foobar" installing + packages "foo" and "bar". + Once the test is complete, the packages are removed from the + DUT. + <literallayout class='monospaced'> + { + "foo": { + "pkg": "bar" + }, + "foobar": [ + { + "pkg": "foo", + "rm": true + }, + { + "pkg": "bar", + "rm": true + } + ] + } + </literallayout> + </para> + </section> </section> <section id="platdev-gdb-remotedebug"> @@ -9244,15 +9836,6 @@ as all the heavy debugging is done by the host GDB. Offloading these processes gives the Gdbserver running on the target a chance to remain small and fast. - <note> - By default, source files are part of the - <filename>*-dbg</filename> packages in order to enable GDB - to show source lines in its output. - You can save further space on the target by setting the - <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_DEBUG_SPLIT_STYLE'><filename>PACKAGE_DEBUG_SPLIT_STYLE</filename></ulink> - variable to "debug-without-src" so that these packages do not - include the source files. - </note> </para> <para> @@ -9276,10 +9859,200 @@ </para> <para> - The remainder of this section describes the steps you need to take - to debug using the GNU project debugger. + The following steps show you how to debug using the GNU project + debugger. + <orderedlist> + <listitem><para> + <emphasis>Configure your build system to construct the + companion debug filesystem:</emphasis></para> + + <para>In your <filename>local.conf</filename> file, set + the following: + <literallayout class='monospaced'> + IMAGE_GEN_DEBUGFS = "1" + IMAGE_FSTYPES_DEBUGFS = "tar.bz2" + </literallayout> + These options cause the OpenEmbedded build system + to generate a special companion filesystem fragment, + which contains the matching source and debug symbols to + your deployable filesystem. + The build system does this by looking at what is in the + deployed filesystem, and pulling the corresponding + <filename>-dbg</filename> packages.</para> + + <para>The companion debug filesystem is not a complete + filesystem, but only contains the debug fragments. + This filesystem must be combined with the full filesystem + for debugging. + Subsequent steps in this procedure show how to combine + the partial filesystem with the full filesystem. + </para></listitem> + <listitem><para> + <emphasis>Configure the system to include Gdbserver in + the target filesystem:</emphasis></para> + + <para>Make the following addition in either your + <filename>local.conf</filename> file or in an image + recipe: + <literallayout class='monospaced'> + IMAGE_INSTALL_append = “ gdbserver" + </literallayout> + The change makes sure the <filename>gdbserver</filename> + package is included. + </para></listitem> + <listitem><para> + <emphasis>Build the environment:</emphasis></para> + + <para>Use the following command to construct the image and + the companion Debug Filesystem: + <literallayout class='monospaced'> + $ bitbake <replaceable>image</replaceable> + </literallayout> + Build the cross GDB component and make it available + for debugging. + Build the SDK that matches the image. + Building the SDK is best for a production build + that can be used later for debugging, especially + during long term maintenance: + <literallayout class='monospaced'> + $ bitbake -c populate_sdk <replaceable>image</replaceable> + </literallayout></para> + + <para>Alternatively, you can build the minimal + toolchain components that match the target. + Doing so creates a smaller than typical SDK and only + contains a minimal set of components with which to + build simple test applications, as well as run the + debugger: + <literallayout class='monospaced'> + $ bitbake meta-toolchain + </literallayout></para> + + <para>A final method is to build Gdb itself within + the build system: + <literallayout class='monospaced'> + $ bitbake gdb-cross-<replaceable>architecture</replaceable> + </literallayout> + Doing so produces a temporary copy of + <filename>cross-gdb</filename> you can use for + debugging during development. + While this is the quickest approach, the two previous + methods in this step are better when considering + long-term maintenance strategies. + <note> + If you run + <filename>bitbake gdb-cross</filename>, the + OpenEmbedded build system suggests the actual + image (e.g. <filename>gdb-cross-i586</filename>). + The suggestion is usually the actual name you want + to use. + </note> + </para></listitem> + <listitem><para> + <emphasis>Set up the</emphasis> <filename>debugfs</filename></para> + + <para>Run the following commands to set up the + <filename>debugfs</filename>: + <literallayout class='monospaced'> + $ mkdir debugfs + $ cd debugfs + $ tar xvfj <replaceable>build-dir</replaceable>/tmp-glibc/deploy/images/<replaceable>machine</replaceable>/<replaceable>image</replaceable>.rootfs.tar.bz2 + $ tar xvfj <replaceable>build-dir</replaceable>/tmp-glibc/deploy/images/<replaceable>machine</replaceable>/<replaceable>image</replaceable>-dbg.rootfs.tar.bz2 + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Set up GDB</emphasis></para> + + <para>Install the SDK (if you built one) and then + source the correct environment file. + Sourcing the environment file puts the SDK in your + <filename>PATH</filename> environment variable.</para> + + <para>If you are using the build system, Gdb is + located in + <replaceable>build-dir</replaceable>/tmp/sysroots/<replaceable>host</replaceable>/usr/bin/<replaceable>architecture</replaceable>/<replaceable>architecture</replaceable>-gdb + </para></listitem> + <listitem><para> + <emphasis>Boot the target:</emphasis></para> + + <para>For information on how to run QEMU, see the + <ulink url='http://wiki.qemu.org/Documentation/GettingStartedDevelopers'>QEMU Documentation</ulink>. + <note> + Be sure to verify that your host can access the + target via TCP. + </note> + </para></listitem> + <listitem><para> + <emphasis>Debug a program:</emphasis></para> + + <para>Debugging a program involves running Gdbserver + on the target and then running Gdb on the host. + The example in this step debugs + <filename>gzip</filename>: + <literallayout class='monospaced'> + root@qemux86:~# gdbserver localhost:1234 /bin/gzip —help + </literallayout> + For additional Gdbserver options, see the + <ulink url='https://www.gnu.org/software/gdb/documentation/'>Gdb Server Documentation</ulink>. + </para> + + <para>After running Gdbserver on the target, you need + to run Gdb on the host and configure it and connect to + the target. + Use these commands: + <literallayout class='monospaced'> + $ cd <replaceable>directory-holding-the-debugfs-directory</replaceable> + $ <replaceable>arch</replaceable>-gdb + + (gdb) set sysroot debugfs + (gdb) set substitute-path /usr/src/debug debugfs/usr/src/debug + (gdb) target remote <replaceable>IP-of-target</replaceable>:1234 + </literallayout> + At this point, everything should automatically load + (i.e. matching binaries, symbols and headers). + <note> + The Gdb <filename>set</filename> commands in the + previous example can be placed into the users + <filename>~/.gdbinit</filename> file. + Upon starting, Gdb automatically runs whatever + commands are in that file. + </note> + </para></listitem> + <listitem><para> + <emphasis>Deploying without a full image + rebuild:</emphasis></para> + + <para>In many cases, during development you want a + quick method to deploy a new binary to the target and + debug it, without waiting for a full image build. + </para> + + <para>One approach to solving this situation is to + just build the component you want to debug. + Once you have built the component, copy the + executable directly to both the target and the + host <filename>debugfs</filename>.</para> + + <para>If the binary is processed through the debug + splitting in OpenEmbedded, you should also + copy the debug items (i.e. <filename>.debug</filename> + contents and corresponding + <filename>/usr/src/debug</filename> files) + from the work directory. + Here is an example: + <literallayout class='monospaced'> + $ bitbake bash + $ bitbake -c devshell bash + $ cd .. + $ scp packages-split/bash/bin/bash <replaceable>target</replaceable>:/bin/bash + $ cp -a packages-split/bash-dbg/* <replaceable>path</replaceable>/debugfs + </literallayout> + </para></listitem> + </orderedlist> </para> + </section> +<!-- <section id='platdev-gdb-remotedebug-setup'> <title>Set Up the Cross-Development Debugging Environment</title> @@ -9453,6 +10226,69 @@ </para> </section> </section> +--> + + <section id='debugging-with-the-gnu-project-debugger-gdb-on-the-target'> + <title>Debugging with the GNU Project Debugger (GDB) on the Target</title> + + <para> + The previous section addressed using GDB remotely for debugging + purposes, which is the most usual case due to the inherent + hardware limitations on many embedded devices. + However, debugging in the target hardware itself is also possible + with more powerful devices. + This section describes what you need to do in order to support + using GDB to debug on the target hardware. + </para> + + <para> + To support this kind of debugging, you need do the following: + <itemizedlist> + <listitem><para> + Ensure that GDB is on the target. + You can do this by adding "gdb" to + <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>: + <literallayout class='monospaced'> + IMAGE_INSTALL_append = " gdb" + </literallayout> + Alternatively, you can add "tools-debug" to + <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>: + <literallayout class='monospaced'> + IMAGE_FEATURES_append = " tools-debug" + </literallayout> + </para></listitem> + <listitem><para> + Ensure that debug symbols are present. + You can make sure these symbols are present by installing + <filename>-dbg</filename>: + <literallayout class='monospaced'> + IMAGE_INSTALL_append = " <replaceable>packagename</replaceable>-dbg" + </literallayout> + Alternatively, you can do the following to include all the + debug symbols: + <literallayout class='monospaced'> + IMAGE_FEATURES_append = " dbg-pkgs" + </literallayout> + </para></listitem> + </itemizedlist> + <note> + To improve the debug information accuracy, you can reduce the + level of optimization used by the compiler. + For example, when adding the following line to your + <filename>local.conf</filename> file, you will reduce + optimization from + <ulink url='&YOCTO_DOCS_REF_URL;#var-FULL_OPTIMIZATION'><filename>FULL_OPTIMIZATION</filename></ulink> + of "-O2" to + <ulink url='&YOCTO_DOCS_REF_URL;#var-DEBUG_OPTIMIZATION'><filename>DEBUG_OPTIMIZATION</filename></ulink> + of "-O -fno-omit-frame-pointer": + <literallayout class='monospaced'> + DEBUG_BUILD = "1" + </literallayout> + Consider that this will reduce the application's performance + and is recommended only for debugging purposes. + </note> + </para> + </section> <section id='debugging-parallel-make-races'> <title>Debugging Parallel Make Races</title> @@ -9736,265 +10572,6 @@ </section> </section> -<!-- - <section id="platdev-oprofile"> - <title>Profiling with OProfile</title> - - <para> - <ulink url="http://oprofile.sourceforge.net/">OProfile</ulink> is a - statistical profiler well suited for finding performance - bottlenecks in both user-space software and in the kernel. - This profiler provides answers to questions like "Which functions does my application spend - the most time in when doing X?" - Because the OpenEmbedded build system is well integrated with OProfile, it makes profiling - applications on target hardware straight forward. - <note> - For more information on how to set up and run OProfile, see the - "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-oprofile'>oprofile</ulink>" - section in the Yocto Project Profiling and Tracing Manual. - </note> - </para> - - <para> - To use OProfile, you need an image that has OProfile installed. - The easiest way to do this is with "tools-profile" in the - <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'>IMAGE_FEATURES</ulink></filename> variable. - You also need debugging symbols to be available on the system where the analysis - takes place. - You can gain access to the symbols by using "dbg-pkgs" in the - <filename>IMAGE_FEATURES</filename> variable or by - installing the appropriate debug (<filename>-dbg</filename>) - packages. - </para> - - <para> - For successful call graph analysis, the binaries must preserve the frame - pointer register and should also be compiled with the - <filename>-fno-omit-framepointer</filename> flag. - You can achieve this by setting the - <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</ulink></filename> - variable with the following options: - <literallayout class='monospaced'> - -fexpensive-optimizations - -fno-omit-framepointer - -frename-registers - -O2 - </literallayout> - You can also achieve it by setting the - <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DEBUG_BUILD'>DEBUG_BUILD</ulink></filename> - variable to "1" in the <filename>local.conf</filename> configuration file. - If you use the <filename>DEBUG_BUILD</filename> variable, - you also add extra debugging information that can make the debug - packages large. - </para> - - <section id="platdev-oprofile-target"> - <title>Profiling on the Target</title> - - <para> - Using OProfile, you can perform all the profiling work on the target device. - A simple OProfile session might look like the following: - </para> - - <para> - <literallayout class='monospaced'> - # opcontrol ‐‐reset - # opcontrol ‐‐start ‐‐separate=lib ‐‐no-vmlinux -c 5 - . - . - [do whatever is being profiled] - . - . - # opcontrol ‐‐stop - $ opreport -cl - </literallayout> - </para> - - <para> - In this example, the <filename>reset</filename> command clears any previously profiled data. - The next command starts OProfile. - The options used when starting the profiler separate dynamic library data - within applications, disable kernel profiling, and enable callgraphing up to - five levels deep. - <note> - To profile the kernel, you would specify the - <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> - </para> - - <para> - After you perform your profiling tasks, the next command stops the profiler. - After that, you can view results with the <filename>opreport</filename> command with options - to see the separate library symbols and callgraph information. - </para> - - <para> - Callgraphing logs information about time spent in functions and about a function's - calling function (parent) and called functions (children). - The higher the callgraphing depth, the more accurate the results. - However, higher depths also increase the logging overhead. - Consequently, you should take care when setting the callgraphing depth. - <note> - On ARM, binaries need to have the frame pointer enabled for callgraphing to work. - To accomplish this use the <filename>-fno-omit-framepointer</filename> option - with <filename>gcc</filename>. - </note> - </para> - - <para> - For more information on using OProfile, see the OProfile - online documentation at - <ulink url="http://oprofile.sourceforge.net/docs/"/>. - </para> - </section> - - <section id="platdev-oprofile-oprofileui"> - <title>Using OProfileUI</title> - - <para> - A graphical user interface for OProfile is also available. - You can download and build this interface from the Yocto Project at - <ulink url="&YOCTO_GIT_URL;/cgit.cgi/oprofileui/"></ulink>. - If the "tools-profile" image feature is selected, all necessary binaries - are installed onto the target device for OProfileUI interaction. - For a list of image features that ship with the Yocto Project, - see the - "<ulink url='&YOCTO_DOCS_REF_URL;#ref-features-image'>Image Features</ulink>" - section in the Yocto Project Reference Manual. - </para> - - <para> - Even though the source directory usually includes all needed patches on the target device, you - might find you need other OProfile patches for recent OProfileUI features. - If so, see the <ulink url='&YOCTO_GIT_URL;/cgit.cgi/oprofileui/tree/README'> - OProfileUI README</ulink> for the most recent information. - </para> - - <section id="platdev-oprofile-oprofileui-online"> - <title>Online Mode</title> - - <para> - Using OProfile in online mode assumes a working network connection with the target - hardware. - 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 - option. - </note> - </para> - - <para> - The client program is called <filename>oprofile-viewer</filename> and its UI is relatively - straight forward. - You access key functionality through the buttons on the toolbar, which - are duplicated in the menus. - Here are the buttons: - <itemizedlist> - <listitem><para><emphasis>Connect:</emphasis> Connects to the remote host. - You can also supply the IP address or hostname.</para></listitem> - <listitem><para><emphasis>Disconnect:</emphasis> Disconnects from the target. - </para></listitem> - <listitem><para><emphasis>Start:</emphasis> Starts profiling on the device. - </para></listitem> - <listitem><para><emphasis>Stop:</emphasis> Stops profiling on the device and - downloads the data to the local host. - Stopping the profiler generates the profile and displays it in the viewer. - </para></listitem> - <listitem><para><emphasis>Download:</emphasis> Downloads the data from the - target and generates the profile, which appears in the viewer.</para></listitem> - <listitem><para><emphasis>Reset:</emphasis> Resets the sample data on the device. - Resetting the data removes sample information collected from previous - sampling runs. - Be sure you reset the data if you do not want to include old sample information. - </para></listitem> - <listitem><para><emphasis>Save:</emphasis> Saves the data downloaded from the - target to another directory for later examination.</para></listitem> - <listitem><para><emphasis>Open:</emphasis> Loads previously saved data. - </para></listitem> - </itemizedlist> - </para> - - <para> - The client downloads the complete profile archive from - the target to the host for processing. - This archive is a directory that contains the sample data, the object files, - and the debug information for the object files. - The archive is then converted using the <filename>oparchconv</filename> script, which is - included in this distribution. - The script uses <filename>opimport</filename> to convert the archive from - the target to something that can be processed on the host. - </para> - - <para> - Downloaded archives reside in the - <link linkend='build-directory'>Build Directory</link> in - <filename>tmp</filename> and are cleared up when they are no longer in use. - </para> - - <para> - If you wish to perform kernel profiling, you need to be sure - a <filename>vmlinux</filename> file that matches the running kernel is available. - In the source directory, that file is usually located in - <filename>/boot/vmlinux-<replaceable>kernelversion</replaceable></filename>, where - <filename><replaceable>kernelversion</replaceable></filename> is the version of the kernel. - The OpenEmbedded build system generates separate <filename>vmlinux</filename> - packages for each kernel it builds. - Thus, it should just be a question of making sure a matching package is - installed (e.g. <filename>opkg install kernel-vmlinux</filename>). - The files are automatically installed into development and profiling images - alongside OProfile. - A configuration option exists within the OProfileUI settings page that you can use to - enter the location of the <filename>vmlinux</filename> file. - </para> - - <para> - Waiting for debug symbols to transfer from the device can be slow, and it - is not always necessary to actually have them on the device for OProfile use. - All that is needed is a copy of the filesystem with the debug symbols present - on the viewer system. - The "<link linkend='platdev-gdb-remotedebug-launch-gdb'>Launch GDB on the Host Computer</link>" - section covers how to create such a directory within - the source directory and how to use the OProfileUI Settings - Dialog to specify the location. - If you specify the directory, it will be used when the file checksums - match those on the system you are profiling. - </para> - </section> - - <section id="platdev-oprofile-oprofileui-offline"> - <title>Offline Mode</title> - - <para> - 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 - . - . - [do whatever is being profiled] - . - . - # opcontrol ‐‐stop - # oparchive -o my_archive - </literallayout> - </para> - - <para> - In the above example, <filename>my_archive</filename> is the name of the - archive directory where you would like the profile archive to be kept. - After the directory is created, you can copy it to another host and load it - using <filename>oprofile-viewer</filename> open functionality. - If necessary, the archive is converted. - </para> - </section> - </section> - </section> ---> - <section id='maintaining-open-source-license-compliance-during-your-products-lifecycle'> <title>Maintaining Open Source License Compliance During Your Product's Lifecycle</title> @@ -10113,12 +10690,31 @@ tarballs for licenses that require the release of source. Let us assume you are only concerned with GPL code as - identified with the following: + identified by running the following script: <literallayout class='monospaced'> - $ cd poky/build/tmp/deploy/sources - $ mkdir ~/gpl_source_release - $ for dir in */*GPL*; do cp -r $dir ~/gpl_source_release; done - </literallayout> + # Script to archive a subset of packages matching specific license(s) + # Source and license files are copied into sub folders of package folder + # Must be run from build folder + #!/bin/bash + src_release_dir="source-release" + mkdir -p $src_release_dir + for a in tmp/deploy/sources/*; do + for d in $a/*; do + # Get package name from path + p=`basename $d` + p=${p%-*} + p=${p%-*} + # Only archive GPL packages (update *GPL* regex for your license check) + numfiles=`ls tmp/deploy/licenses/$p/*GPL* 2> /dev/null | wc -l` + if [ $numfiles -gt 1 ]; then + echo Archiving $p + mkdir -p $src_release_dir/$p/source + cp $d/* $src_release_dir/$p/source 2> /dev/null + mkdir -p $src_release_dir/$p/license + cp tmp/deploy/licenses/$p/* $src_release_dir/$p/license 2> /dev/null + fi + done + done </literallayout> At this point, you could create a tarball from the <filename>gpl_source_release</filename> directory and provide that to the end user. diff --git a/import-layers/yocto-poky/documentation/dev-manual/dev-manual-model.xml b/import-layers/yocto-poky/documentation/dev-manual/dev-manual-model.xml index ff44a3f68..1008e1169 100644 --- a/import-layers/yocto-poky/documentation/dev-manual/dev-manual-model.xml +++ b/import-layers/yocto-poky/documentation/dev-manual/dev-manual-model.xml @@ -646,16 +646,20 @@ <para> The remainder of this section presents these workflows. + See the + "<ulink url='&YOCTO_DOCS_REF_URL;#ref-devtool-reference'><filename>devtool</filename> Quick Reference</ulink>" + in the Yocto Project Reference Manual for a + <filename>devtool</filename> quick reference. </para> <section id='use-devtool-to-integrate-new-code'> - <title>Use <filename>devtool add</filename> to Integrate New Code</title> + <title>Use <filename>devtool add</filename> to Add an Application</title> <para> The <filename>devtool add</filename> command generates a new recipe based on existing source code. This command takes advantage of the - <link linkend='devtool-the-workspace-layer-structure'>workspace</link> + <ulink url='&YOCTO_DOCS_DEV_URL;#devtool-the-workspace-layer-structure'>workspace</ulink> layer that many <filename>devtool</filename> commands use. The command is flexible enough to allow you to extract source @@ -721,7 +725,8 @@ and needs to be extracted to some local area - this time outside of the default workspace. - As always, if required <filename>devtool</filename> creates + If required, <filename>devtool</filename> + always creates a Git repository locally during the extraction. Furthermore, the first positional argument <replaceable>srctree</replaceable> in this case @@ -788,10 +793,6 @@ <para>If you need to take the build output and eventually move it to the target hardware, you would use <filename>devtool build</filename>: - <note> - You could use <filename>bitbake</filename> to build - the recipe as well. - </note> <literallayout class='monospaced'> $ devtool build <replaceable>recipe</replaceable> </literallayout></para> @@ -831,49 +832,44 @@ However, <filename>devtool</filename> does not provide a specific command that allows you to do this. </para></listitem> - <listitem><para><emphasis>Optionally Update the Recipe With Patch Files</emphasis>: - Once you are satisfied with the recipe, if you have made - any changes to the source tree that you want to have - applied by the recipe, you need to generate patches - from those changes. - You do this before moving the recipe - to its final layer and cleaning up the workspace area - <filename>devtool</filename> uses. - This optional step is especially relevant if you are - using or adding third-party software.</para> - <para>To convert commits created using Git to patch files, - use the <filename>devtool update-recipe</filename> command. + <listitem><para> + <emphasis>Finish Your Work With the Recipe</emphasis>: + The <filename>devtool finish</filename> command creates + any patches corresponding to commits in the local + Git repository, moves the new recipe to a more permanent + layer, and then resets the recipe so that the recipe is + built normally rather than from the workspace. + <literallayout class='monospaced'> + $ devtool finish <replaceable>recipe layer</replaceable> + </literallayout> <note> Any changes you want to turn into patches must be committed to the Git repository in the source tree. + </note></para> + + <para>As mentioned, the <filename>devtool finish</filename> + command moves the final recipe to its permanent layer. + </para> + + <para>As a final process of the + <filename>devtool finish</filename> command, the state + of the standard layers and the upstream source is + restored so that you can build the recipe from those + areas rather than the workspace. + <note> + You can use the <filename>devtool reset</filename> + command to put things back should you decide you + do not want to proceed with your work. + If you do use this command, realize that the source + tree is preserved. </note> - <literallayout class='monospaced'> - $ devtool update-recipe <replaceable>recipe</replaceable> - </literallayout> - </para></listitem> - <listitem><para><emphasis>Move the Recipe to its Permanent Layer</emphasis>: - Before cleaning up the workspace, you need to move the - final recipe to its permanent layer. - You must do this before using the - <filename>devtool reset</filename> command if you want to - retain the recipe. - </para></listitem> - <listitem><para><emphasis>Reset the Recipe</emphasis>: - As a final step, you can restore the state such that - standard layers and the upstream source is used to build - the recipe rather than data in the workspace. - To reset the recipe, use the <filename>devtool reset</filename> - command: - <literallayout class='monospaced'> - $ devtool reset <replaceable>recipe</replaceable> - </literallayout> </para></listitem> </orderedlist> </para> </section> <section id='devtool-use-devtool-modify-to-enable-work-on-code-associated-with-an-existing-recipe'> - <title>Use <filename>devtool modify</filename> to Enable Work on Code Associated with an Existing Recipe</title> + <title>Use <filename>devtool modify</filename> to Modify the Source of an Existing Component</title> <para> The <filename>devtool modify</filename> command prepares the @@ -1028,17 +1024,12 @@ <listitem><para><emphasis>Build the Recipe</emphasis>: Once you have updated the source files, you can build the recipe. - You can either use <filename>devtool build</filename> or - <filename>bitbake</filename>. - Either method produces build output that is stored - in - <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>. </para></listitem> <listitem><para><emphasis>Deploy the Build Output</emphasis>: When you use the <filename>devtool build</filename> - command or <filename>bitbake</filename> to build out your - recipe, you probably want to see if the resulting build - output works as expected on target hardware. + command to build out your recipe, you probably want to see + if the resulting build output works as expected on target + hardware. <note> This step assumes you have a previously built image that is already either running in QEMU or @@ -1062,42 +1053,43 @@ However, <filename>devtool</filename> does not provide a specific command that allows you to do this. </para></listitem> - <listitem><para><emphasis>Optionally Create Patch Files for Your Changes</emphasis>: - After you have debugged your changes, you can - use <filename>devtool update-recipe</filename> to - generate patch files for all the commits you have - made. - <note> - Patch files are generated only for changes - you have committed. - </note> + <listitem><para> + <emphasis>Finish Your Work With the Recipe</emphasis>: + The <filename>devtool finish</filename> command creates + any patches corresponding to commits in the local + Git repository, updates the recipe to point to them + (or creates a <filename>.bbappend</filename> file to do + so, depending on the specified destination layer), and + then resets the recipe so that the recipe is built normally + rather than from the workspace. <literallayout class='monospaced'> - $ devtool update-recipe <replaceable>recipe</replaceable> + $ devtool finish <replaceable>recipe layer</replaceable> </literallayout> - By default, the - <filename>devtool update-recipe</filename> command - creates the patch files in a folder named the same - as the recipe beneath the folder in which the recipe - resides, and updates the recipe's - <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> - statement to point to the generated patch files. <note> - You can use the - "--append <replaceable>LAYERDIR</replaceable>" - option to cause the command to create append files - in a specific layer rather than the default - recipe layer. + Any changes you want to turn into patches must be + committed to the Git repository in the source tree. + </note></para> + + <para>Because there is no need to move the recipe, + <filename>devtool finish</filename> either updates the + original recipe in the original layer or the command + creates a <filename>.bbappend</filename> in a different + layer as provided by <replaceable>layer</replaceable>. + </para> + + <para>As a final process of the + <filename>devtool finish</filename> command, the state + of the standard layers and the upstream source is + restored so that you can build the recipe from those + areas rather than the workspace. + <note> + You can use the <filename>devtool reset</filename> + command to put things back should you decide you + do not want to proceed with your work. + If you do use this command, realize that the source + tree is preserved. </note> </para></listitem> - <listitem><para><emphasis>Restore the Workspace</emphasis>: - The <filename>devtool reset</filename> restores the - state so that standard layers and upstream sources are - used to build the recipe rather than what is in the - workspace. - <literallayout class='monospaced'> - $ devtool reset <replaceable>recipe</replaceable> - </literallayout> - </para></listitem> </orderedlist> </para> </section> @@ -1229,633 +1221,42 @@ However, <filename>devtool</filename> does not provide a specific command that allows you to do this. </para></listitem> - <listitem><para><emphasis>Optionally Create Patch Files for Your Changes</emphasis>: - After you have debugged your changes, you can - use <filename>devtool update-recipe</filename> to - generate patch files for all the commits you have - made. - <note> - Patch files are generated only for changes - you have committed. - </note> + <listitem><para> + <emphasis>Finish Your Work With the Recipe</emphasis>: + The <filename>devtool finish</filename> command creates + any patches corresponding to commits in the local + Git repository, moves the new recipe to a more permanent + layer, and then resets the recipe so that the recipe is + built normally rather than from the workspace. + If you specify a destination layer that is the same as + the original source, then the old version of the + recipe and associated files will be removed prior to + adding the new version. <literallayout class='monospaced'> - $ devtool update-recipe <replaceable>recipe</replaceable> - </literallayout> - By default, the - <filename>devtool update-recipe</filename> command - creates the patch files in a folder named the same - as the recipe beneath the folder in which the recipe - resides, and updates the recipe's - <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> - statement to point to the generated patch files. - </para></listitem> - <listitem><para><emphasis>Move the Recipe to its Permanent Layer</emphasis>: - Before cleaning up the workspace, you need to move the - final recipe to its permanent layer. - You can either overwrite the original recipe or you can - overlay the upgraded recipe into a separate layer. - You must do this before using the - <filename>devtool reset</filename> command if you want to - retain the upgraded recipe. - </para></listitem> - <listitem><para><emphasis>Restore the Workspace</emphasis>: - The <filename>devtool reset</filename> restores the - state so that standard layers and upstream sources are - used to build the recipe rather than what is in the - workspace. - <literallayout class='monospaced'> - $ devtool reset <replaceable>recipe</replaceable> + $ devtool finish <replaceable>recipe layer</replaceable> </literallayout> + <note> + Any changes you want to turn into patches must be + committed to the Git repository in the source tree. + </note></para> + <para>As a final process of the + <filename>devtool finish</filename> command, the state + of the standard layers and the upstream source is + restored so that you can build the recipe from those + areas rather than the workspace. + <note> + You can use the <filename>devtool reset</filename> + command to put things back should you decide you + do not want to proceed with your work. + If you do use this command, realize that the source + tree is preserved. + </note> </para></listitem> </orderedlist> </para> </section> </section> - <section id='devtool-quick-reference'> - <title><filename>devtool</filename> Quick Reference</title> - - <para> - <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> and its 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'> - usage: devtool [--basepath BASEPATH] [--bbpath BBPATH] [-d] [-q] - [--color COLOR] [-h] - <subcommand> ... - - OpenEmbedded development tool - - optional arguments: - --basepath BASEPATH Base directory of SDK / build directory - --bbpath BBPATH Explicitly specify the BBPATH, rather than getting it - from the metadata - -d, --debug Enable debug output - -q, --quiet Print only errors - --color COLOR Colorize output (where COLOR is auto, always, never) - -h, --help show this help message and exit - - subcommands: - Beginning work on a recipe: - add Add a new recipe - modify Modify the source for an existing recipe - upgrade Upgrade an existing recipe - Getting information: - status Show workspace status - search Search available recipes - Working on a recipe in the workspace: - build Build a recipe - edit-recipe Edit a recipe file in your workspace - configure-help Get help on configure script options - update-recipe Apply changes from external source tree to recipe - reset Remove a recipe from your workspace - Testing changes on target: - deploy-target Deploy recipe output files to live target machine - undeploy-target Undeploy recipe output files in live target machine - build-image Build image including workspace recipe packages - Advanced: - create-workspace Set up workspace in an alternative location - extract Extract the source for an existing recipe - sync Synchronize the source tree for an existing recipe - Use devtool <subcommand> --help to get help on a specific command - </literallayout> - </para> - - <para> - As directed in the general help output, you can get more - syntax on a specific command by providing the command - name and using <filename>--help</filename>: - <literallayout class='monospaced'> - $ devtool add --help - usage: devtool add [-h] [--same-dir | --no-same-dir] [--fetch URI] - [--version VERSION] [--no-git] [--binary] [--also-native] - [--src-subdir SUBDIR] - [recipename] [srctree] [fetchuri] - - Adds a new recipe to the workspace to build a specified source tree. Can - optionally fetch a remote URI and unpack it to create the source tree. - - positional arguments: - recipename Name for new recipe to add (just name - no version, - path or extension). If not specified, will attempt to - auto-detect it. - srctree Path to external source tree. If not specified, a - subdirectory of - /home/scottrif/poky/build/workspace/sources will be - used. - fetchuri Fetch the specified URI and extract it to create the - source tree - - optional arguments: - -h, --help show this help message and exit - --same-dir, -s Build in same directory as source - --no-same-dir Force build in a separate build directory - --fetch URI, -f URI Fetch the specified URI and extract it to create the - source tree (deprecated - pass as positional argument - instead) - --version VERSION, -V VERSION - Version to use within recipe (PV) - --no-git, -g If fetching source, do not set up source tree as a git - repository - --binary, -b Treat the source tree as something that should be - installed verbatim (no compilation, same directory - structure). Useful with binary packages e.g. RPMs. - --also-native Also add native variant (i.e. support building recipe - for the build host as well as the target machine) - --src-subdir SUBDIR Specify subdirectory within source tree to use - </literallayout> - </para> - </section> - - <section id='devtool-the-workspace-layer-structure'> - <title>The Workspace Layer Structure</title> - - <para> - <filename>devtool</filename> uses a "Workspace" layer - in which to accomplish builds. - This layer is not specific to any single - <filename>devtool</filename> command but is rather a common - working area used across the tool. - </para> - - <para> - The following figure shows the workspace structure: - </para> - - <para> - <imagedata fileref="figures/build-workspace-directory.png" - width="6in" depth="5in" align="left" scale="70" /> - </para> - - <para> - <literallayout class='monospaced'> - attic - A directory created if devtool believes it preserve - anything when you run "devtool reset". For example, if you - run "devtool add", make changes to the recipe, and then - run "devtool reset", devtool takes notice that the file has - been changed and moves it into the attic should you still - want the recipe. - - README - Provides information on what is in workspace layer and how to - manage it. - - .devtool_md5 - A checksum file used by devtool. - - appends - A directory that contains *.bbappend files, which point to - external source. - - conf - A configuration directory that contains the layer.conf file. - - recipes - A directory containing recipes. This directory contains a - folder for each directory added whose name matches that of the - added recipe. devtool places the <replaceable>recipe</replaceable>.bb file - within that sub-directory. - - sources - A directory containing a working copy of the source files used - when building the recipe. This is the default directory used - as the location of the source tree when you do not provide a - source tree path. This directory contains a folder for each - set of source files matched to a corresponding recipe. - </literallayout> - </para> - </section> - - <section id='devtool-adding-a-new-recipe-to-the-workspace'> - <title>Adding a New Recipe to the Workspace Layer</title> - - <para> - Use the <filename>devtool add</filename> command to add a new recipe - to the workspace layer. - The recipe you add should not exist - - <filename>devtool</filename> creates it for you. - The source files the recipe uses should exist in an external - area. - </para> - - <para> - The following example creates and adds a new recipe named - <filename>jackson</filename> to a workspace layer the tool creates. - The source code built by the recipes resides in - <filename>/home/scottrif/sources/jackson</filename>: - <literallayout class='monospaced'> - $ devtool add jackson /home/scottrif/sources/jackson - </literallayout> - </para> - - <para> - If you add a recipe and the workspace layer does not exist, - the command creates the layer and populates it as - described in - "<link linkend='devtool-the-workspace-layer-structure'>The Workspace Layer Structure</link>" - section. - </para> - - <para> - Running <filename>devtool add</filename> when the - workspace layer exists causes the tool to add the recipe, - append files, and source files into the existing workspace layer. - The <filename>.bbappend</filename> file is created to point - to the external source tree. - </para> - </section> - - <section id='devtool-extracting-the-source-for-an-existing-recipe'> - <title>Extracting the Source for an Existing Recipe</title> - - <para> - Use the <filename>devtool extract</filename> command to - extract the source for an existing recipe. - When you use this command, you must supply the root name - of the recipe (i.e. no version, paths, or extensions), and - you must supply the directory to which you want the source - extracted. - </para> - - <para> - Additional command options let you control the name of a - development branch into which you can checkout the source - and whether or not to keep a temporary directory, which is - useful for debugging. - </para> - </section> - - <section id='devtool-synchronizing-a-recipes-extracted-source-tree'> - <title>Synchronizing a Recipe's Extracted Source Tree</title> - - <para> - Use the <filename>devtool sync</filename> command to - synchronize a previously extracted source tree for an - existing recipe. - When you use this command, you must supply the root name - of the recipe (i.e. no version, paths, or extensions), and - you must supply the directory to which you want the source - extracted. - </para> - - <para> - Additional command options let you control the name of a - development branch into which you can checkout the source - and whether or not to keep a temporary directory, which is - useful for debugging. - </para> - </section> - - <section id='devtool-modifying-a-recipe'> - <title>Modifying an Existing Recipe</title> - - <para> - Use the <filename>devtool modify</filename> command to begin - modifying the source of an existing recipe. - This command is very similar to the - <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 <replaceable>recipe</replaceable> - </literallayout> - Using the above command form, <filename>devtool</filename> uses - the existing recipe's - <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> - statement to locate the upstream source, extracts the source - into the default sources location in the workspace. - The default development branch used is "devtool". - </para> - </section> - - <section id='devtool-edit-an-existing-recipe'> - <title>Edit an Existing Recipe</title> - - <para> - Use the <filename>devtool edit-recipe</filename> command - to run the default editor, which is identified using the - <filename>EDITOR</filename> variable, on the specified recipe. - </para> - - <para> - When you use the <filename>devtool edit-recipe</filename> - command, you must supply the root name of the recipe - (i.e. no version, paths, or extensions). - Also, the recipe file itself must reside in the workspace - as a result of the <filename>devtool add</filename> or - <filename>devtool upgrade</filename> commands. - However, you can override that requirement by using the - "-a" or "--any-recipe" option. - Using either of these options allows you to edit any recipe - regardless of its location. - </para> - </section> - - <section id='devtool-updating-a-recipe'> - <title>Updating a Recipe</title> - - <para> - Use the <filename>devtool update-recipe</filename> command to - update your recipe with patches that reflect changes you make - to the source files. - For example, if you know you are going to work on some - code, you could first use the - <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. - </para> - - <para> - When you are satisfied with the results and you have committed - your changes to the Git repository, you can then - run the <filename>devtool update-recipe</filename> to create the - patches and update the recipe: - <literallayout class='monospaced'> - $ devtool update-recipe <replaceable>recipe</replaceable> - </literallayout> - If you run the <filename>devtool update-recipe</filename> - without committing your changes, the command ignores the - changes. - </para> - - <para> - Often, you might want to apply customizations made to your - software in your own layer rather than apply them to the - original recipe. - If so, you can use the - <filename>-a</filename> or <filename>--append</filename> - option with the <filename>devtool update-recipe</filename> - command. - These options allow you to specify the layer into which to - write an append file: - <literallayout class='monospaced'> - $ devtool update-recipe <replaceable>recipe</replaceable> -a <replaceable>base-layer-directory</replaceable> - </literallayout> - The <filename>*.bbappend</filename> file is created at the - appropriate path within the specified layer directory, which - may or may not be in your <filename>bblayers.conf</filename> - file. - If an append file already exists, the command updates it - appropriately. - </para> - </section> - - <section id='devtool-upgrading-a-recipe'> - <title>Upgrading a Recipe</title> - - <para> - Use the <filename>devtool upgrade</filename> command - to upgrade an existing recipe to a new upstream version. - The command puts the upgraded recipe file into the - workspace along with any associated files, and extracts - the source tree to a specified location should patches - need rebased or added to as a result of the upgrade. - </para> - - <para> - When you use the <filename>devtool upgrade</filename> command, - you must supply the root name of the recipe (i.e. no version, - paths, or extensions), and you must supply the directory - to which you want the source extracted. - Additional command options let you control things such as - the version number to which you want to upgrade (i.e. the - <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>), - the source revision to which you want to upgrade (i.e. the - <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>, - whether or not to apply patches, and so forth. - </para> - </section> - - <section id='devtool-resetting-a-recipe'> - <title>Resetting a Recipe</title> - - <para> - Use the <filename>devtool reset</filename> command to remove a - recipe and its configuration (e.g. the corresponding - <filename>.bbappend</filename> file) from the workspace layer. - Realize that this command deletes the recipe and the - append file. - The command does not physically move them for you. - Consequently, you must be sure to physically relocate your - updated recipe and the append file outside of the workspace - layer before running the <filename>devtool reset</filename> - command. - </para> - - <para> - If the <filename>devtool reset</filename> command detects that - the recipe or the append files have been modified, the - command preserves the modified files in a separate "attic" - subdirectory under the workspace layer. - </para> - - <para> - Here is an example that resets the workspace directory that - contains the <filename>mtr</filename> recipe: - <literallayout class='monospaced'> - $ devtool reset mtr - NOTE: Cleaning sysroot for recipe mtr... - NOTE: Leaving source tree /home/scottrif/poky/build/workspace/sources/mtr as-is; if you no - longer need it then please delete it manually - $ - </literallayout> - </para> - </section> - - <section id='devtool-building-your-recipe'> - <title>Building Your Recipe</title> - - <para> - Use the <filename>devtool build</filename> command to cause the - OpenEmbedded build system to build your recipe. - The <filename>devtool build</filename> command is equivalent to - <filename>bitbake -c populate_sysroot</filename>. - </para> - - <para> - When you use the <filename>devtool build</filename> command, - you must supply the root name of the recipe (i.e. no version, - paths, or extensions). - You can use either the "-s" or the "--disable-parallel-make" - option to disable parallel makes during the build. - Here is an example: - <literallayout class='monospaced'> - $ devtool build <replaceable>recipe</replaceable> - </literallayout> - </para> - </section> - - <section id='devtool-building-your-image'> - <title>Building Your Image</title> - - <para> - Use the <filename>devtool build-image</filename> command - to build an image, extending it to include packages from - recipes in the workspace. - Using this command is useful when you want an image that - ready for immediate deployment onto a device for testing. - For proper integration into a final image, you need to - edit your custom image recipe appropriately. - </para> - - <para> - When you use the <filename>devtool build-image</filename> - command, you must supply the name of the image. - This command has no command line options: - <literallayout class='monospaced'> - $ devtool build-image <replaceable>image</replaceable> - </literallayout> - </para> - </section> - - <section id='devtool-deploying-your-software-on-the-target-machine'> - <title>Deploying Your Software on the Target Machine</title> - - <para> - Use the <filename>devtool deploy-target</filename> command to - deploy the recipe's build output to the live target machine: - <literallayout class='monospaced'> - $ devtool deploy-target <replaceable>recipe</replaceable> <replaceable>target</replaceable> - </literallayout> - The <replaceable>target</replaceable> is the address of the - target machine, which must be running an SSH server (i.e. - <filename>user@hostname[:destdir]</filename>). - </para> - - <para> - This command deploys all files installed during the - <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> - </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>). - </para> - </section> - - <section id='devtool-creating-the-workspace'> - <title>Creating the Workspace Layer in an Alternative Location</title> - - <para> - Use the <filename>devtool create-workspace</filename> command to - create a new workspace layer in your - <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> - </para> - - <para> - You can create a workspace layer anywhere by supplying - a pathname with the command. - The following command creates a new workspace layer named - "new-workspace": - <literallayout class='monospaced'> - $ devtool create-workspace /home/scottrif/new-workspace - </literallayout> - </para> - </section> - - <section id='devtool-get-the-status-of-the-recipes-in-your-workspace'> - <title>Get the Status of the Recipes in Your Workspace</title> - - <para> - Use the <filename>devtool status</filename> command to - list the recipes currently in your workspace. - Information includes the paths to their respective - external source trees. - </para> - - <para> - The <filename>devtool status</filename> command has no - command-line options: - <literallayout class='monospaced'> - devtool status - </literallayout> - Following is sample output after using - <link linkend='devtool-adding-a-new-recipe-to-the-workspace'><filename>devtool add</filename></link> - to create and add the <filename>mtr_0.86.bb</filename> recipe - to the <filename>workspace</filename> directory: - <literallayout class='monospaced'> - $ devtool status - mtr: /home/scottrif/poky/build/workspace/sources/mtr (/home/scottrif/poky/build/workspace/recipes/mtr/mtr_0.86.bb) - $ - </literallayout> - </para> - </section> - - <section id='devtool-search-for-available-target-recipes'> - <title>Search for Available Target Recipes</title> - - <para> - Use the <filename>devtool search</filename> command to - search for available target recipes. - The command matches the recipe name, package name, - description, and installed files. - The command displays the recipe name as a result of a - match. - </para> - - <para> - When you use the <filename>devtool search</filename> command, - you must supply a <replaceable>keyword</replaceable>. - The command uses the <replaceable>keyword</replaceable> when - searching for a match. - </para> - </section> - </section> - <section id="using-a-quilt-workflow"> <title>Using Quilt in Your Workflow</title> @@ -2192,4 +1593,62 @@ </note> </section> +<section id="platdev-appdev-devpyshell"> + <title>Using a Development Python Shell</title> + + <para> + Similar to working within a development shell as described in + the previous section, you can also spawn and work within an + interactive Python development shell. + When debugging certain commands or even when just editing packages, + <filename>devpyshell</filename> can be a useful tool. + When you invoke <filename>devpyshell</filename>, all tasks up to and + including + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-patch'><filename>do_patch</filename></ulink> + are run for the specified target. + Then a new terminal is opened. + Additionally, key Python objects and code are available in the same + way they are to BitBake tasks, in particular, the data store 'd'. + So, commands such as the following are useful when exploring the data + store and running functions: + <literallayout class='monospaced'> + pydevshell> d.getVar("STAGING_DIR", True) + '/media/build1/poky/build/tmp/sysroots' + pydevshell> d.getVar("STAGING_DIR", False) + '${TMPDIR}/sysroots' + pydevshell> d.setVar("FOO", "bar") + pydevshell> d.getVar("FOO", True) + 'bar' + pydevshell> d.delVar("FOO") + pydevshell> d.getVar("FOO", True) + pydevshell> bb.build.exec_func("do_unpack", d) + pydevshell> + </literallayout> + The commands execute just as if the OpenEmbedded build system were executing them. + Consequently, working this way can be helpful when debugging a build or preparing + software to be used with the OpenEmbedded build system. + </para> + + <para> + Following is an example that uses <filename>devpyshell</filename> on a target named + <filename>matchbox-desktop</filename>: + <literallayout class='monospaced'> + $ bitbake matchbox-desktop -c devpyshell + </literallayout> + </para> + + <para> + This command spawns a terminal and places you in an interactive + Python interpreter within the OpenEmbedded build environment. + The <ulink url='&YOCTO_DOCS_REF_URL;#var-OE_TERMINAL'><filename>OE_TERMINAL</filename></ulink> + variable controls what type of shell is opened. + </para> + + <para> + When you are finished using <filename>devpyshell</filename>, you + can exit the shell either by using Ctrl+d or closing the terminal + window. + </para> +</section> + </chapter> diff --git a/import-layers/yocto-poky/documentation/dev-manual/dev-manual.xml b/import-layers/yocto-poky/documentation/dev-manual/dev-manual.xml index 791a8cb6a..0012aaa3b 100644 --- a/import-layers/yocto-poky/documentation/dev-manual/dev-manual.xml +++ b/import-layers/yocto-poky/documentation/dev-manual/dev-manual.xml @@ -86,6 +86,11 @@ <date>April 2016</date> <revremark>Released with the Yocto Project 2.1 Release.</revremark> </revision> + <revision> + <revnumber>2.2</revnumber> + <date>October 2016</date> + <revremark>Released with the Yocto Project 2.2 Release.</revremark> + </revision> </revhistory> <copyright> diff --git a/import-layers/yocto-poky/documentation/dev-manual/figures/devtool-add-flow.png b/import-layers/yocto-poky/documentation/dev-manual/figures/devtool-add-flow.png Binary files differindex c09e60e35..985ac331f 100644 --- a/import-layers/yocto-poky/documentation/dev-manual/figures/devtool-add-flow.png +++ b/import-layers/yocto-poky/documentation/dev-manual/figures/devtool-add-flow.png diff --git a/import-layers/yocto-poky/documentation/dev-manual/figures/devtool-modify-flow.png b/import-layers/yocto-poky/documentation/dev-manual/figures/devtool-modify-flow.png Binary files differindex cd7f4d05b..fd684ffbe 100644 --- a/import-layers/yocto-poky/documentation/dev-manual/figures/devtool-modify-flow.png +++ b/import-layers/yocto-poky/documentation/dev-manual/figures/devtool-modify-flow.png diff --git a/import-layers/yocto-poky/documentation/dev-manual/figures/devtool-upgrade-flow.png b/import-layers/yocto-poky/documentation/dev-manual/figures/devtool-upgrade-flow.png Binary files differindex d25168c84..65474dad0 100644 --- a/import-layers/yocto-poky/documentation/dev-manual/figures/devtool-upgrade-flow.png +++ b/import-layers/yocto-poky/documentation/dev-manual/figures/devtool-upgrade-flow.png diff --git a/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-common.xml b/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-common.xml index 261471c46..a9aafd3c2 100644 --- a/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-common.xml +++ b/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev-common.xml @@ -384,9 +384,10 @@ <para> 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-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. + located in the build directory, + <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-B'><filename>B</filename></ulink><filename>}</filename>, + which expands to + <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename><filename>/linux-</filename><filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink><filename>}-${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink><filename>}-build</filename>. 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. @@ -394,6 +395,16 @@ see the "<ulink url='&YOCTO_DOCS_DEV_URL;#using-menuconfig'>Using <filename>menuconfig</filename></ulink>" section in the Yocto Project Development Manual. + <note> + You can determine what a variable expands to by looking + at the output of the <filename>bitbake -e</filename> + command: + <literallayout class='monospaced'> + $ bitbake -e virtual/kernel + </literallayout> + Search the output for the variable in which you are + interested to see exactly how it is expanded and used. + </note> </para> <para> @@ -512,8 +523,14 @@ </literallayout> Taking this step ensures you have the sources prepared and the configuration completed. - You can find the sources in the - <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/linux</filename> directory. + You can find the sources in the build directory within the + <filename>source/</filename> directory, which is a symlink + (i.e. <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-B'><filename>B</filename></ulink><filename>}/source</filename>). + The <filename>source/</filename> directory expands to + <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename><filename>/linux-</filename><filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink><filename>}-${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink><filename>}-build/source</filename>. + The directory pointed to by the + <filename>source/</filename> symlink is also known as + <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></ulink><filename>}</filename>. </para> <para> diff --git a/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev.xml b/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev.xml index fb11dd15c..12828d26c 100644 --- a/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev.xml +++ b/import-layers/yocto-poky/documentation/kernel-dev/kernel-dev.xml @@ -71,6 +71,11 @@ <date>April 2016</date> <revremark>Released with the Yocto Project 2.1 Release.</revremark> </revision> + <revision> + <revnumber>2.2</revnumber> + <date>October 2016</date> + <revremark>Released with the Yocto Project 2.2 Release.</revremark> + </revision> </revhistory> <copyright> diff --git a/import-layers/yocto-poky/documentation/mega-manual/figures/sdk-devtool-upgrade-flow.png b/import-layers/yocto-poky/documentation/mega-manual/figures/sdk-devtool-upgrade-flow.png Binary files differnew file mode 100644 index 000000000..65474dad0 --- /dev/null +++ b/import-layers/yocto-poky/documentation/mega-manual/figures/sdk-devtool-upgrade-flow.png diff --git a/import-layers/yocto-poky/documentation/mega-manual/mega-manual.xml b/import-layers/yocto-poky/documentation/mega-manual/mega-manual.xml index 154e369ab..c16e92861 100644 --- a/import-layers/yocto-poky/documentation/mega-manual/mega-manual.xml +++ b/import-layers/yocto-poky/documentation/mega-manual/mega-manual.xml @@ -55,6 +55,11 @@ <date>April 2016</date> <revremark>Released with the Yocto Project 2.1 Release.</revremark> </revision> + <revision> + <revnumber>2.2</revnumber> + <date>October 2016</date> + <revremark>Released with the Yocto Project 2.2 Release.</revremark> + </revision> </revhistory> <copyright> @@ -111,13 +116,17 @@ <xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../sdk-manual/sdk-intro.xml"/> <xi:include + xmlns:xi="http://www.w3.org/2003/XInclude" href="../sdk-manual/sdk-extensible.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../sdk-manual/sdk-using.xml"/> <xi:include - xmlns:xi="http://www.w3.org/2003/XInclude" href="../sdk-manual/sdk-extensible.xml"/> + xmlns:xi="http://www.w3.org/2003/XInclude" href="../sdk-manual/sdk-working-projects.xml"/> <xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../sdk-manual/sdk-appendix-obtain.xml"/> <xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../sdk-manual/sdk-appendix-customizing.xml"/> + <xi:include + xmlns:xi="http://www.w3.org/2003/XInclude" href="../sdk-manual/sdk-appendix-mars.xml"/> <!-- Includes bsp-guide title image and then bsp-guide chapters --> @@ -191,6 +200,9 @@ 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-devtool-reference.xml"/> + + <xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../ref-manual/ref-qa-checks.xml"/> <xi:include diff --git a/import-layers/yocto-poky/documentation/poky.ent b/import-layers/yocto-poky/documentation/poky.ent index 673ab23c9..b36c234b1 100644 --- a/import-layers/yocto-poky/documentation/poky.ent +++ b/import-layers/yocto-poky/documentation/poky.ent @@ -1,10 +1,10 @@ -<!ENTITY DISTRO "2.1"> -<!ENTITY DISTRO_COMPRESSED "21"> -<!ENTITY DISTRO_NAME_NO_CAP "krogoth"> -<!ENTITY DISTRO_NAME "Krogoth"> -<!ENTITY YOCTO_DOC_VERSION "2.1"> -<!ENTITY POKYVERSION "15.0.0"> -<!ENTITY POKYVERSION_COMPRESSED "1500"> +<!ENTITY DISTRO "2.2"> +<!ENTITY DISTRO_COMPRESSED "22"> +<!ENTITY DISTRO_NAME_NO_CAP "morty"> +<!ENTITY DISTRO_NAME "Morty"> +<!ENTITY YOCTO_DOC_VERSION "2.2"> +<!ENTITY POKYVERSION "17.0.0"> +<!ENTITY POKYVERSION_COMPRESSED "1700"> <!ENTITY YOCTO_POKY "poky-&DISTRO_NAME_NO_CAP;-&POKYVERSION;"> <!ENTITY COPYRIGHT_YEAR "2010-2016"> <!ENTITY YOCTO_DL_URL "http://downloads.yoctoproject.org"> @@ -62,7 +62,7 @@ <!ENTITY OE_INIT_FILE "oe-init-build-env"> <!ENTITY UBUNTU_HOST_PACKAGES_ESSENTIAL "gawk wget git-core diffstat unzip texinfo gcc-multilib \ build-essential chrpath socat"> -<!ENTITY FEDORA_HOST_PACKAGES_ESSENTIAL "gawk make wget tar bzip2 gzip python unzip perl patch \ +<!ENTITY FEDORA_HOST_PACKAGES_ESSENTIAL "gawk make wget tar bzip2 gzip python3 unzip perl patch \ diffutils diffstat git cpp gcc gcc-c++ glibc-devel texinfo chrpath \ ccache perl-Data-Dumper perl-Text-ParseWords perl-Thread-Queue perl-bignum socat \ findutils which"> diff --git a/import-layers/yocto-poky/documentation/profile-manual/profile-manual-intro.xml b/import-layers/yocto-poky/documentation/profile-manual/profile-manual-intro.xml index cc47f5267..d38d61a82 100644 --- a/import-layers/yocto-poky/documentation/profile-manual/profile-manual-intro.xml +++ b/import-layers/yocto-poky/documentation/profile-manual/profile-manual-intro.xml @@ -67,8 +67,10 @@ By default, the Yocto build system strips symbols from the binaries it packages, which makes it difficult to use some of the tools. - </para><para>You can prevent that by putting the following - in your local.conf when you build the image: + </para><para>You can prevent that by setting the + <ulink url='&YOCTO_DOCS_REF_URL;#var-INHIBIT_PACKAGE_STRIP'><filename>INHIBIT_PACKAGE_STRIP</filename></ulink> + variable to "1" in your + <filename>local.conf</filename> when you build the image: </para> </note> <literallayout class='monospaced'> diff --git a/import-layers/yocto-poky/documentation/profile-manual/profile-manual-usage.xml b/import-layers/yocto-poky/documentation/profile-manual/profile-manual-usage.xml index 310e8f01c..c0873e13a 100644 --- a/import-layers/yocto-poky/documentation/profile-manual/profile-manual-usage.xml +++ b/import-layers/yocto-poky/documentation/profile-manual/profile-manual-usage.xml @@ -60,8 +60,11 @@ <para> In particular, you'll get the most mileage out of perf if you - profile an image built with INHIBIT_PACKAGE_STRIP = "1" in your - local.conf. + profile an image built with the following in your + <filename>local.conf</filename> file: + <literallayout class='monospaced'> + <ulink url='&YOCTO_DOCS_REF_URL;#var-INHIBIT_PACKAGE_STRIP'>INHIBIT_PACKAGE_STRIP</ulink> = "1" + </literallayout> </para> <para> @@ -355,10 +358,10 @@ </para> <para> - One way around that is to put the following in your local.conf - when you build the image: + One way around that is to put the following in your + <filename>local.conf</filename> file when you build the image: <literallayout class='monospaced'> - INHIBIT_PACKAGE_STRIP = "1" + <ulink url='&YOCTO_DOCS_REF_URL;#var-INHIBIT_PACKAGE_STRIP'>INHIBIT_PACKAGE_STRIP</ulink> = "1" </literallayout> However, we already have an image with the binaries stripped, so what can we do to get perf to resolve the symbols? Basically diff --git a/import-layers/yocto-poky/documentation/profile-manual/profile-manual.xml b/import-layers/yocto-poky/documentation/profile-manual/profile-manual.xml index 1e0ccc1aa..4717906ca 100644 --- a/import-layers/yocto-poky/documentation/profile-manual/profile-manual.xml +++ b/import-layers/yocto-poky/documentation/profile-manual/profile-manual.xml @@ -71,6 +71,11 @@ <date>April 2016</date> <revremark>Released with the Yocto Project 2.1 Release.</revremark> </revision> + <revision> + <revnumber>2.2</revnumber> + <date>October 2016</date> + <revremark>Released with the Yocto Project 2.2 Release.</revremark> + </revision> </revhistory> <copyright> diff --git a/import-layers/yocto-poky/documentation/ref-manual/closer-look.xml b/import-layers/yocto-poky/documentation/ref-manual/closer-look.xml index 84ff584ba..b73e59ca7 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/closer-look.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/closer-look.xml @@ -888,7 +888,9 @@ class, you can add additional configuration options by using the <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link> - variable. + or + <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link> + variables. For information on how this variable works within that class, see the <filename>meta/classes/autotools.bbclass</filename> file. @@ -1209,6 +1211,199 @@ which includes the environment setup script. </para> </section> + + <section id='stamp-files-and-the-rerunning-of-tasks'> + <title>Stamp Files and the Rerunning of Tasks</title> + + <para> + For each task that completes successfully, BitBake writes a + stamp file into the + <link linkend='var-STAMPS_DIR'><filename>STAMPS_DIR</filename></link> + directory. + The beginning of the stamp file's filename is determined by the + <link linkend='var-STAMP'><filename>STAMP</filename></link> + variable, and the end of the name consists of the task's name + and current + <ulink url='&YOCTO_DOCS_BB_URL;#checksums'>input checksum</ulink>. + <note> + This naming scheme assumes that + <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_SIGNATURE_HANDLER'><filename>BB_SIGNATURE_HANDLER</filename></ulink> + is "OEBasicHash", which is almost always the case in + current OpenEmbedded. + </note> + To determine if a task needs to be rerun, BitBake checks if a + stamp file with a matching input checksum exists for the task. + If such a stamp file exists, the task's output is assumed to + exist and still be valid. + If the file does not exist, the task is rerun. + <note> + <para>The stamp mechanism is more general than the shared + state (sstate) cache mechanism described in the + "<link linkend='setscene-tasks-and-shared-state'>Setscene Tasks and Shared State</link>" + section. + BitBake avoids rerunning any task that has a valid + stamp file, not just tasks that can be accelerated through + the sstate cache.</para> + <para>However, you should realize that stamp files only + serve as a marker that some work has been done and that + these files do not record task output. + The actual task output would usually be somewhere in + <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> + (e.g. in some recipe's + <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.) + What the sstate cache mechanism adds is a way to cache task + output that can then be shared between build machines. + </para> + </note> + Since <filename>STAMPS_DIR</filename> is usually a subdirectory + of <filename>TMPDIR</filename>, removing + <filename>TMPDIR</filename> will also remove + <filename>STAMPS_DIR</filename>, which means tasks will + properly be rerun to repopulate <filename>TMPDIR</filename>. + </para> + + <para> + If you want some task to always be considered "out of date", + you can mark it with the + <ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>nostamp</filename></ulink> + varflag. + If some other task depends on such a task, then that task will + also always be considered out of date, which might not be what + you want. + </para> + + <para> + For details on how to view information about a task's + signature, see the + "<link linkend='usingpoky-viewing-task-variable-dependencies'>Viewing Task Variable Dependencies</link>" + section. + </para> + </section> + + <section id='setscene-tasks-and-shared-state'> + <title>Setscene Tasks and Shared State</title> + + <para> + The description of tasks so far assumes that BitBake needs to + build everything and there are no prebuilt objects available. + BitBake does support skipping tasks if prebuilt objects are + available. + These objects are usually made available in the form of a + shared state (sstate) cache. + <note> + For information on variables affecting sstate, see the + <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link> + and + <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link> + variables. + </note> + </para> + + <para> + The idea of a setscene task (i.e + <filename>do_</filename><replaceable>taskname</replaceable><filename>_setscene</filename>) + is a version of the task where + instead of building something, BitBake can skip to the end + result and simply place a set of files into specific locations + as needed. + In some cases, it makes sense to have a setscene task variant + (e.g. generating package files in the + <filename>do_package_write_*</filename> task). + In other cases, it does not make sense, (e.g. a + <link linkend='ref-tasks-patch'><filename>do_patch</filename></link> + task or + <link linkend='ref-tasks-unpack'><filename>do_unpack</filename></link> + task) since the work involved would be equal to or greater than + the underlying task. + </para> + + <para> + In the OpenEmbedded build system, the common tasks that have + setscene variants are <link linkend='ref-tasks-package'><filename>do_package</filename></link>, + <filename>do_package_write_*</filename>, + <link linkend='ref-tasks-deploy'><filename>do_deploy</filename></link>, + <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link>, + and + <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link>. + Notice that these are most of the tasks whose output is an + end result. + </para> + + <para> + The OpenEmbedded build system has knowledge of the relationship + between these tasks and other tasks that precede them. + For example, if BitBake runs + <filename>do_populate_sysroot_setscene</filename> for + something, there is little point in running any of the + <filename>do_fetch</filename>, <filename>do_unpack</filename>, + <filename>do_patch</filename>, + <filename>do_configure</filename>, + <filename>do_compile</filename>, and + <filename>do_install</filename> tasks. + However, if <filename>do_package</filename> needs to be run, + BitBake would need to run those other tasks. + </para> + + <para> + It becomes more complicated if everything can come from an + sstate cache because some objects are simply not required at + all. + For example, you do not need a compiler or native tools, such + as quilt, if there is nothing to compile or patch. + If the <filename>do_package_write_*</filename> packages are + available from sstate, BitBake does not need the + <filename>do_package</filename> task data. + </para> + + <para> + To handle all these complexities, BitBake runs in two phases. + The first is the "setscene" stage. + During this stage, BitBake first checks the sstate cache for + any targets it is planning to build. + BitBake does a fast check to see if the object exists rather + than a complete download. + If nothing exists, the second phase, which is the setscene + stage, completes and the main build proceeds. + </para> + + <para> + If objects are found in the sstate cache, the OpenEmbedded + build system works backwards from the end targets specified + by the user. + For example, if an image is being built, the OpenEmbedded build + system first looks for the packages needed for that image and + the tools needed to construct an image. + If those are available, the compiler is not needed. + Thus, the compiler is not even downloaded. + If something was found to be unavailable, or the download or + setscene task fails, the OpenEmbedded build system then tries + to install dependencies, such as the compiler, from the cache. + </para> + + <para> + The availability of objects in the sstate cache is handled by + the function specified by the + <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_HASHCHECK_FUNCTION'><filename>BB_HASHCHECK_FUNCTION</filename></ulink> + variable and returns a list of the objects that are available. + The function specified by the + <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_SETSCENE_DEPVALID'><filename>BB_SETSCENE_DEPVALID</filename></ulink> + variable is the function that determines whether a given + dependency needs to be followed, and whether for any given + relationship the function needs to be passed. + The function returns a True or False value. + </para> + + <para> + Once the setscene process completes, the OpenEmbedded build + system has a list of tasks that it believes it can "accelerate" + and therefore does not need to run. + There is a final function call to the function specified by the + <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_SETSCENE_VERIFY_FUNCTION2'><filename>BB_SETSCENE_VERIFY_FUNCTION2</filename></ulink> + variable that is able to require the tasks to be run that + that the OpenEmbedded build system initially was going to + skip. + </para> + </section> </section> <section id='images-dev-environment'> @@ -1403,6 +1598,10 @@ Specifies whether or not packagedata will be included in the extensible SDK for all recipes in the "world" target. </para></listitem> + <listitem><para><link linkend='var-SDK_INCLUDE_TOOLCHAIN'><filename>SDK_INCLUDE_TOOLCHAIN</filename></link>: + Specifies whether or not the toolchain will be included + when building the extensible SDK. + </para></listitem> <listitem><para><link linkend='var-SDK_LOCAL_CONF_WHITELIST'><filename>SDK_LOCAL_CONF_WHITELIST</filename></link>: A list of variables allowed through from the build system configuration into the extensible SDK configuration. diff --git a/import-layers/yocto-poky/documentation/ref-manual/faq.xml b/import-layers/yocto-poky/documentation/ref-manual/faq.xml index d2e4e8eb1..5f3f17349 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/faq.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/faq.xml @@ -33,9 +33,7 @@ <para id='faq-not-meeting-requirements'> My development system does not meet the required Git, tar, and Python versions. - In particular, I do not have Python 2.7.3 or greater, or - I do have Python 3.x, which is specifically not supported by - the Yocto Project. + In particular, I do not have Python 3.4.0 or greater. Can I still use the Yocto Project? </para> </question> diff --git a/import-layers/yocto-poky/documentation/dev-manual/figures/build-workspace-directory.png b/import-layers/yocto-poky/documentation/ref-manual/figures/build-workspace-directory.png Binary files differindex 5387d33f0..5387d33f0 100644 --- a/import-layers/yocto-poky/documentation/dev-manual/figures/build-workspace-directory.png +++ b/import-layers/yocto-poky/documentation/ref-manual/figures/build-workspace-directory.png diff --git a/import-layers/yocto-poky/documentation/ref-manual/introduction.xml b/import-layers/yocto-poky/documentation/ref-manual/introduction.xml index ce8fa5c65..90d965f6d 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/introduction.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/introduction.xml @@ -47,7 +47,7 @@ <listitem><para><emphasis> <link linkend='usingpoky'>Using the Yocto Project</link>:</emphasis> Provides an overview of the components that make up the Yocto Project - followed by information about debugng images created in the Yocto Project. + followed by information about debugging images created in the Yocto Project. </para></listitem> <listitem><para><emphasis> <link linkend='closer-look'>A Closer Look at the Yocto Project Development Environment</link>:</emphasis> @@ -80,6 +80,11 @@ Describes the tasks defined by the OpenEmbedded build system. </para></listitem> <listitem><para><emphasis> + <link linkend='ref-devtool-reference'><filename>devtool</filename> Quick Reference</link>:</emphasis> + Provides a quick reference for the <filename>devtool</filename> + command. + </para></listitem> + <listitem><para><emphasis> <link linkend='ref-qa-checks'>QA Error and Warning Messages</link>:</emphasis> Lists and describes QA warning and error messages. </para></listitem> @@ -252,12 +257,6 @@ <literallayout class='monospaced'> $ sudo apt-get install make xsltproc docbook-utils fop dblatex xmlto </literallayout></para></listitem> - <listitem><para><emphasis>SDK Installer Extras:</emphasis> - Packages needed if you are going to be using the - the standard or extensible SDK: - <literallayout class='monospaced'> - $ sudo apt-get install autoconf automake libtool libglib2.0-dev libarchive-dev - </literallayout></para></listitem> <listitem><para><emphasis>OpenEmbedded Self-Test (<filename>oe-selftest</filename>):</emphasis> Packages needed if you are going to run <filename>oe-selftest</filename>: @@ -296,17 +295,11 @@ $ sudo dnf install make docbook-style-dsssl docbook-style-xsl \ docbook-dtds docbook-utils fop libxslt dblatex xmlto xsltproc </literallayout></para></listitem> - <listitem><para><emphasis>SDK Installer Extras:</emphasis> - Packages needed if you are going to be using the - standard or extensible SDK: - <literallayout class='monospaced'> - $ sudo dnf install autoconf automake libtool glib2-devel libarchive-devel - </literallayout></para></listitem> <listitem><para><emphasis>OpenEmbedded Self-Test (<filename>oe-selftest</filename>):</emphasis> Packages needed if you are going to run <filename>oe-selftest</filename>: <literallayout class='monospaced'> - $ sudo dnf install GitPython + $ sudo dnf install python3-GitPython </literallayout> </para></listitem> </itemizedlist> @@ -339,12 +332,6 @@ <literallayout class='monospaced'> $ sudo zypper install make fop xsltproc dblatex xmlto </literallayout></para></listitem> - <listitem><para><emphasis>SDK Installer Extras:</emphasis> - Packages needed if you are going to be using the - standard or extensible SDK: - <literallayout class='monospaced'> - $ sudo zypper install autoconf automake libtool glib2-devel libarchive-devel - </literallayout></para></listitem> <listitem><para><emphasis>OpenEmbedded Self-Test (<filename>oe-selftest</filename>):</emphasis> Packages needed if you are going to run <filename>oe-selftest</filename>: @@ -394,12 +381,6 @@ $ sudo yum install make docbook-style-dsssl docbook-style-xsl \ docbook-dtds docbook-utils fop libxslt dblatex xmlto xsltproc </literallayout></para></listitem> - <listitem><para><emphasis>SDK Installer Extras:</emphasis> - Packages needed if you are going to be using the - standard or extensible SDK: - <literallayout class='monospaced'> - $ sudo yum install autoconf automake libtool glib2-devel libarchive-devel - </literallayout></para></listitem> <listitem><para><emphasis>OpenEmbedded Self-Test (<filename>oe-selftest</filename>):</emphasis> Packages needed if you are going to run <filename>oe-selftest</filename>: @@ -422,8 +403,7 @@ <itemizedlist> <listitem><para>Git 1.8.3.1 or greater</para></listitem> <listitem><para>tar 1.24 or greater</para></listitem> - <listitem><para>Python 2.7.3 or greater not including - Python 3.x, which is not supported.</para></listitem> + <listitem><para>Python 3.4.0 or greater</para></listitem> </itemizedlist> </para> diff --git a/import-layers/yocto-poky/documentation/ref-manual/migration.xml b/import-layers/yocto-poky/documentation/ref-manual/migration.xml index e6c0aa36b..3e7e6b084 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/migration.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/migration.xml @@ -2447,8 +2447,8 @@ </literallayout> </para></listitem> <listitem><para> - <filename>d.delVar('</filename><replaceable>varname</replaceable><filename>')</filename> and - <filename>d.setVar('</filename><replaceable>varname</replaceable><filename>', None)</filename> + <filename>d.delVar('</filename><replaceable>VARNAME</replaceable><filename>')</filename> and + <filename>d.setVar('</filename><replaceable>VARNAME</replaceable><filename>', None)</filename> result in the variable and all of its overrides being cleared out. Before the change, only the non-overridden values @@ -2740,13 +2740,13 @@ <para> Variable expressions, such as - <filename>${</filename><replaceable>varname</replaceable><filename>}</filename> + <filename>${</filename><replaceable>VARNAME</replaceable><filename>}</filename> no longer expand automatically within Python functions. Suppressing expansion was done to allow Python functions to construct shell scripts or other code for situations in which you do not want such expressions expanded. For any existing code that relies on these expansions, you need to - change the expansions to either expand the value of individual + change the expansions to expand the value of individual variables through <filename>d.getVar()</filename>. To alternatively expand more complex expressions, use <filename>d.expand()</filename>. @@ -2880,7 +2880,7 @@ to allow the default implementation from the <filename>autotools</filename> class to work such that <filename>autoreconf</filename> succeeds and produces a working - configure script), and to remove the + configure script, and to remove the overridden <filename>do_configure</filename> task such that the default implementation does get used. </para> @@ -2910,7 +2910,8 @@ <filename>do_rootfs</filename>, you should make edits so that those tasks are after the <link linkend='ref-tasks-image-complete'><filename>do_image_complete</filename></link> - task rather than before the task so that the your added tasks + task rather than after <filename>do_rootfs</filename> + so that the your added tasks run at the correct time. </para> @@ -3057,6 +3058,10 @@ <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-extensible'>extensible SDK</ulink>. For information on these SDKs and how to build and use them, see the <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-intro'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>. + <note> + The Yocto Project Eclipse IDE Plug-in is still supported and + is not affected by this change. + </note> </para> </section> @@ -3128,7 +3133,7 @@ The separate <filename>poky-tiny</filename> distribution now uses the musl C library instead of a heavily pared down <filename>glibc</filename>. - Using <filename>glibc</filename> results in a smaller + Using musl results in a smaller distribution and facilitates much greater maintainability because musl is designed to have a small footprint.</para> @@ -3194,6 +3199,21 @@ </para> </section> + <section id='migration-2.1-supporting-gobject-introspection'> + <title>Supporting GObject Introspection</title> + + <para> + This release supports generation of GLib Introspective + Repository (GIR) files through GObject introspection, which is + the standard mechanism for accessing GObject-based software from + runtime environments. + You can enable, disable, and test the generation of this data. + See the + "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-gobject-introspection-support'>Enabling GObject Introspection Support</ulink>" + section for more information. + </para> + </section> + <section id='migration-2.1-miscellaneous-changes'> <title>Miscellaneous Changes</title> @@ -3205,6 +3225,9 @@ If your host distribution does not provide a sufficiently recent version, you can install the buildtools, which will provide it. + See the + "<link linkend='required-git-tar-and-python-versions'>Required Git, tar, and Python Versions</link>" + section for more information on the buildtools tarball. </para></listitem> <listitem><para> The buggy and incomplete support for the RPM version 4 @@ -3213,6 +3236,25 @@ remains. </para></listitem> <listitem><para> + Previously, the following list of packages were removed + if package-management was not in + <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>, + regardless of any dependencies: + <literallayout class='monospaced'> + update-rc.d + base-passwd + shadow + update-alternatives + run-postinsts + </literallayout> + With the Yocto Project 2.1 release, these packages are only + removed if "read-only-rootfs" is in + <filename>IMAGE_FEATURES</filename>, since they might + still be needed for a read-write image even in the absence + of a package manager (e.g. if users need to be added, + modified, or removed at runtime). + </para></listitem> + <listitem><para> The <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-devtool-use-devtool-modify-to-modify-the-source-of-an-existing-component'><filename>devtool modify</filename></ulink> command now defaults to extracting the source since that @@ -3220,7 +3262,7 @@ The "-x" or "--extract" options are now no-ops. If you wish to provide your own existing source tree, you will now need to specify either the "-n" or - "--no-extract" option when running + "--no-extract" options when running <filename>devtool modify</filename>. </para></listitem> <listitem><para> @@ -3228,10 +3270,8 @@ or does not specify whether a keyboard is attached, then the default is to assume a keyboard is attached rather than assume no keyboard. - <note> - This change primarily affects the Sato UI. - </note> - </para></listitem> + This change primarily affects the Sato UI. + </para></listitem> <listitem><para> The <filename>.debug</filename> directory packaging is now automatic. @@ -3248,8 +3288,8 @@ This data has been replaced with <filename>getrusage()</filename> data and corrected IO statistics. - You will probably need to update code that reads the - <filename>buildstats</filename> data. + You will probably need to update any custom code that reads + the <filename>buildstats</filename> data. </para></listitem> <listitem><para> The @@ -3272,8 +3312,622 @@ <filename>meta-yocto-bsp</filename> layer. Most modern x86 boards do not rely on this file and it only adds kernel error messages during startup. - If you do still need the file, you can simply add - <filename>v86d</filename> to your image. + If you do still need to support + <filename>uvesafb</filename>, you can + simply add <filename>v86d</filename> to your image. + </para></listitem> + <listitem><para> + Build sysroot paths are now removed from debug symbol + files. + Removing these paths means that remote GDB using an + unstripped build system sysroot will no longer work + (although this was never documented to work). + The supported method to accomplish something similar is + to set <filename>IMAGE_GEN_DEBUGFS</filename> to "1", + which will generate a companion debug image + containing unstripped binaries and associated debug + sources alongside the image. + </para></listitem> + </itemizedlist> + </para> + </section> +</section> + +<section id='moving-to-the-yocto-project-2.2-release'> + <title>Moving to the Yocto Project 2.2 Release</title> + + <para> + This section provides migration information for moving to the + Yocto Project 2.2 Release from the prior release. + </para> + + <section id='migration-2.2-minimum-kernel-version'> + <title>Minimum Kernel Version</title> + + <para> + The minimum kernel version for the target system and for SDK + is now 3.2.0, due to the upgrade + to <filename>glibc 2.24</filename>. + Specifically, for AArch64-based targets the version is + 3.14. + For Nios II-based targets, the minimum kernel version is 3.19. + <note> + For x86 and x86_64, you can reset + <link linkend='var-OLDEST_KERNEL'><filename>OLDEST_KERNEL</filename></link> + to anything down to 2.6.32 if desired. + </note> + </para> + </section> + + <section id='migration-2.2-staging-directories-in-sysroot-simplified'> + <title>Staging Directories in Sysroot Has Been Simplified</title> + + <para> + The way directories are staged in sysroot has been simplified and + introduces the new + <link linkend='var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></link>, + <link linkend='var-SYSROOT_DIRS_NATIVE'><filename>SYSROOT_DIRS_NATIVE</filename></link>, + and + <link linkend='var-SYSROOT_DIRS_BLACKLIST'><filename>SYSROOT_DIRS_BLACKLIST</filename></link>. + See the + <ulink url='http://lists.openembedded.org/pipermail/openembedded-core/2016-May/121365.html'>v2 patch series on the OE-Core Mailing List</ulink> + for additional information. + </para> + </section> + + <section id='migration-2.2-removal-of-old-images-from-tmp-deploy-now-enabled'> + <title>Removal of Old Images and Other Files in <filename>tmp/deploy</filename> Now Enabled</title> + + <para> + Removal of old images and other files in + <filename>tmp/deploy/</filename> is now enabled by default due + to a new staging method used for those files. + As a result of this change, the + <filename>RM_OLD_IMAGE</filename> variable is now redundant. + </para> + </section> + + <section id='migration-2.2-python-changes'> + <title>Python Changes</title> + + <para> + The following changes for Python occurred: + </para> + + <section id='migration-2.2-bitbake-now-requires-python-3.4'> + <title>BitBake Now Requires Python 3.4+</title> + + <para> + BitBake requires Python 3.4 or greater. + </para> + </section> + + <section id='migration-2.2-utf-8-locale-required-on-build-host'> + <title>UTF-8 Locale Required on Build Host</title> + + <para> + A UTF-8 locale is required on the build host due to Python 3. + Since C.UTF-8 is not a standard, the default is en_US.UTF-8. + </para> + </section> + + <section id='migration-2.2-metadata-now-must-use-python-3-syntax'> + <title>Metadata Must Now Use Python 3 Syntax</title> + + <para> + The metadata is now required to use Python 3 syntax. + For help preparing metadata, see any of the many Python 3 porting + guides available. + Alternatively, you can reference the conversion commits for Bitbake + and you can use OE-Core as a guide for changes. + Following are particular areas of interest: + <literallayout class='monospaced'> + * subprocess command-line pipes needing locale decoding + * the syntax for octal values changed + * the <filename>iter*()</filename> functions changed name + * iterators now return views, not lists + * changed names for Python modules + </literallayout> + </para> + </section> + + <section id='migration-2.2-target-python-recipes-switched-to-python-3'> + <title>Target Python Recipes Switched to Python 3</title> + + <para> + Most target Python recipes have now been switched to Python 3. + Unfortunately, systems using RPM as a package manager and + providing online package-manager support through SMART still + require Python 2. + <note> + Python 2 and recipes that use it can still be built for the + target as with previous versions. + </note> + </para> + </section> + + <section id='migration-2.2-buildtools-tarball-includes-python-3'> + <title><filename>buildtools-tarball</filename> Includes Python 3</title> + + <para> + <filename>buildtools-tarball</filename> now includes Python 3. + </para> + </section> + </section> + + <section id='migration-2.2-uclibc-replaced-by-musl'> + <title>uClibc Replaced by musl</title> + + <para> + uClibc has been removed in favor of musl. + Musl has matured, is better maintained, and is compatible with a + wider range of applications as compared to uClibc. + </para> + </section> + + <section id='migration-2.2-B-no-longer-default-working-directory-for-tasks'> + <title><filename>${B}</filename> No Longer Default Working Directory for Tasks</title> + + <para> + <filename>${</filename><link linkend='var-B'><filename>B</filename></link><filename>}</filename> + is no longer the default working directory for tasks. + Consequently, any custom tasks you define now need to either + have the + <filename>[</filename><ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>dirs</filename></ulink><filename>]</filename> flag set, or the task needs to change into the + appropriate working directory manually (e.g using + <filename>cd</filename> for a shell task). + <note> + The preferred method is to use the + <filename>[dirs]</filename> flag. + </note> + </para> + </section> + + <section id='migration-2.2-runqemu-ported-to-python'> + <title><filename>runqemu</filename> Ported to Python</title> + + <para> + <filename>runqemu</filename> has been ported to Python and has + changed behavior in some cases. + Previous usage patterns continued to be supported. + </para> + + <para> + The new <filename>runqemu</filename> is a Python script. + Machine knowledge is no longer hardcoded into + <filename>runqemu</filename>. + You can choose to use the <filename>qemuboot</filename> + configuration file to define the BSP's own arguments and to make + it bootable with <filename>runqemu</filename>. + If you use a configuration file, use the following form: + <literallayout class='monospaced'> + <replaceable>image-name</replaceable>-<replaceable>machine</replaceable>.qemuboot.conf + </literallayout> + The configuration file enables fine-grained tuning of options + passed to QEMU without the <filename>runqemu</filename> script + hard-coding any knowledge about different machines. + Using a configuration file is particularly convenient when trying + to use QEMU with machines other than the + <filename>qemu*</filename> machines in OE-Core. + The <filename>qemuboot.conf</filename> file is generated by the + <filename>qemuboot</filename> + class when the root filesystem is being build (i.e. + build rootfs). + QEMU boot arguments can be set in BSP's configuration file and + the <filename>qemuboot</filename> class will save them to + <filename>qemuboot.conf</filename>. + </para> + + + <para> + If you want to use <filename>runqemu</filename> without a + configuration file, use the following command form: + <literallayout class='monospaced'> + $ runqemu <replaceable>machine</replaceable> <replaceable>rootfs</replaceable> <replaceable>kernel</replaceable> [<replaceable>options</replaceable>] + </literallayout> + Supported <replaceable>machines</replaceable> are as follows: + <literallayout class='monospaced'> + qemuarm + qemuarm64 + qemux86 + qemux86-64 + qemuppc + qemumips + qemumips64 + qemumipsel + qemumips64el + </literallayout> + Consider the following example, which uses the + <filename>qemux86-64</filename> machine, + provides a root filesystem, provides an image, and uses + the <filename>nographic</filename> option: + <literallayout class='monospaced'> +$ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.ext4 tmp/deploy/images/qemux86-64/bzImage nographic + </literallayout> + </para> + + <para> + Following is a list of variables that can be set in configuration + files such as <filename>bsp.conf</filename> to enable the BSP + to be booted by <filename>runqemu</filename>: + <note> + "QB" means "QEMU Boot". + </note> + <literallayout class='monospaced'> + QB_SYSTEM_NAME: QEMU name (e.g. "qemu-system-i386") + QB_OPT_APPEND: Options to append to QEMU (e.g. "-show-cursor") + QB_DEFAULT_KERNEL: Default kernel to boot (e.g. "bzImage") + QB_DEFAULT_FSTYPE: Default FSTYPE to boot (e.g. "ext4") + QB_MEM: Memory (e.g. "-m 512") + QB_MACHINE: QEMU machine (e.g. "-machine virt") + QB_CPU: QEMU cpu (e.g. "-cpu qemu32") + QB_CPU_KVM: Similar to QB_CPU except used for kvm support (e.g. "-cpu kvm64") + QB_KERNEL_CMDLINE_APPEND: Options to append to the kernel's -append + option (e.g. "console=ttyS0 console=tty") + QB_DTB: QEMU dtb name + QB_AUDIO_DRV: QEMU audio driver (e.g. "alsa", set it when support audio) + QB_AUDIO_OPT: QEMU audio option (e.g. "-soundhw ac97,es1370"), which is used + when QB_AUDIO_DRV is set. + QB_KERNEL_ROOT: Kernel's root (e.g. /dev/vda) + QB_TAP_OPT: Network option for 'tap' mode (e.g. + "-netdev tap,id=net0,ifname=@TAP@,script=no,downscript=no -device virtio-net-device,netdev=net0"). + runqemu will replace "@TAP@" with the one that is used, such as tap0, tap1 ... + QB_SLIRP_OPT: Network option for SLIRP mode (e.g. "-netdev user,id=net0 -device virtio-net-device,netdev=net0") + QB_ROOTFS_OPT: Used as rootfs (e.g. + "-drive id=disk0,file=@ROOTFS@,if=none,format=raw -device virtio-blk-device,drive=disk0"). + runqemu will replace "@ROOTFS@" with the one which is used, such as + core-image-minimal-qemuarm64.ext4. + QB_SERIAL_OPT: Serial port (e.g. "-serial mon:stdio") + QB_TCPSERIAL_OPT: tcp serial port option (e.g. + " -device virtio-serial-device -chardev socket,id=virtcon,port=@PORT@,host=127.0.0.1 -device virtconsole,chardev=virtcon" + runqemu will replace "@PORT@" with the port number which is used. + </literallayout> + </para> + + <para> + To use <filename>runqemu</filename>, set + <link linkend='var-IMAGE_CLASSES'><filename>IMAGE_CLASSES</filename></link> + as follows and run <filename>runqemu</filename>: + <note> + For command-line syntax, use + <filename>runqemu help</filename>. + </note> + <literallayout class='monospaced'> + IMAGE_CLASSES += "qemuboot" + </literallayout> + </para> + </section> + + <section id='migration-2.2-default-linker-hash-style-changed'> + <title>Default Linker Hash Style Changed</title> + + <para> + The default linker hash style for <filename>gcc-cross</filename> + is now "sysv" in order to catch recipes that are building software + without using the OpenEmbedded + <link linkend='var-LDFLAGS'><filename>LDFLAGS</filename></link>. + This change could result in seeing some "No GNU_HASH in the elf + binary" QA issues when building such recipes. + You need to fix these recipes so that they use the expected + <filename>LDFLAGS</filename>. + Depending on how the software is built, the build system used by + the software (e.g. a Makefile) might need to be patched. + However, sometimes making this fix is as simple as adding the + following to the recipe: + <literallayout class='monospaced'> + TARGET_CC_ARCH += "${LDFLAGS}" + </literallayout> + </para> + </section> + + <section id='migration-2.2-bitbake-changes'> + <title>BitBake Changes</title> + + <para> + The following changes took place for BitBake: + <itemizedlist> + <listitem><para> + The "goggle" UI and standalone image-writer tool have + been removed as they both require GTK+ 2.0 and + were not being maintained. + </para></listitem> + <listitem><para> + The Perforce fetcher now supports + <link linkend='var-SRCREV'><filename>SRCREV</filename></link> + for specifying the source revision to use, be it + <filename>${</filename><link linkend='var-AUTOREV'><filename>AUTOREV</filename></link><filename>}</filename>, + changelist number, p4date, or label, in preference to + separate + <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link> + parameters to specify these. + This change is more in-line with how the other fetchers + work for source control systems. + Recipes that fetch from Perforce will need to be updated + to use <filename>SRCREV</filename> in place of specifying + the source revision within + <filename>SRC_URI</filename>. + </para></listitem> + <listitem><para> + Some of BitBake's internal code structures for accessing + the recipe cache needed to be changed to support the new + multi-configuration functionality. + These changes will affect external tools that use BitBake's + tinfoil module. + For information on these changes, see the changes made to + the scripts supplied with OpenEmbedded-Core: + <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=189371f8393971d00bca0fceffd67cc07784f6ee'>1</ulink> + and + <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=4a5aa7ea4d07c2c90a1654b174873abb018acc67'>2</ulink>. + </para></listitem> + <listitem><para> + The task management code has been rewritten to avoid using + ID indirection in order to improve performance. + This change is unlikely to cause any problems for most + users. + However, the setscene verification function as pointed to + by <filename>BB_SETSCENE_VERIFY_FUNCTION</filename> + needed to change signature. + Consequently, a new variable named + <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_SETSCENE_VERIFY_FUNCTION2'><filename>BB_SETSCENE_VERIFY_FUNCTION2</filename></ulink> + has been added allowing multiple versions of BitBake + to work with suitably written metadata, which includes + OpenEmbedded-Core and Poky. + Anyone with custom BitBake task scheduler code might also + need to update the code to handle the new structure. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.2-swabber-has-been-removed'> + <title>Swabber has Been Removed</title> + + <para> + Swabber, a tool that was intended to detect host contamination in + the build process, has been removed, as it has been unmaintained + and unused for some time and was never particularly effective. + The OpenEmbedded build system has since incorporated a number of + mechanisms including enhanced QA checks that mean that there is + less of a need for such a tool. + </para> + </section> + + <section id='migration-2.2-removed-recipes'> + <title>Removed Recipes</title> + + <para> + The following recipes have been removed: + <itemizedlist> + <listitem><para> + <filename>augeas</filename>: + No longer needed and has been moved to + <filename>meta-oe</filename>. + </para></listitem> + <listitem><para> + <filename>directfb</filename>: + Unmaintained and has been moved to + <filename>meta-oe</filename>. + </para></listitem> + <listitem><para> + <filename>gcc</filename>: + Removed 4.9 version. + Versions 5.4 and 6.2 are still present. + </para></listitem> + <listitem><para> + <filename>gnome-doc-utils</filename>: + No longer needed. + </para></listitem> + <listitem><para> + <filename>gtk-doc-stub</filename>: + Replaced by <filename>gtk-doc</filename>. + </para></listitem> + <listitem><para> + <filename>gtk-engines</filename>: + No longer needed and has been moved to + <filename>meta-gnome</filename>. + </para></listitem> + <listitem><para> + <filename>gtk-sato-engine</filename>: + Became obsolete. + </para></listitem> + <listitem><para> + <filename>libglade</filename>: + No longer needed and has been moved to + <filename>meta-oe</filename>. + </para></listitem> + <listitem><para> + <filename>libmad</filename>: + Unmaintained and functionally replaced by + <filename>libmpg123</filename>. + <filename>libmad</filename> has been moved to + <filename>meta-oe</filename>. + </para></listitem> + <listitem><para> + <filename>libowl</filename>: + Became obsolete. + </para></listitem> + <listitem><para> + <filename>libxsettings-client</filename>: + No longer needed. + </para></listitem> + <listitem><para> + <filename>oh-puzzles</filename>: + Functionally replaced by + <filename>puzzles</filename>. + </para></listitem> + <listitem><para> + <filename>oprofileui</filename>: + Became obsolete. + OProfile has been largely supplanted by perf. + </para></listitem> + <listitem><para> + <filename>packagegroup-core-directfb.bb</filename>: + Removed. + </para></listitem> + <listitem><para> + <filename>core-image-directfb.bb</filename>: + Removed. + </para></listitem> + <listitem><para> + <filename>pointercal</filename>: + No longer needed and has been moved to + <filename>meta-oe</filename>. + </para></listitem> + <listitem><para> + <filename>python-imaging</filename>: + No longer needed and moved to + <filename>meta-python</filename> + </para></listitem> + <listitem><para> + <filename>python-pyrex</filename>: + No longer needed and moved to + <filename>meta-python</filename>. + </para></listitem> + <listitem><para> + <filename>sato-icon-theme</filename>: + Became obsolete. + </para></listitem> + <listitem><para> + <filename>swabber-native</filename>: + Swabber has been removed. + See the + <link linkend='migration-2.2-swabber-has-been-removed'>entry on Swabber</link>. + </para></listitem> + <listitem><para> + <filename>tslib</filename>: + No longer needed and has been moved to + <filename>meta-oe</filename>. + </para></listitem> + <listitem><para> + <filename>uclibc</filename>: + Removed in favor of musl. + </para></listitem> + <listitem><para> + <filename>xtscal</filename>: + No longer needed and moved to + <filename>meta-oe</filename> + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.2-removed-classes'> + <title>Removed Classes</title> + + <para> + The following classes have been removed: + <itemizedlist> + <listitem><para> + <filename>distutils-native-base</filename>: + No longer needed. + </para></listitem> + <listitem><para> + <filename>distutils3-native-base</filename>: + No longer needed. + </para></listitem> + <listitem><para> + <filename>sdl</filename>: + Only set + <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link> + and + <link linkend='var-SECTION'><filename>SECTION</filename></link>, + which are better set within the recipe instead. + </para></listitem> + <listitem><para> + <filename>sip</filename>: + Mostly unused. + </para></listitem> + <listitem><para> + <filename>swabber</filename>: + See the + <link linkend='migration-2.2-swabber-has-been-removed'>entry on Swabber</link>. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.2-minor-packaging-changes'> + <title>Minor Packaging Changes</title> + + <para> + The following minor packaging changes have occurred: + <itemizedlist> + <listitem><para> + <filename>grub</filename>: + Split <filename>grub-editenv</filename> into its own + package. + </para></listitem> + <listitem><para> + <filename>systemd</filename>: + Split container and vm related units into a new package, + systemd-container. + </para></listitem> + <listitem><para> + <filename>util-linux</filename>: + Moved <filename>prlimit</filename> to a separate + <filename>util-linux-prlimit</filename> package. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.2-miscellaneous-changes'> + <title>Miscellaneous Changes</title> + + <para> + The following miscellaneous changes have occurred: + <itemizedlist> + <listitem><para> + <filename>package_regex.inc</filename>: + Removed because the definitions + <filename>package_regex.inc</filename> previously contained + have been moved to their respective recipes. + </para></listitem> + <listitem><para> + Both <filename>devtool add</filename> and + <filename>recipetool create</filename> now use a fixed + <link linkend='var-SRCREV'><filename>SRCREV</filename></link> + by default when fetching from a Git repository. + You can override this in either case to use + <filename>${</filename><link linkend='var-AUTOREV'><filename>AUTOREV</filename></link><filename>}</filename> + instead by using the <filename>-a</filename> or + <filename>‐‐autorev</filename> command-line + option + </para></listitem> + <listitem><para> + <filename>distcc</filename>: + GTK+ UI is now disabled by default. + </para></listitem> + <listitem><para> + <filename>packagegroup-core-tools-testapps</filename>: + Removed Piglit. + </para></listitem> + <listitem><para> + <filename>image.bbclass</filename>: + Renamed COMPRESS(ION) to CONVERSION. + This change means that + <filename>COMPRESSIONTYPES</filename>, + <filename>COMPRESS_DEPENDS</filename> and + <filename>COMPRESS_CMD</filename> are deprecated in favor + of <filename>CONVERSIONTYPES</filename>, + <filename>CONVERSION_DEPENDS</filename> and + <filename>CONVERSION_CMD</filename>. + The <filename>COMPRESS*</filename> variable names will + still work in the 2.2 release but metadata that does not + need to be backwards-compatible should be changed to + use the new names as the <filename>COMPRESS*</filename> + ones will be removed in a future release. + </para></listitem> + <listitem><para> + <filename>gtk-doc</filename>: + A full version of <filename>gtk-doc</filename> is now + made available. + However, some old software might not be capable of using + the current version of <filename>gtk-doc</filename> + to build documentation. + You need to change recipes that build such software so that + they explicitly disable building documentation with + <filename>gtk-doc</filename>. </para></listitem> </itemizedlist> </para> diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-classes.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-classes.xml index e919bd7eb..2344a0406 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/ref-classes.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/ref-classes.xml @@ -161,13 +161,17 @@ cross-compilation. You can pass additional parameters to <filename>configure</filename> through the - <filename><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link></filename> variable. + <filename><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link></filename> + or + <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link> + variables. </para></listitem> <listitem><para><link linkend='ref-tasks-compile'><filename>do_compile</filename></link> - Runs <filename>make</filename> with arguments that specify the compiler and linker. You can pass additional arguments through - the <filename><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></filename> variable. + the <filename><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></filename> + variable. </para></listitem> <listitem><para><link linkend='ref-tasks-install'><filename>do_install</filename></link> - Runs <filename>make install</filename> and passes in @@ -194,7 +198,14 @@ class or the <link linkend='ref-classes-package'><filename>package</filename></link> class. + </para> + + <para> The class also contains some commonly used functions such as + <filename>oe_runmake</filename>, which runs + <filename>make</filename> with the arguments specified in + <link linkend='var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></link> + variable as well as the arguments passed directly to <filename>oe_runmake</filename>. </para> </section> @@ -1092,36 +1103,6 @@ </para> </section> -<section id='ref-classes-gummiboot'> - <title><filename>gummiboot.bbclass</filename></title> - - <para> - The <filename>gummiboot</filename> class provides functions specific - to the gummiboot bootloader for building bootable images. - This is an internal class and is not intended to be - used directly. - Set the - <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link> - variable to "gummiboot" to use this class. - </para> - - <para> - For information on more variables used and supported in this class, - see the - <link linkend='var-GUMMIBOOT_CFG'><filename>GUMMIBOOT_CFG</filename></link>, - <link linkend='var-GUMMIBOOT_ENTRIES'><filename>GUMMIBOOT_ENTRIES</filename></link>, - and - <link linkend='var-GUMMIBOOT_TIMEOUT'><filename>GUMMIBOOT_TIMEOUT</filename></link> - variables. - </para> - - <para> - You can also see the - <ulink url='http://freedesktop.org/wiki/Software/gummiboot/'>Gummiboot documentation</ulink> - for more information. - </para> -</section> - <section id='ref-classes-gzipnative'> <title><filename>gzipnative.bbclass</filename></title> @@ -1381,22 +1362,6 @@ </para> </section> -<section id='ref-classes-image-swab'> - <title><filename>image-swab.bbclass</filename></title> - - <para> - The <filename>image-swab</filename> class enables the - <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/swabber'>Swabber</ulink> - tool in order to detect and log accesses to the host system during - the OpenEmbedded build process. - <note> - This class is currently unmaintained. - The <filename>strace</filename> package needs to be installed - in the build host as a dependency for this tool. - </note> - </para> -</section> - <section id='ref-classes-image-vm'> <title><filename>image-vm.bbclass</filename></title> @@ -1599,6 +1564,17 @@ <link linkend='var-FILES'><filename>FILES</filename></link> variable values that contain "//", which is invalid. </para></listitem> + <listitem><para><emphasis><filename>host-user-contaminated:</filename></emphasis> + Checks that no package produced by the recipe contains any + files outside of <filename>/home</filename> with a user or + group ID that matches the user running BitBake. + A match usually indicates that the files are being installed + with an incorrect UID/GID, since target IDs are independent + from host IDs. + For additional information, see the section describing the + <link linkend='ref-tasks-install'><filename>do_install</filename></link> + task. + </para></listitem> <listitem><para><emphasis><filename>incompatible-license:</filename></emphasis> Report when packages are excluded from being created due to being marked with a license that is in @@ -1626,6 +1602,25 @@ <filename>do_install</filename> if the files are not needed in any package. </para></listitem> + <listitem><para><emphasis><filename>invalid-chars:</filename></emphasis> + Checks that the recipe metadata variables + <link linkend='var-DESCRIPTION'><filename>DESCRIPTION</filename></link>, + <link linkend='var-SUMMARY'><filename>SUMMARY</filename></link>, + <link linkend='var-LICENSE'><filename>LICENSE</filename></link>, + and + <link linkend='var-SECTION'><filename>SECTION</filename></link> + do not contain non-UTF-8 characters. + Some package managers do not support such characters. + </para></listitem> + <listitem><para><emphasis><filename>invalid-packageconfig:</filename></emphasis> + Checks that no undefined features are being added to + <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link>. + For example, any name "foo" for which the following form + does not exist: + <literallayout class='monospaced'> + PACKAGECONFIG[foo] = "..." + </literallayout> + </para></listitem> <listitem><para><emphasis><filename>la:</filename></emphasis> Checks <filename>.la</filename> files for any <filename>TMPDIR</filename> paths. @@ -3294,6 +3289,43 @@ </para> </section> +<section id='ref-classes-systemd-boot'> + <title><filename>systemd-boot.bbclass</filename></title> + + <para> + The <filename>systemd-boot</filename> class provides functions specific + to the systemd-boot bootloader for building bootable images. + This is an internal class and is not intended to be used directly. + <note> + The <filename>systemd-boot</filename> class is a result from + merging the <filename>gummiboot</filename> class used in previous + Yocto Project releases with the <filename>systemd</filename> + project. + </note> + Set the + <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link> + variable to "systemd-boot" to use this class. + Doing so creates a standalone EFI bootloader that is not dependent + on systemd. + </para> + + <para> + For information on more variables used and supported in this class, + see the + <link linkend='var-SYSTEMD_BOOT_CFG'><filename>SYSTEMD_BOOT_CFG</filename></link>, + <link linkend='var-SYSTEMD_BOOT_ENTRIES'><filename>SYSTEMD_BOOT_ENTRIES</filename></link>, + and + <link linkend='var-SYSTEMD_BOOT_TIMEOUT'><filename>SYSTEMD_BOOT_TIMEOUT</filename></link> + variables. + </para> + + <para> + You can also see the + <ulink url='http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/'>Systemd-boot documentation</ulink> + for more information. + </para> +</section> + <section id='ref-classes-terminal'> <title><filename>terminal.bbclass</filename></title> @@ -3698,7 +3730,9 @@ software that uses the Waf build system. You can use the <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link> - variable to specify additional configuration options to be passed on + or + <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link> + variables to specify additional configuration options to be passed on the Waf command line. </para> </section> diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-devtool-reference.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-devtool-reference.xml new file mode 100644 index 000000000..1764f0196 --- /dev/null +++ b/import-layers/yocto-poky/documentation/ref-manual/ref-devtool-reference.xml @@ -0,0 +1,607 @@ +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" +[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > + +<chapter id='ref-devtool-reference'> + <title><filename>devtool</filename> Quick Reference</title> + + <para> + The <filename>devtool</filename> command-line tool provides a number + of features that help you build, test, and package software. + This command is available alongside the <filename>bitbake</filename> + command. + Additionally, the <filename>devtool</filename> command is a key + part of the extensible SDK. + </para> + + <para> + This chapter provides a Quick Reference for the + <filename>devtool</filename> command. + For more information on how to apply the command when using the + extensible SDK, see the + "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-extensible'>Using the Extensible SDK</ulink>" + section in the Yocto Project Software Development Kit (SDK) Developer's + Guide. + </para> + + <section id='devtool-getting-help'> + <title>Getting Help</title> + + <para> + The <filename>devtool</filename> command line is organized + similarly to Git in that it has a number of sub-commands for + each function. + You can run <filename>devtool --help</filename> to see all + the commands: + <literallayout class='monospaced'> + $ devtool --help + usage: devtool [--basepath BASEPATH] [--bbpath BBPATH] [-d] [-q] + [--color COLOR] [-h] + <subcommand> ... + + OpenEmbedded development tool + + options: + --basepath BASEPATH Base directory of SDK / build directory + --bbpath BBPATH Explicitly specify the BBPATH, rather than getting it + from the metadata + -d, --debug Enable debug output + -q, --quiet Print only errors + --color COLOR Colorize output (where COLOR is auto, always, never) + -h, --help show this help message and exit + + subcommands: + Beginning work on a recipe: + add Add a new recipe + modify Modify the source for an existing recipe + upgrade Upgrade an existing recipe + Getting information: + status Show workspace status + search Search available recipes + Working on a recipe in the workspace: + edit-recipe Edit a recipe file in your workspace + configure-help Get help on configure script options + build Build a recipe + update-recipe Apply changes from external source tree to recipe + reset Remove a recipe from your workspace + finish Finish working on a recipe in your workspace + Testing changes on target: + deploy-target Deploy recipe output files to live target machine + undeploy-target Undeploy recipe output files in live target machine + build-image Build image including workspace recipe packages + Advanced: + create-workspace Set up workspace in an alternative location + extract Extract the source for an existing recipe + sync Synchronize the source tree for an existing recipe + Use devtool <subcommand> --help to get help on a specific command + </literallayout> + </para> + + <para> + As directed in the general help output, you can get more + syntax on a specific command by providing the command + name and using <filename>--help</filename>: + <literallayout class='monospaced'> + $ devtool add --help + usage: devtool add [-h] [--same-dir | --no-same-dir] [--fetch URI] + [--version VERSION] [--no-git] [--autorev] [--binary] + [--also-native] [--src-subdir SUBDIR] + [recipename] [srctree] [fetchuri] + + Adds a new recipe to the workspace to build a specified source tree. Can + optionally fetch a remote URI and unpack it to create the source tree. + + arguments: + recipename Name for new recipe to add (just name - no version, + path or extension). If not specified, will attempt to + auto-detect it. + srctree Path to external source tree. If not specified, a + subdirectory of + /home/scottrif/poky/build/workspace/sources will be + used. + fetchuri Fetch the specified URI and extract it to create the + source tree + + options: + -h, --help show this help message and exit + --same-dir, -s Build in same directory as source + --no-same-dir Force build in a separate build directory + --fetch URI, -f URI Fetch the specified URI and extract it to create the + source tree (deprecated - pass as positional argument + instead) + --version VERSION, -V VERSION + Version to use within recipe (PV) + --no-git, -g If fetching source, do not set up source tree as a git + repository + --autorev, -a When fetching from a git repository, set SRCREV in the + recipe to a floating revision instead of fixed + --binary, -b Treat the source tree as something that should be + installed verbatim (no compilation, same directory + structure). Useful with binary packages e.g. RPMs. + --also-native Also add native variant (i.e. support building recipe + for the build host as well as the target machine) + --src-subdir SUBDIR Specify subdirectory within source tree to use + </literallayout> + </para> + </section> + + <section id='devtool-the-workspace-layer-structure'> + <title>The Workspace Layer Structure</title> + + <para> + <filename>devtool</filename> uses a "Workspace" layer + in which to accomplish builds. + This layer is not specific to any single + <filename>devtool</filename> command but is rather a common + working area used across the tool. + </para> + + <para> + The following figure shows the workspace structure: + </para> + + <para> + <imagedata fileref="figures/build-workspace-directory.png" + width="6in" depth="5in" align="left" scale="70" /> + </para> + + <para> + <literallayout class='monospaced'> + attic - A directory created if devtool believes it preserve + anything when you run "devtool reset". For example, if you + run "devtool add", make changes to the recipe, and then + run "devtool reset", devtool takes notice that the file has + been changed and moves it into the attic should you still + want the recipe. + + README - Provides information on what is in workspace layer and how to + manage it. + + .devtool_md5 - A checksum file used by devtool. + + appends - A directory that contains *.bbappend files, which point to + external source. + + conf - A configuration directory that contains the layer.conf file. + + recipes - A directory containing recipes. This directory contains a + folder for each directory added whose name matches that of the + added recipe. devtool places the <replaceable>recipe</replaceable>.bb file + within that sub-directory. + + sources - A directory containing a working copy of the source files used + when building the recipe. This is the default directory used + as the location of the source tree when you do not provide a + source tree path. This directory contains a folder for each + set of source files matched to a corresponding recipe. + </literallayout> + </para> + </section> + + <section id='devtool-adding-a-new-recipe-to-the-workspace'> + <title>Adding a New Recipe to the Workspace Layer</title> + + <para> + Use the <filename>devtool add</filename> command to add a new recipe + to the workspace layer. + The recipe you add should not exist - + <filename>devtool</filename> creates it for you. + The source files the recipe uses should exist in an external + area. + </para> + + <para> + The following example creates and adds a new recipe named + <filename>jackson</filename> to a workspace layer the tool creates. + The source code built by the recipes resides in + <filename>/home/scottrif/sources/jackson</filename>: + <literallayout class='monospaced'> + $ devtool add jackson /home/scottrif/sources/jackson + </literallayout> + </para> + + <para> + If you add a recipe and the workspace layer does not exist, + the command creates the layer and populates it as + described in + "<link linkend='devtool-the-workspace-layer-structure'>The Workspace Layer Structure</link>" + section. + </para> + + <para> + Running <filename>devtool add</filename> when the + workspace layer exists causes the tool to add the recipe, + append files, and source files into the existing workspace layer. + The <filename>.bbappend</filename> file is created to point + to the external source tree. + </para> + </section> + + <section id='devtool-extracting-the-source-for-an-existing-recipe'> + <title>Extracting the Source for an Existing Recipe</title> + + <para> + Use the <filename>devtool extract</filename> command to + extract the source for an existing recipe. + When you use this command, you must supply the root name + of the recipe (i.e. no version, paths, or extensions), and + you must supply the directory to which you want the source + extracted. + </para> + + <para> + Additional command options let you control the name of a + development branch into which you can checkout the source + and whether or not to keep a temporary directory, which is + useful for debugging. + </para> + </section> + + <section id='devtool-synchronizing-a-recipes-extracted-source-tree'> + <title>Synchronizing a Recipe's Extracted Source Tree</title> + + <para> + Use the <filename>devtool sync</filename> command to + synchronize a previously extracted source tree for an + existing recipe. + When you use this command, you must supply the root name + of the recipe (i.e. no version, paths, or extensions), and + you must supply the directory to which you want the source + extracted. + </para> + + <para> + Additional command options let you control the name of a + development branch into which you can checkout the source + and whether or not to keep a temporary directory, which is + useful for debugging. + </para> + </section> + + <section id='devtool-modifying-a-recipe'> + <title>Modifying an Existing Recipe</title> + + <para> + Use the <filename>devtool modify</filename> command to begin + modifying the source of an existing recipe. + This command is very similar to the + <ulink url='&YOCTO_DOCS_DEV_URL;#devtool-adding-a-new-recipe-to-the-workspace'><filename>add</filename></ulink> + command except that it does not physically create the + recipe in the workspace layer because the recipe already + exists in an another layer. + </para> + + <para> + The <filename>devtool modify</filename> command extracts the + source for a recipe, sets it up as a Git repository if the + source had not already been fetched from Git, checks out a + branch for development, and applies any patches from the recipe + as commits on top. + You can use the following command to checkout the source + files: + <literallayout class='monospaced'> + $ devtool modify <replaceable>recipe</replaceable> + </literallayout> + Using the above command form, <filename>devtool</filename> uses + the existing recipe's + <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link> + statement to locate the upstream source, extracts the source + into the default sources location in the workspace. + The default development branch used is "devtool". + </para> + </section> + + <section id='devtool-edit-an-existing-recipe'> + <title>Edit an Existing Recipe</title> + + <para> + Use the <filename>devtool edit-recipe</filename> command + to run the default editor, which is identified using the + <filename>EDITOR</filename> variable, on the specified recipe. + </para> + + <para> + When you use the <filename>devtool edit-recipe</filename> + command, you must supply the root name of the recipe + (i.e. no version, paths, or extensions). + Also, the recipe file itself must reside in the workspace + as a result of the <filename>devtool add</filename> or + <filename>devtool upgrade</filename> commands. + However, you can override that requirement by using the + "-a" or "--any-recipe" option. + Using either of these options allows you to edit any recipe + regardless of its location. + </para> + </section> + + <section id='devtool-updating-a-recipe'> + <title>Updating a Recipe</title> + + <para> + Use the <filename>devtool update-recipe</filename> command to + update your recipe with patches that reflect changes you make + to the source files. + For example, if you know you are going to work on some + code, you could first use the + <ulink url='&YOCTO_DOCS_DEV_URL;#devtool-modifying-a-recipe'><filename>devtool modify</filename></ulink> + command to extract the code and set up the workspace. + After which, you could modify, compile, and test the code. + </para> + + <para> + When you are satisfied with the results and you have committed + your changes to the Git repository, you can then + run the <filename>devtool update-recipe</filename> to create the + patches and update the recipe: + <literallayout class='monospaced'> + $ devtool update-recipe <replaceable>recipe</replaceable> + </literallayout> + If you run the <filename>devtool update-recipe</filename> + without committing your changes, the command ignores the + changes. + </para> + + <para> + Often, you might want to apply customizations made to your + software in your own layer rather than apply them to the + original recipe. + If so, you can use the + <filename>-a</filename> or <filename>--append</filename> + option with the <filename>devtool update-recipe</filename> + command. + These options allow you to specify the layer into which to + write an append file: + <literallayout class='monospaced'> + $ devtool update-recipe <replaceable>recipe</replaceable> -a <replaceable>base-layer-directory</replaceable> + </literallayout> + The <filename>*.bbappend</filename> file is created at the + appropriate path within the specified layer directory, which + may or may not be in your <filename>bblayers.conf</filename> + file. + If an append file already exists, the command updates it + appropriately. + </para> + </section> + + <section id='devtool-upgrading-a-recipe'> + <title>Upgrading a Recipe</title> + + <para> + Use the <filename>devtool upgrade</filename> command + to upgrade an existing recipe to a new upstream version. + The command puts the upgraded recipe file into the + workspace along with any associated files, and extracts + the source tree to a specified location should patches + need rebased or added to as a result of the upgrade. + </para> + + <para> + When you use the <filename>devtool upgrade</filename> command, + you must supply the root name of the recipe (i.e. no version, + paths, or extensions), and you must supply the directory + to which you want the source extracted. + Additional command options let you control things such as + the version number to which you want to upgrade (i.e. the + <link linkend='var-PV'><filename>PV</filename></link>), + the source revision to which you want to upgrade (i.e. the + <link linkend='var-SRCREV'><filename>SRCREV</filename></link>, + whether or not to apply patches, and so forth. + </para> + </section> + + <section id='devtool-resetting-a-recipe'> + <title>Resetting a Recipe</title> + + <para> + Use the <filename>devtool reset</filename> command to remove a + recipe and its configuration (e.g. the corresponding + <filename>.bbappend</filename> file) from the workspace layer. + Realize that this command deletes the recipe and the + append file. + The command does not physically move them for you. + Consequently, you must be sure to physically relocate your + updated recipe and the append file outside of the workspace + layer before running the <filename>devtool reset</filename> + command. + </para> + + <para> + If the <filename>devtool reset</filename> command detects that + the recipe or the append files have been modified, the + command preserves the modified files in a separate "attic" + subdirectory under the workspace layer. + </para> + + <para> + Here is an example that resets the workspace directory that + contains the <filename>mtr</filename> recipe: + <literallayout class='monospaced'> + $ devtool reset mtr + NOTE: Cleaning sysroot for recipe mtr... + NOTE: Leaving source tree /home/scottrif/poky/build/workspace/sources/mtr as-is; if you no + longer need it then please delete it manually + $ + </literallayout> + </para> + </section> + + <section id='devtool-building-your-recipe'> + <title>Building Your Recipe</title> + + <para> + Use the <filename>devtool build</filename> command to cause the + OpenEmbedded build system to build your recipe. + The <filename>devtool build</filename> command is equivalent to + <filename>bitbake -c populate_sysroot</filename>. + </para> + + <para> + When you use the <filename>devtool build</filename> command, + you must supply the root name of the recipe (i.e. no version, + paths, or extensions). + You can use either the "-s" or the "--disable-parallel-make" + option to disable parallel makes during the build. + Here is an example: + <literallayout class='monospaced'> + $ devtool build <replaceable>recipe</replaceable> + </literallayout> + </para> + </section> + + <section id='devtool-building-your-image'> + <title>Building Your Image</title> + + <para> + Use the <filename>devtool build-image</filename> command + to build an image, extending it to include packages from + recipes in the workspace. + Using this command is useful when you want an image that + ready for immediate deployment onto a device for testing. + For proper integration into a final image, you need to + edit your custom image recipe appropriately. + </para> + + <para> + When you use the <filename>devtool build-image</filename> + command, you must supply the name of the image. + This command has no command line options: + <literallayout class='monospaced'> + $ devtool build-image <replaceable>image</replaceable> + </literallayout> + </para> + </section> + + <section id='devtool-deploying-your-software-on-the-target-machine'> + <title>Deploying Your Software on the Target Machine</title> + + <para> + Use the <filename>devtool deploy-target</filename> command to + deploy the recipe's build output to the live target machine: + <literallayout class='monospaced'> + $ devtool deploy-target <replaceable>recipe</replaceable> <replaceable>target</replaceable> + </literallayout> + The <replaceable>target</replaceable> is the address of the + target machine, which must be running an SSH server (i.e. + <filename>user@hostname[:destdir]</filename>). + </para> + + <para> + This command deploys all files installed during the + <link linkend='ref-tasks-install'><filename>do_install</filename></link> + task. + Furthermore, you do not need to have package management enabled + within the target machine. + If you do, the package manager is bypassed. + <note><title>Notes</title> + <para> + The <filename>deploy-target</filename> + functionality is for development only. + You should never use it to update an image that will be + used in production. + </para> + </note> + </para> + </section> + + <section id='devtool-removing-your-software-from-the-target-machine'> + <title>Removing Your Software from the Target Machine</title> + + <para> + Use the <filename>devtool undeploy-target</filename> command to + remove deployed build output from the target machine. + For the <filename>devtool undeploy-target</filename> command to + work, you must have previously used the + <ulink url='&YOCTO_DOCS_DEV_URL;#devtool-deploying-your-software-on-the-target-machine'><filename>devtool deploy-target</filename></ulink> + command. + <literallayout class='monospaced'> + $ devtool undeploy-target <replaceable>recipe</replaceable> <replaceable>target</replaceable> + </literallayout> + The <replaceable>target</replaceable> is the address of the + target machine, which must be running an SSH server (i.e. + <filename>user@hostname</filename>). + </para> + </section> + + <section id='devtool-creating-the-workspace'> + <title>Creating the Workspace Layer in an Alternative Location</title> + + <para> + Use the <filename>devtool create-workspace</filename> command to + create a new workspace layer in your + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. + When you create a new workspace layer, it is populated with the + <filename>README</filename> file and the + <filename>conf</filename> directory only. + </para> + + <para> + The following example creates a new workspace layer in your + current working and by default names the workspace layer + "workspace": + <literallayout class='monospaced'> + $ devtool create-workspace + </literallayout> + </para> + + <para> + You can create a workspace layer anywhere by supplying + a pathname with the command. + The following command creates a new workspace layer named + "new-workspace": + <literallayout class='monospaced'> + $ devtool create-workspace /home/scottrif/new-workspace + </literallayout> + </para> + </section> + + <section id='devtool-get-the-status-of-the-recipes-in-your-workspace'> + <title>Get the Status of the Recipes in Your Workspace</title> + + <para> + Use the <filename>devtool status</filename> command to + list the recipes currently in your workspace. + Information includes the paths to their respective + external source trees. + </para> + + <para> + The <filename>devtool status</filename> command has no + command-line options: + <literallayout class='monospaced'> + $ devtool status + </literallayout> + Following is sample output after using + <ulink url='&YOCTO_DOCS_DEV_URL;#devtool-adding-a-new-recipe-to-the-workspace'><filename>devtool add</filename></ulink> + to create and add the <filename>mtr_0.86.bb</filename> recipe + to the <filename>workspace</filename> directory: + <literallayout class='monospaced'> + $ devtool status + mtr: /home/scottrif/poky/build/workspace/sources/mtr (/home/scottrif/poky/build/workspace/recipes/mtr/mtr_0.86.bb) + $ + </literallayout> + </para> + </section> + + <section id='devtool-search-for-available-target-recipes'> + <title>Search for Available Target Recipes</title> + + <para> + Use the <filename>devtool search</filename> command to + search for available target recipes. + The command matches the recipe name, package name, + description, and installed files. + The command displays the recipe name as a result of a + match. + </para> + + <para> + When you use the <filename>devtool search</filename> command, + you must supply a <replaceable>keyword</replaceable>. + The command uses the <replaceable>keyword</replaceable> when + searching for a match. + </para> + </section> +</chapter> +<!-- +vim: expandtab tw=80 ts=4 +--> diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-features.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-features.xml index fd7693500..cd1bcb024 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/ref-features.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/ref-features.xml @@ -144,6 +144,27 @@ </para></listitem> <listitem><para><emphasis>bluetooth:</emphasis> Include bluetooth support (integrated BT only).</para></listitem> + <listitem><para><emphasis>bluez5:</emphasis> Include + BlueZ Version 5, which provides core Bluetooth layers and + protocols support. + <note> + The default value for the + <link linkend='var-DISTRO_FEATURES'><filename>DISTRO FEATURES</filename></link> + variable includes "bluetooth", which causes bluez5 + to be backfilled in for bluetooth support. + If you do not want bluez5 backfilled and would rather + use bluez4, you need to use the + <link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename></link> + variable as follows: + <literallayout class='monospaced'> + DISTRO_FEATURES_BACKFILL_CONSIDERED = "bluez5" + </literallayout> + Setting this variable tells the OpenEmbedded build + system that you have considered but ruled + out using the bluez5 feature and that bluez4 will be + used. + </note> + </para></listitem> <listitem><para><emphasis>cramfs:</emphasis> Include CramFS support.</para></listitem> <listitem><para><emphasis>directfb:</emphasis> diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-manual.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-manual.xml index 6834d5f0a..09f34fb52 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/ref-manual.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/ref-manual.xml @@ -102,6 +102,11 @@ <date>April 2016</date> <revremark>Released with the Yocto Project 2.1 Release.</revremark> </revision> + <revision> + <revnumber>2.2</revnumber> + <date>October 2016</date> + <revremark>Released with the Yocto Project 2.2 Release.</revremark> + </revision> </revhistory> <copyright> @@ -140,6 +145,8 @@ <xi:include href="ref-tasks.xml"/> + <xi:include href="ref-devtool-reference.xml"/> + <xi:include href="ref-qa-checks.xml"/> <xi:include href="ref-images.xml"/> diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-qa-checks.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-qa-checks.xml index 4fcf1db61..86456bd42 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/ref-qa-checks.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/ref-qa-checks.xml @@ -918,7 +918,8 @@ can be found then it should be implemented. I can't find one at the moment. and the upstream change log or release notes. Once you have worked out what the appropriate change is, you can update - <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link> + <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>, + <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link>, or the individual <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link> option values accordingly. @@ -1107,7 +1108,7 @@ can be found then it should be implemented. I can't find one at the moment. <listitem> <para id='qa-issue-installed-vs-shipped'> <code> - <recipename>: Files/directories were installed but not shipped [installed-vs-shipped] + <recipename>: Files/directories were installed but not shipped in any package [installed-vs-shipped] </code> </para> diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-structure.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-structure.xml index e51ceb1bf..541a47e55 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/ref-structure.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/ref-structure.xml @@ -660,9 +660,21 @@ <title><filename>build/tmp/cache/</filename></title> <para> - When BitBake parses the metadata, it creates a cache file of the result that can - be used when subsequently running commands. - BitBake stores these results here on a per-machine basis. + When BitBake parses the metadata (recipes and configuration files), + it caches the results in <filename>build/tmp/cache/</filename> + to speed up future builds. + The results are stored on a per-machine basis. + </para> + + <para> + During subsequent builds, BitBake checks each recipe (together + with, for example, any files included or appended to it) to see + if they have been modified. + Changes can be detected, for example, through file modification + time (mtime) changes and hashing of file contents. + If no changes to the file are detected, then the parsed result + stored in the cache is reused. + If the file has changed, it is reparsed. </para> </section> @@ -801,8 +813,9 @@ <title><filename>build/tmp/stamps/</filename></title> <para> - This directory holds information that BitBake uses for accounting purposes - to track what tasks have run and when they have run. + This directory holds information that BitBake uses for + accounting purposes to track what tasks have run and when they + have run. The directory is sub-divided by architecture, package name, and version. Following is an example: @@ -812,6 +825,13 @@ Although the files in the directory are empty of data, BitBake uses the filenames and timestamps for tracking purposes. </para> + + <para> + For information on how BitBake uses stamp files to determine if + a task should be rerun, see the + "<link linkend='stamp-files-and-the-rerunning-of-tasks'>Stamp Files and the Rerunning of Tasks</link>" + section. + </para> </section> <section id='structure-build-tmp-log'> diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-tasks.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-tasks.xml index c46debb55..e9859c1fa 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/ref-tasks.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/ref-tasks.xml @@ -19,6 +19,10 @@ <para> The following sections describe normal tasks associated with building a recipe. + For more information on tasks and dependencies, see the + "<ulink url='&YOCTO_DOCS_BB_URL;#tasks'>Tasks</ulink>" and + "<ulink url='&YOCTO_DOCS_BB_URL;#dependencies'>Dependencies</ulink>" + sections in the BitBake User Manual. </para> <section id='ref-tasks-build'> @@ -31,43 +35,23 @@ </para> </section> - <section id='ref-tasks-checkpkg'> - <title><filename>do_checkpkg</filename></title> - - <para> - Provides information about the recipe including its upstream - version and status. - The upstream version and status reveals whether or not a version - of the recipe exists upstream and a status of not updated, updated, - or unknown. - </para> + <section id='ref-tasks-compile'> + <title><filename>do_compile</filename></title> <para> - The <filename>checkpkg</filename> task is included as part of the - <link linkend='ref-classes-distrodata'><filename>distrodata</filename></link> - class. + Compiles the source code. + This task runs with the current working directory set + to + <filename>${</filename><link linkend='var-B'><filename>B</filename></link><filename>}</filename>. </para> <para> - To build the <filename>checkpkg</filename> task, use the - <filename>bitbake</filename> command with the "-c" option and - task name: - <literallayout class='monospaced'> - $ bitbake core-image-minimal -c checkpkg - </literallayout> - By default, the results are stored in - <link linkend='var-LOG_DIR'><filename>$LOG_DIR</filename></link> - (e.g. <filename>$BUILD_DIR/tmp/log</filename>). - </para> - </section> - - <section id='ref-tasks-compile'> - <title><filename>do_compile</filename></title> - - <para> - Compiles the source in the compilation directory, which is pointed - to by the - <link linkend='var-B'><filename>B</filename></link> variable. + The default behavior of this task is to run the + <filename>oe_runmake</filename> function if a makefile + (<filename>Makefile</filename>, <filename>makefile</filename>, + or <filename>GNUmakefile</filename>) is found. + If no such file is found, the <filename>do_compile</filename> + task does nothing. </para> </section> @@ -86,6 +70,20 @@ <para> Configures the source by enabling and disabling any build-time and configuration options for the software being built. + The task runs with the current working directory set to + <filename>${</filename><link linkend='var-B'><filename>B</filename></link><filename>}</filename>. + </para> + + <para> + The default behavior of this task is to run + <filename>oe_runmake clean</filename> if a makefile + (<filename>Makefile</filename>, <filename>makefile</filename>, + or <filename>GNUmakefile</filename>) is found and + <link linkend='var-CLEANBROKEN'><filename>CLEANBROKEN</filename></link> + is not set to "1". + If no such file is found or the <filename>CLEANBROKEN</filename> + variable is set to "1", the <filename>do_configure</filename> + task does nothing. </para> </section> @@ -102,18 +100,62 @@ <title><filename>do_deploy</filename></title> <para> - Writes output files that are to be deployed to the deploy - directory, which is defined by the - <link linkend='var-DEPLOYDIR'><filename>DEPLOYDIR</filename></link> - variable. + Writes output files that are to be deployed to + <filename>${</filename><link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link><filename>}</filename>. + The task runs with the current working directory set to + <filename>${</filename><link linkend='var-B'><filename>B</filename></link><filename>}</filename>. </para> <para> - The <filename>do_deploy</filename> task is a - shared state (sstate) task, which means that the task can - be accelerated through sstate use. - Realize also that if the task is re-executed, any previous output - is removed (i.e. "cleaned"). + Recipes implementing this task should inherit the + <link linkend='ref-classes-deploy'><filename>deploy</filename></link> + class and should write the output to + <filename>${</filename><link linkend='var-DEPLOYDIR'><filename>DEPLOYDIR</filename></link><filename>}</filename>, + which is not to be confused with + <filename>${</filename><link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link><filename>}</filename>. + The <filename>deploy</filename> class sets up + <filename>do_deploy</filename> as a shared state (sstate) task that + can be accelerated through sstate use. + The sstate mechanism takes care of copying the output from + <filename>${DEPLOYDIR}</filename> to + <filename>${DEPLOY_DIR_IMAGE}</filename>. + <note> + <title>Caution</title> + Do not write the output directly to + <filename>${DEPLOY_DIR_IMAGE}</filename>, as this causes + the sstate mechanism to malfunction. + </note> + </para> + + <para> + The <filename>do_deploy</filename> task is not added as a task + by default and consequently needs to be added manually. + If you want the task to run after + <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>, + you can add it by doing the following: + <literallayout class='monospaced'> + addtask deploy after do_compile + </literallayout> + Adding <filename>do_deploy</filename> after other tasks works the + same way. + <note> + You do not need to add <filename>before do_build</filename> + to the <filename>addtask</filename> command (though it is + harmless), because the + <link linkend='ref-classes-base'><filename>base</filename></link> + class contains the following: + <literallayout class='monospaced'> + do_build[recrdeptask] += "do_deploy" + </literallayout> + See the + "<ulink url='&YOCTO_DOCS_BB_URL;#dependencies'>Dependencies</ulink>" + section in the BitBake User Manual for more information. + </note> + </para> + + <para> + If the <filename>do_deploy</filename> task re-executes, any + previous output is removed (i.e. "cleaned"). </para> </section> @@ -213,11 +255,59 @@ <title><filename>do_install</filename></title> <para> - Copies files from the compilation directory, which is defined by - the - <link linkend='var-B'><filename>B</filename></link> variable, - to a holding area defined by the - <link linkend='var-D'><filename>D</filename></link> variable. + Copies files that are to be packaged into the holding area + <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename>. + This task runs with the current working directory set to + <filename>${</filename><link linkend='var-B'><filename>B</filename></link><filename>}</filename>, + which is the compilation directory. + The <filename>do_install</filename> task, as well as other tasks + that either directly or indirectly depend on the installed files + (e.g. + <link linkend='ref-tasks-package'><filename>do_package</filename></link>, + <link linkend='ref-tasks-package_write_deb'><filename>do_package_write_*</filename></link>, + and + <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>), + run under + <link linkend='fakeroot-and-pseudo'>fakeroot</link>. + <note> + <title>Caution</title> + + <para> + When installing files, be careful not to set the owner and + group IDs of the installed files to unintended values. + Some methods of copying files, notably when using the + recursive <filename>cp</filename> command, can preserve the + UID and/or GID of the original file, which is usually not + what you want. + The + <link linkend='ref-classes-insane'><filename>host-user-contaminated</filename></link> + QA check checks for files that probably have the wrong + ownership. + </para> + + <para> + Safe methods for installing files include the following: + <itemizedlist> + <listitem><para> + The <filename>install</filename> utility. + This utility is the preferred method. + </para></listitem> + <listitem><para> + The <filename>cp</filename> command with the + "--no-preserve=ownership" option. + </para></listitem> + <listitem><para> + The <filename>tar</filename> command with the + "--no-same-owner" option. + See the <filename>bin_package.bbclass</filename> + file in the <filename>meta/classes</filename> + directory of the + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> + for an example. + </para></listitem> + </itemizedlist> + </para> + </note> </para> </section> @@ -234,8 +324,26 @@ <title><filename>do_package</filename></title> <para> - Analyzes the content of the holding area and splits it into subsets - based on available packages and files. + Analyzes the content of the holding area + <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename> + and splits the content into subsets based on available packages + and files. + This task makes use of the + <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link> + and + <link linkend='var-FILES'><filename>FILES</filename></link> + variables. + </para> + + <para> + The <filename>do_package</filename> task, in conjunction with the + <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link> + task, also saves some important package metadata. + For additional information, see the + <link linkend='var-PKGDESTWORK'><filename>PKGDESTWORK</filename></link> + variable and the + "<link linkend='automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</link>" + section. </para> </section> @@ -309,8 +417,11 @@ <title><filename>do_packagedata</filename></title> <para> - Creates package metadata used by the build system to generate the - final packages. + Saves package metadata generated by the + <link linkend='ref-tasks-package'><filename>do_package</filename></link> + task in + <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link> + to make it available globally. </para> </section> @@ -349,16 +460,25 @@ <title><filename>do_populate_sysroot</filename></title> <para> - Copies a subset of the files installed by the + Stages (copies) a subset of the files installed by the <link linkend='ref-tasks-install'><filename>do_install</filename></link> - task into the sysroot to make them available to other recipes. - Files that would typically not be needed by other recipes at build - time are skipped. - Skipped files include files installed into - <filename>/etc.</filename> - For information on what files are copied, see the - <link linkend='ref-classes-staging'><filename>staging</filename></link> - class. + task into the appropriate sysroot. + For information on how to access these files from other recipes, + see the + <link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR*</filename></link> + variables. + Directories that would typically not be needed by other recipes at + build time (e.g. <filename>/etc</filename>) are not copied by + default. + </para> + + <para> + For information on what directories are copied by default, see the + <link linkend='var-SYSROOT_DIRS'><filename>SYSROOT_DIRS*</filename></link> + variables. + You can change these variables inside your recipe if you need + to make additional (or fewer) directories available to other + recipes at build time. </para> <para> @@ -417,6 +537,36 @@ <filename>bitbake -c</filename> command-line option): </para> + <section id='ref-tasks-checkpkg'> + <title><filename>do_checkpkg</filename></title> + + <para> + Provides information about the recipe including its upstream + version and status. + The upstream version and status reveals whether or not a version + of the recipe exists upstream and a status of not updated, updated, + or unknown. + </para> + + <para> + The <filename>checkpkg</filename> task is included as part of the + <link linkend='ref-classes-distrodata'><filename>distrodata</filename></link> + class. + </para> + + <para> + To build the <filename>checkpkg</filename> task, use the + <filename>bitbake</filename> command with the "-c" option and + task name: + <literallayout class='monospaced'> + $ bitbake core-image-minimal -c checkpkg + </literallayout> + By default, the results are stored in + <link linkend='var-LOG_DIR'><filename>$LOG_DIR</filename></link> + (e.g. <filename>$BUILD_DIR/tmp/log</filename>). + </para> + </section> + <section id='ref-tasks-checkuri'> <title><filename>do_checkuri</filename></title> @@ -541,6 +691,22 @@ </para> </section> + <section id='ref-tasks-devpyshell'> + <title><filename>do_devpyshell</filename></title> + + <para> + Starts a shell in which an interactive Python interpreter allows + you to interact with the BitBake build environment. + From within this shell, you can directly examine and set + bits from the data store and execute functions as if within + the BitBake environment. + See the + "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devpyshell'>Using a Development Python Shell</ulink>" + section in the Yocto Project Development Manual for more + information about using <filename>devpyshell</filename>. + </para> + </section> + <section id='ref-tasks-devshell'> <title><filename>do_devshell</filename></title> diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-variables.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-variables.xml index d55bccdc6..ce331d85b 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/ref-variables.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/ref-variables.xml @@ -536,7 +536,7 @@ By default, this directory is the same as the <link linkend='var-S'><filename>S</filename></link> directory, which is defined as: <literallayout class='monospaced'> - S = "${WORKDIR}/${BP}/" + S = "${WORKDIR}/${BP}" </literallayout> </para> @@ -995,6 +995,29 @@ BBCLASSEXTEND =+ "native nativesdk" BBCLASSEXTEND =+ "multilib:<replaceable>multilib_name</replaceable>" </literallayout> + <note> + <para> + Internally, the <filename>BBCLASSEXTEND</filename> + mechanism generates recipe variants by rewriting + variable values and applying overrides such as + <filename>_class-native</filename>. + For example, to generate a native version of a recipe, + a + <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link> + on "foo" is rewritten to a <filename>DEPENDS</filename> + on "foo-native". + </para> + + <para> + Even when using <filename>BBCLASSEXTEND</filename>, the + recipe is only parsed once. + Parsing once adds some limitations. + For example, it is not possible to + include a different file depending on the variant, + since <filename>include</filename> statements are + processed when the recipe is parsed. + </para> + </note> </para> </glossdef> </glossentry> @@ -1202,6 +1225,42 @@ </glossdef> </glossentry> + <glossentry id='var-BBMULTICONFIG'><glossterm>BBMULTICONFIG</glossterm> + <info> + BBMULTICONFIG[doc] = "Specifies each separate configuration when you are building targets with multiple configurations." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Specifies each separate configuration when you are + building targets with multiple configurations. + Use this variable in your + <filename>conf/local.conf</filename> configuration file. + Specify a <replaceable>multiconfigname</replaceable> for + each configuration file you are using. + For example, the following line specifies three + configuration files: + <literallayout class='monospaced'> + BBMULTIFONFIG = "configA configB configC" + </literallayout> + Each configuration file you use must reside in the + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory's</ulink> + <filename>conf/multiconfig</filename> directory + (e.g. + <replaceable>build_directory</replaceable><filename>/conf/multiconfig/configA.conf</filename>). + </para> + + <para> + For information on how to use + <filename>BBMULTICONFIG</filename> in an environment that + supports building targets with multiple configurations, + see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-building-targets-with-multiple-configurations'>Building Targets with Multiple Configurations</ulink>" + section in the Yocto Project Development Manual. + </para> + </glossdef> + </glossentry> + <glossentry id='var-BBPATH'><glossterm>BBPATH</glossterm> <info> BBPATH[doc] = "Used by BitBake to locate .bbclass and configuration files. This variable is analogous to the PATH variable." @@ -1336,28 +1395,25 @@ <glossentry id='var-BPN'><glossterm>BPN</glossterm> <info> - BPN[doc] = "The bare name of the recipe. This variable is a version of the PN variable but removes common suffixes and prefixes." + BPN[doc] = "This variable is a version of the PN variable but removes common suffixes and prefixes." </info> <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - The bare name of the recipe. This variable is a version of the <link linkend='var-PN'><filename>PN</filename></link> - variable but removes common suffixes such as - <filename>-native</filename> and - <filename>-cross</filename> as well - as removes common prefixes such as multilib's + variable with common prefixes and suffixes + removed, such as <filename>nativesdk-</filename>, + <filename>-cross</filename>, + <filename>-native</filename>, and multilib's <filename>lib64-</filename> and <filename>lib32-</filename>. - The exact list of suffixes removed is specified by the - <link linkend='var-SPECIAL_PKGSUFFIX'><filename>SPECIAL_PKGSUFFIX</filename></link> - variable. - The exact list of prefixes removed is specified by the + The exact lists of prefixes and suffixes removed are + specified by the <link linkend='var-MLPREFIX'><filename>MLPREFIX</filename></link> - variable. - Prefixes are removed for <filename>multilib</filename> - and <filename>nativesdk-</filename> cases. + and + <link linkend='var-SPECIAL_PKGSUFFIX'><filename>SPECIAL_PKGSUFFIX</filename></link> + variables, respectively. </para> </glossdef> </glossentry> @@ -1972,22 +2028,36 @@ An internal variable specifying the special class override that should currently apply (e.g. "class-target", "class-native", and so forth). - The classes that use this variable set it to - appropriate values. + The classes that use this variable (e.g. + <link linkend='ref-classes-native'><filename>native</filename></link>, + <link linkend='ref-classes-nativesdk'><filename>nativesdk</filename></link>, + and so forth) set the variable to appropriate values. + <note> + <filename>CLASSOVERRIDE</filename> gets its default + "class-target" value from the + <filename>bitbake.conf</filename> file. + </note> </para> <para> - You do not normally directly interact with this variable. - The value for the <filename>CLASSOVERRIDE</filename> - variable goes into - <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link> - and then can be used as an override. - Here is an example where "python-native" is added to - <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link> - only when building for the <filename>-native</filename> case: + As an example, the following override allows you to install + extra files, but only when building for the target: + <literallayout class='monospaced'> + do_install_append_class-target() { + install my-extra-file ${D}${sysconfdir} + } + </literallayout> + Here is an example where <filename>FOO</filename> + is set to "native" when building for the build host, and + to "other" when not building for the build host: <literallayout class='monospaced'> - DEPENDS_append_class-native = " python-native" + FOO_class-native = "native" + FOO = "other" </literallayout> + The underlying mechanism behind + <filename>CLASSOVERRIDE</filename> is simply that it is + included in the default value of + <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>. </para> </glossdef> </glossentry> @@ -2574,8 +2644,13 @@ task. This location defaults to: <literallayout class='monospaced'> - ${WORKDIR}/image + ${<link linkend='var-WORKDIR'>WORKDIR</link>}/image </literallayout> + <note><title>Caution</title> + Tasks that read from or write to this directory should + run under + <link linkend='fakeroot-and-pseudo'>fakeroot</link>. + </note> </para> </glossdef> </glossentry> @@ -2748,34 +2823,117 @@ <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - Lists a recipe's build-time dependencies - (i.e. other recipe files). - The system ensures that all the dependencies listed - have been built and have their contents in the appropriate - sysroots before the recipe's configure task is executed. + Lists a recipe's build-time dependencies. + These are dependencies on other recipes whose + contents (e.g. headers and shared libraries) are needed + by the recipe at build time. </para> <para> - Consider this simple example for two recipes named "a" and - "b" that produce similarly named packages. - In this example, the <filename>DEPENDS</filename> - statement appears in the "a" recipe: + As an example, consider a recipe <filename>foo</filename> + that contains the following assignment: <literallayout class='monospaced'> - DEPENDS = "b" + DEPENDS = "bar" </literallayout> - Here, the dependency is such that the + The practical effect of the previous assignment is that + all files installed by bar will be available in the + appropriate staging sysroot, given by the + <link linkend='var-STAGING_DIR'><filename>STAGING_DIR*</filename></link> + variables, by the time the <link linkend='ref-tasks-configure'><filename>do_configure</filename></link> - task for recipe "a" depends on the + task for <filename>foo</filename> runs. + This mechanism is implemented by having + <filename>do_configure</filename> depend on the <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link> - task of recipe "b". - This means anything that recipe "b" puts into sysroot - is available when recipe "a" is configuring itself. + task of each recipe listed in <filename>DEPENDS</filename>, + through a + <filename>[</filename><ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>deptask</filename></ulink><filename>]</filename> + declaration in the + <link linkend='ref-classes-base'><filename>base</filename></link> + class. + <note> + It seldom is necessary to reference, for example, + <filename>STAGING_DIR_HOST</filename> explicitly. + The standard classes and build-related variables are + configured to automatically use the appropriate staging + sysroots. + </note> + As another example, <filename>DEPENDS</filename> can also + be used to add utilities that run on the build machine + during the build. + For example, a recipe that makes use of a code generator + built by the recipe <filename>codegen</filename> might have + the following: + <literallayout class='monospaced'> + DEPENDS = "codegen-native" + </literallayout> + For more information, see the + <link linkend='ref-classes-native'><filename>native</filename></link> + class and the + <link linkend='var-EXTRANATIVEPATH'><filename>EXTRANATIVEPATH</filename></link> + variable. + <note> + <title>Notes</title> + <itemizedlist> + <listitem><para> + <filename>DEPENDS</filename> is a list of + recipe names. + Or, to be more precise, it is a list of + <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link> + names, which usually match recipe names. + Putting a package name such as "foo-dev" in + <filename>DEPENDS</filename> does not make + sense. + Use "foo" instead, as this will put files + from all the packages that make up + <filename>foo</filename>, which includes + those from <filename>foo-dev</filename>, into + the sysroot. + </para></listitem> + <listitem><para> + One recipe having another recipe in + <filename>DEPENDS</filename> does not by itself + add any runtime dependencies between the + packages produced by the two recipes. + However, as explained in the + "<link linkend='automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</link>" + section, runtime dependencies will often be + added automatically, meaning + <filename>DEPENDS</filename> alone is + sufficient for most recipes. + </para></listitem> + <listitem><para> + Counterintuitively, + <filename>DEPENDS</filename> is often necessary + even for recipes that install precompiled + components. + For example, if <filename>libfoo</filename> + is a precompiled library that links against + <filename>libbar</filename>, then + linking against <filename>libfoo</filename> + requires both <filename>libfoo</filename> + and <filename>libbar</filename> to be available + in the sysroot. + Without a <filename>DEPENDS</filename> from the + recipe that installs <filename>libfoo</filename> + to the recipe that installs + <filename>libbar</filename>, other recipes might + fail to link against + <filename>libfoo</filename>. + </para></listitem> + </itemizedlist> + </note> </para> <para> For information on runtime dependencies, see the <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> variable. + You can also see the + "<ulink url='&YOCTO_DOCS_BB_URL;#tasks'>Tasks</ulink>" and + "<ulink url='&YOCTO_DOCS_BB_URL;#dependencies'>Dependencies</ulink>" + sections in the BitBake User Manual for additional + information on tasks and dependencies. </para> </glossdef> </glossentry> @@ -3072,15 +3230,15 @@ by UUID to allow the kernel to locate the root device even if the device name changes due to differences in hardware configuration. - By default, <filename>SYSLINUX_ROOT</filename> is set + By default, <filename>ROOT_VM</filename> is set as follows: <literallayout class='monospaced'> - SYSLINUX_ROOT = "root=/dev/sda2" + ROOT_VM ?= "root=/dev/sda2" </literallayout> However, you can change this to locate the root device using the disk signature instead: <literallayout class='monospaced'> - SYSLINUX_ROOT = "root=PARTUUID=${DISK_SIGNATURE}-02" + ROOT_VM = "root=PARTUUID=${DISK_SIGNATURE}-02" </literallayout> </para> @@ -3341,20 +3499,28 @@ <glossentry id='var-DISTROOVERRIDES'><glossterm>DISTROOVERRIDES</glossterm> <info> - DISTROOVERRIDES[doc] = "Lists overrides specific to the current distribution. By default, the variable list includes the value of the DISTRO variable." + DISTROOVERRIDES[doc] = "A colon-separated list of overrides specific to the current distribution." </info> <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - This variable lists overrides specific to the current - distribution. - By default, the variable list includes the value of the - <filename><link linkend='var-DISTRO'>DISTRO</link></filename> - variable. - You can extend the variable to apply any variable overrides - you want as part of the distribution and are not - already in <filename>OVERRIDES</filename> through - some other means. + A colon-separated list of overrides specific to the + current distribution. + By default, this list includes the value of + <link linkend='var-DISTRO'><filename>DISTRO</filename></link>. + </para> + + <para> + You can extend <filename>DISTROOVERRIDES</filename> + to add extra overrides that should apply to + the distribution. + </para> + + <para> + The underlying mechanism behind + <filename>DISTROOVERRIDES</filename> is simply that it + is included in the default value of + <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>. </para> </glossdef> </glossentry> @@ -3463,13 +3629,13 @@ <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>), the <filename>EFI_PROVIDER</filename> variable specifies the EFI bootloader to use. - The default is "grub-efi", but "gummiboot" can be used + The default is "grub-efi", but "systemd-boot" can be used instead. </para> <para> See the - <link linkend='ref-classes-gummiboot'><filename>gummiboot</filename></link> + <link linkend='ref-classes-systemd-boot'><filename>systemd-boot</filename></link> class for more information. </para> </glossdef> @@ -3893,6 +4059,27 @@ </glossdef> </glossentry> + <glossentry id='var-EXTRANATIVEPATH'><glossterm>EXTRANATIVEPATH</glossterm> + <info> + EXTRANATIVEPATH[doc] = "A list of subdirectories of ${STAGING_BINDIR_NATIVE} added to the beginning of the environment variable PATH." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + A list of subdirectories of + <filename>${</filename><link linkend='var-STAGING_BINDIR_NATIVE'><filename>STAGING_BINDIR_NATIVE</filename></link><filename>}</filename> + added to the beginning of the environment variable + <filename>PATH</filename>. + As an example, the following prepends + "${STAGING_BINDIR_NATIVE}/foo:${STAGING_BINDIR_NATIVE}/bar:" + to <filename>PATH</filename>: + <literallayout class='monospaced'> + EXTRANATIVEPATH = "foo bar" + </literallayout> + </para> + </glossdef> + </glossentry> + <glossentry id='var-EXTRA_OECMAKE'><glossterm>EXTRA_OECMAKE</glossterm> <info> EXTRA_OECMAKE[doc] = "Additional cmake options." @@ -3913,6 +4100,10 @@ <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Additional <filename>configure</filename> script options. + See + <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link> + for additional information on passing configure script + options. </para> </glossdef> </glossentry> @@ -3932,6 +4123,15 @@ "", you need to set the variable to specify any required GNU options. </para> + + <para> + <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link> + and + <link linkend='var-PARALLEL_MAKEINST'><filename>PARALLEL_MAKEINST</filename></link> + also make use of + <filename>EXTRA_OEMAKE</filename> to pass the required + flags. + </para> </glossdef> </glossentry> @@ -4061,12 +4261,16 @@ <glossentry id='var-FILES'><glossterm>FILES</glossterm> <info> - FILES[doc] = "The list of directories or files that are placed in packages." + FILES[doc] = "The list of directories or files that are placed in a package." </info> <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - The list of directories or files that are placed in packages. + The list of files and directories that are placed in a + package. + The + <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link> + variable lists the packages generated by a recipe. </para> <para> @@ -4077,7 +4281,7 @@ resulting package. Here is an example: <literallayout class='monospaced'> - FILES_${PN} += "${bindir}/mydir1/ ${bindir}/mydir2/myfile" + FILES_${PN} += "${bindir}/mydir1 ${bindir}/mydir2/myfile" </literallayout> </para> @@ -4092,6 +4296,8 @@ You can find a list of these variables at the top of the <filename>meta/conf/bitbake.conf</filename> file in the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. + You will also find the default values of the various + <filename>FILES_*</filename> variables in this file. </note> <para> @@ -4106,7 +4312,6 @@ variable for information on how to identify these files to the PMS. </para> - </glossdef> </glossentry> @@ -4361,6 +4566,25 @@ </glossdef> </glossentry> + <glossentry id='var-FORCE_RO_REMOVE'><glossterm>FORCE_RO_REMOVE</glossterm> + <info> + FORCE_RO_REMOVE[doc] = "Forces the removal of the packages listed in ROOTFS_RO_UNNEEDED during the generation of the root filesystem." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Forces the removal of the packages listed in + <filename>ROOTFS_RO_UNNEEDED</filename> during the + generation of the root filesystem. + </para> + + <para> + Set the variable to "1" to force the removal of these + packages. + </para> + </glossdef> + </glossentry> + <glossentry id='var-FULL_OPTIMIZATION'><glossterm>FULL_OPTIMIZATION</glossterm> <info> FULL_OPTIMIZATION[doc]= "The options to pass in TARGET_CFLAGS and CFLAGS when compiling an optimized system. This variable defaults to '-fexpensive-optimizations -fomit-frame-pointer -frename-registers -O2'." @@ -4570,92 +4794,6 @@ </glossdef> </glossentry> - <glossentry id='var-GUMMIBOOT_CFG'><glossterm>GUMMIBOOT_CFG</glossterm> - <info> - GUMMIBOOT_CFG[doc] = "When EFI_PROVIDER is set to "gummiboot", the GUMMIBOOT_CFG variable specifies the configuration file that should be used." - </info> - <glossdef> - <para role="glossdeffirst"> -<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - When - <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link> - is set to "gummiboot", the - <filename>GUMMIBOOT_CFG</filename> variable specifies the - configuration file that should be used. - By default, the - <link linkend='ref-classes-gummiboot'><filename>gummiboot</filename></link> - class sets the <filename>GUMMIBOOT_CFG</filename> as - follows: - <literallayout class='monospaced'> - GUMMIBOOT_CFG ?= "${<link linkend='var-S'>S</link>}/loader.conf" - </literallayout> - </para> - - <para> - For information on Gummiboot, see the - <ulink url='http://freedesktop.org/wiki/Software/gummiboot/'>Gummiboot documentation</ulink>. - </para> - </glossdef> - </glossentry> - - <glossentry id='var-GUMMIBOOT_ENTRIES'><glossterm>GUMMIBOOT_ENTRIES</glossterm> - <info> - GUMMIBOOT_ENTRIES[doc] = "When EFI_PROVIDER is set to "gummiboot", the GUMMIBOOT_ENTRIES variable specifies a list of entry files (*.conf) to be installed containing one boot entry per file." - </info> - <glossdef> - <para role="glossdeffirst"> -<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - When - <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link> - is set to "gummiboot", the - <filename>GUMMIBOOT_ENTRIES</filename> variable specifies - a list of entry files - (<filename>*.conf</filename>) to be installed - containing one boot entry per file. - By default, the - <link linkend='ref-classes-gummiboot'><filename>gummiboot</filename></link> - class sets the <filename>GUMMIBOOT_ENTRIES</filename> as - follows: - <literallayout class='monospaced'> - GUMMIBOOT_ENTRIES ?= "" - </literallayout> - </para> - - <para> - For information on Gummiboot, see the - <ulink url='http://freedesktop.org/wiki/Software/gummiboot/'>Gummiboot documentation</ulink>. - </para> - </glossdef> - </glossentry> - - <glossentry id='var-GUMMIBOOT_TIMEOUT'><glossterm>GUMMIBOOT_TIMEOUT</glossterm> - <info> - GUMMIBOOT_TIMEOUT[doc] = "When EFI_PROVIDER is set to "gummiboot", the GUMMIBOOT_TIMEOUT variable specifies the boot menu timeout in seconds." - </info> - <glossdef> - <para role="glossdeffirst"> -<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - When - <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link> - is set to "gummiboot", the - <filename>GUMMIBOOT_TIMEOUT</filename> variable specifies - the boot menu timeout in seconds. - By default, the - <link linkend='ref-classes-gummiboot'><filename>gummiboot</filename></link> - class sets the <filename>GUMMIBOOT_TIMEOUT</filename> as - follows: - <literallayout class='monospaced'> - GUMMIBOOT_TIMEOUT ?= "10" - </literallayout> - </para> - - <para> - For information on Gummiboot, see the - <ulink url='http://freedesktop.org/wiki/Software/gummiboot/'>Gummiboot documentation</ulink>. - </para> - </glossdef> - </glossentry> - </glossdiv> <glossdiv id='var-glossary-h'><title>H</title> @@ -5940,7 +6078,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossentry id='var-INHIBIT_PACKAGE_DEBUG_SPLIT'><glossterm>INHIBIT_PACKAGE_DEBUG_SPLIT</glossterm> <info> - INHIBIT_PACKAGE_STRIP[doc] = "If set to "1", causes the build to not strip binaries in resulting packages." + INHIBIT_PACKAGE_DEBUG_SPLIT[doc] = "If set to "1", prevents the OpenEmbedded build system from splitting out debug information during packaging" </info> <glossdef> <para role="glossdeffirst"> @@ -5976,7 +6114,19 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - If set to "1", causes the build to not strip binaries in resulting packages. + If set to "1", causes the build to not strip binaries in + resulting packages and prevents the + <filename>-dbg</filename> package from containing the + source files. + </para> + + <para> + By default, the OpenEmbedded build system strips + binaries and puts the debugging symbols into + <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}-dbg</filename>. + Consequently, you should not set + <filename>INHIBIT_PACKAGE_STRIP</filename> when you plan + to debug in general. </para> </glossdef> </glossentry> @@ -5994,72 +6144,108 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link> variable. </para> + + <para> + The default value of this variable, which is set in the + <filename>meta/conf/bitbake.conf</filename> configuration + file in the + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>, + is "cpio.gz". + The Linux kernel's initramfs mechanism, as opposed to the + initial RAM disk + <ulink url='https://en.wikipedia.org/wiki/Initrd'>initrd</ulink> + mechanism, expects an optionally compressed cpio + archive. + </para> </glossdef> </glossentry> <glossentry id='var-INITRAMFS_IMAGE'><glossterm>INITRAMFS_IMAGE</glossterm> <info> - INITRAMFS_IMAGE[doc] = "Causes the OpenEmbedded build system to build an additional recipe as a dependency to your root filesystem recipe (e.g. core-image-sato)." + INITRAMFS_IMAGE[doc] = "Specifies the PROVIDES name of an image recipe that is used to build an initial RAM disk (initramfs) image." </info> <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - Causes the OpenEmbedded build system to build an additional - recipe as a dependency to your root filesystem recipe - (e.g. <filename>core-image-sato</filename>). - The additional recipe is used to create an initial RAM disk - (initramfs) that might be needed during the initial boot of - the target system to accomplish such things as loading - kernel modules prior to mounting the root file system. + Specifies the + <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link> + name of an image recipe that is used to build an initial + RAM disk (initramfs) image. + An initramfs provides a temporary root filesystem used for + early system initialization (e.g. loading of modules + needed to locate and mount the "real" root filesystem). + The specified recipe is added as a dependency of the root + filesystem recipe (e.g. + <filename>core-image-sato</filename>). + See the <filename>meta/recipes-core/images/core-image-minimal-initramfs.bb</filename> + recipe in the + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> + for an example initramfs recipe. + To select this recipe to provide the initramfs, + set <filename>INITRAMFS_IMAGE</filename> to + "core-image-minimal-initramfs". + <note> + The initramfs image recipe should set + <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link> + to + <link linkend='var-INITRAMFS_FSTYPES'><filename>INITRAMFS_FSTYPES</filename></link>. + </note> </para> <para> - When you set the variable, specify the name of the - initramfs you want created. - The following example, which is set in the - <filename>local.conf</filename> configuration file, causes - a separate recipe to be created that results in an - initramfs image named - <filename>core-image-sato-initramfs.bb</filename> to be - created: - <literallayout class='monospaced'> - INITRAMFS_IMAGE = "core-image-minimal-initramfs" - </literallayout> - By default, the + You can also find more information by referencing the + <filename>meta/poky/conf/local.conf.sample.extended</filename> + configuration file in the + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>, + the + <link linkend='ref-classes-image'><filename>image</filename></link> + class, and the <link linkend='ref-classes-kernel'><filename>kernel</filename></link> - class sets this variable to a null string as follows: - <literallayout class='monospaced'> - INITRAMFS_IMAGE = "" - </literallayout> + class to see how to use the + <filename>INITRAMFS_IMAGE</filename> variable. </para> <para> - See the - <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-poky/conf/local.conf.sample.extended'><filename>local.conf.sample.extended</filename></ulink> - file for additional information. - You can also reference the - <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/classes/kernel.bbclass'><filename>kernel.bbclass</filename></ulink> - file to see how the variable is used. + If <filename>INITRAMFS_IMAGE</filename> is empty, which is + the default, then no initramfs is built. + </para> + + <para> + Finally, for more information you can also see the + <link linkend='var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></link> + variable, which allows the generated image to be bundled + inside the kernel image. </para> </glossdef> </glossentry> <glossentry id='var-INITRAMFS_IMAGE_BUNDLE'><glossterm>INITRAMFS_IMAGE_BUNDLE</glossterm> <info> - INITRAMFS_IMAGE_BUNDLE[doc] = "Controls whether or not the image recipe specified by INITRAMFS_IMAGE is run through an extra pass during kernel compilation in order to build a single binary that contains both the kernel image and the initial RAM disk (initramfs)." + INITRAMFS_IMAGE_BUNDLE[doc] = "Controls whether or not the image recipe specified by INITRAMFS_IMAGE is run through an extra pass (do_bundle_initramfs) during kernel compilation in order to build a single binary that contains both the kernel image and the initial RAM disk (initramfs)." </info> <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Controls whether or not the image recipe specified by <link linkend='var-INITRAMFS_IMAGE'><filename>INITRAMFS_IMAGE</filename></link> - is run through an extra pass during kernel compilation - in order to build a single binary that contains both the - kernel image and the initial RAM disk (initramfs). - Using an extra compilation pass ensures that when a kernel - attempts to use an initramfs, it does not encounter - circular dependencies should the initramfs include kernel - modules. + is run through an extra pass + (<link linkend='ref-tasks-bundle_initramfs'><filename>do_bundle_initramfs</filename></link>) + during kernel compilation in order to build a single binary + that contains both the kernel image and the initial RAM disk + (initramfs). + This makes use of the + <link linkend='var-CONFIG_INITRAMFS_SOURCE'><filename>CONFIG_INITRAMFS_SOURCE</filename></link> + kernel feature. + <note> + Using an extra compilation pass to bundle the initramfs + avoids a circular dependency between the kernel recipe and + the initramfs recipe should the initramfs include kernel + modules. + Should that be the case, the initramfs recipe depends on + the kernel for the kernel modules, and the kernel depends + on the initramfs recipe since the initramfs is bundled + inside the kernel image. + </note> </para> <para> @@ -6070,9 +6256,11 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </para> <para> - Setting the variable to "1" in a configuration file causes - the OpenEmbedded build system to make the extra pass during - kernel compilation: + Setting the variable to "1" in a configuration file causes the + OpenEmbedded build system to generate a kernel image with the + initramfs specified in + <link linkend='var-INITRAMFS_IMAGE'><filename>INITRAMFS_IMAGE</filename></link> + bundled within: <literallayout class='monospaced'> INITRAMFS_IMAGE_BUNDLE = "1" </literallayout> @@ -6080,7 +6268,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <link linkend='ref-classes-kernel'><filename>kernel</filename></link> class sets this variable to a null string as follows: <literallayout class='monospaced'> - INITRAMFS_IMAGE_BUNDLE = "" + INITRAMFS_IMAGE_BUNDLE ?= "" </literallayout> <note> You must set the @@ -7727,36 +7915,41 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossentry id='var-MACHINEOVERRIDES'><glossterm>MACHINEOVERRIDES</glossterm> <info> - MACHINEOVERRIDES[doc] = "Lists overrides specific to the current machine. By default, this list includes the value of MACHINE." + MACHINEOVERRIDES[doc] = "A colon-separated list of overrides that apply to the current machine." </info> <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - Lists overrides specific to the current machine. - By default, this list includes the value - of <filename><link linkend='var-MACHINE'>MACHINE</link></filename>. - You can extend the list to apply variable overrides for - classes of machines. - For example, all QEMU emulated machines (e.g. qemuarm, - qemux86, and so forth) include a common file named - <filename>meta/conf/machine/include/qemu.inc</filename> - that prepends <filename>MACHINEOVERRIDES</filename> with - the following variable override: - <literallayout class='monospaced'> - MACHINEOVERRIDES =. "qemuall:" - </literallayout> + A colon-separated list of overrides that apply to the + current machine. + By default, this list includes the value of + <link linkend='var-MACHINE'><filename>MACHINE</filename></link>. </para> <para> - Applying an override like <filename>qemuall</filename> - affects all QEMU emulated machines elsewhere. - Here is an example from the - <filename>connman-conf</filename> recipe: + You can extend <filename>MACHINEOVERRIDES</filename> + to add extra overrides that should apply to a machine. + For example, all machines emulated in QEMU (e.g. + <filename>qemuarm</filename>, <filename>qemux86</filename>, + and so forth) include a file named + <filename>meta/conf/machine/include/qemu.inc</filename> + that prepends the following override to + <filename>MACHINEOVERRIDES</filename>: + <literallayout class='monospaced'> + MACHINEOVERRIDES =. "qemuall:" + </literallayout> + This override allows variables to be overriden for all + machines emulated in QEMU, like in the following example + from the <filename>connman-conf</filename> recipe: <literallayout class='monospaced'> - SRC_URI_append_qemuall = "file://wired.config \ - file://wired-setup \ - " + SRC_URI_append_qemuall = "file://wired.config \ + file://wired-setup \ + " </literallayout> + The underlying mechanism behind + <filename>MACHINEOVERRIDES</filename> is simply that it is + included in the default value of + <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>. </para> </glossdef> </glossentry> @@ -7817,6 +8010,39 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <link linkend='var-BPN'><filename>BPN</filename></link> variable). <filename>MLPREFIX</filename> gets set when a prefix has been added to <filename>PN</filename>. + <note> + The "ML" in <filename>MLPREFIX</filename> stands for + "MultiLib". + This representation is historical and comes from + a time when <filename>nativesdk</filename> was a suffix + rather than a prefix on the recipe name. + When <filename>nativesdk</filename> was turned into a + prefix, it made sense to set + <filename>MLPREFIX</filename> for it as well. + </note> + </para> + + <para> + To help understand when <filename>MLPREFIX</filename> + might be needed, consider when + <link linkend='var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></link> + is used to provide a <filename>nativesdk</filename> version + of a recipe in addition to the target version. + If that recipe declares build-time dependencies on tasks in + other recipes by using + <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>, + then a dependency on "foo" will automatically get rewritten + to a dependency on "nativesdk-foo". + However, dependencies like the following will not get + rewritten automatically: + <literallayout class='monospaced'> + do_foo[depends] += "<replaceable>recipe</replaceable>:do_foo" + </literallayout> + If you want such a dependency to also get transformed, + you can do the following: + <literallayout class='monospaced'> + do_foo[depends] += "${MLPREFIX}<replaceable>recipe</replaceable>:do_foo" + </literallayout> </para> </glossdef> </glossentry> @@ -7956,6 +8182,31 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> + <glossentry id='var-MULTIMACH_HOST_SYS'><glossterm>MULTIMACH_HOST_SYS</glossterm> + <info> + MULTIMACH_HOST_SYS[doc] = "Separates files for different machines such that you can build for multiple host machines using the same output directories." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Serves the same purpose as + <link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>, + but for the "HOST" system, in situations that involve a + "HOST" and a "TARGET" system. + See the + <link linkend='var-STAGING_DIR_TARGET'><filename>STAGING_DIR_TARGET</filename></link> + variable for more information. + </para> + + <para> + The default value of this variable is: + <literallayout class='monospaced'> + ${PACKAGE_ARCH}${HOST_VENDOR}-${HOST_OS} + </literallayout> + </para> + </glossdef> + </glossentry> + <glossentry id='var-MULTIMACH_TARGET_SYS'><glossterm>MULTIMACH_TARGET_SYS</glossterm> <info> MULTIMACH_TARGET_SYS[doc] = "Separates files for different machines such that you can build for multiple target machines using the same output directories." @@ -7963,10 +8214,33 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - Separates files for different machines such that you can build - for multiple target machines using the same output directories. - See the <link linkend='var-STAMP'><filename>STAMP</filename></link> variable - for an example. + Uniquely identifies the type of the target system for + which packages are being built. + This variable allows output for different types of target + systems to be put into different subdirectories of the same + output directory. + </para> + + <para> + The default value of this variable is: + <literallayout class='monospaced'> + ${PACKAGE_ARCH}${TARGET_VENDOR}-${TARGET_OS} + </literallayout> + Some classes (e.g. + <link linkend='ref-classes-cross-canadian'><filename>cross-canadian</filename></link>) + modify the <filename>MULTIMACH_TARGET_SYS</filename> value. + </para> + + <para> + See the + <link linkend='var-STAMP'><filename>STAMP</filename></link> + variable for an example. + <link linkend='var-MULTIMACH_HOST_SYS'><filename>MULTIMACH_HOST_SYS</filename></link> + is the corresponding variable for the host system in + situations that involve a "HOST" and a "TARGET" system. + See the + <link linkend='var-STAGING_DIR_TARGET'><filename>STAGING_DIR_TARGET</filename></link> + variable for more information. </para> </glossdef> </glossentry> @@ -8304,18 +8578,60 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossentry id='var-OVERRIDES'><glossterm>OVERRIDES</glossterm> <info> - OVERRIDES[doc] = "BitBake uses OVERRIDES to control what variables are overridden after BitBake parses recipes and configuration files." + OVERRIDES[doc] = "A colon-separated list of overrides that currently apply." </info> <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - BitBake uses <filename>OVERRIDES</filename> to control - what variables are overridden after BitBake parses - recipes and configuration files. - You can find more information on how overrides are handled - in the + A colon-separated list of overrides that currently apply. + Overrides are a BitBake mechanism that allows variables to + be selectively overridden at the end of parsing. + The set of overrides in <filename>OVERRIDES</filename> + represents the "state" during building, which includes + the current recipe being built, the machine for which + it is being built, and so forth. + </para> + + <para> + As an example, if the string "an-override" appears as an + element in the colon-separated list in + <filename>OVERRIDES</filename>, then the following + assignment will override <filename>FOO</filename> with the + value "overridden" at the end of parsing: + <literallayout class='monospaced'> + FOO_an-override = "overridden" + </literallayout> + See the "<ulink url='&YOCTO_DOCS_BB_URL;#conditional-syntax-overrides'>Conditional Syntax (Overrides)</ulink>" - section of the BitBake User Manual. + section in the BitBake User Manual for more information on + the overrides mechanism. + </para> + + <para> + The default value of <filename>OVERRIDES</filename> + includes the values of the + <link linkend='var-CLASSOVERRIDE'><filename>CLASSOVERRIDE</filename></link>, + <link linkend='var-MACHINEOVERRIDES'><filename>MACHINEOVERRIDES</filename></link>, + and + <link linkend='var-DISTROOVERRIDES'><filename>DISTROOVERRIDES</filename></link> + variables. + Another important override included by default is + <filename>pn-${PN}</filename>. + This override allows variables to be set for a single + recipe within configuration (<filename>.conf</filename>) + files. + Here is an example: + <literallayout class='monospaced'> + FOO_pn-myrecipe = "myrecipe-specific value" + </literallayout> + <note><title>Tip</title> + An easy way to see what overrides apply is to search for + <filename>OVERRIDES</filename> in the output of the + <filename>bitbake -e</filename> command. + See the + "<link linkend='usingpoky-debugging-viewing-variable-values'>Viewing Variable Values</link>" + section for more information. + </note> </para> </glossdef> </glossentry> @@ -8863,10 +9179,13 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <listitem><para>Extra arguments that should be added to the configure script argument list - (<link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>) + (<link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link> + or + <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link>) if the feature is enabled.</para></listitem> <listitem><para>Extra arguments that should be added to <filename>EXTRA_OECONF</filename> + or <filename>PACKAGECONFIG_CONFARGS</filename> if the feature is disabled. </para></listitem> <listitem><para>Additional build dependencies @@ -8950,6 +9269,50 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> + <glossentry id='var-PACKAGECONFIG_CONFARGS'><glossterm>PACKAGECONFIG_CONFARGS</glossterm> + <info> + PACKAGECONFIG_CONFARGS[doc] = "A space-separated list of configuration options generated from PACKAGECONFIG." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + A space-separated list of configuration options generated + from the + <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link> + setting. + This list of options helps other classes and + recipes take advantage of the + <filename>PACKAGECONFIG</filename> mechanism without + having to include options from + <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>. + </para> + + <para> + To illustrate how to use + <filename>PACKAGECONFIG_CONFARGS</filename>, consider the + following example: + <literallayout class='monospaced'> + PACKAGECONFIG_CONFARGS = " \ + -prefix ${prefix} \ + -sysroot ${STAGING_DIR_NATIVE} \ + -no-gcc-sysroot + " + </literallayout> + In the previous example, + <filename>PACKAGECONFIG_CONFARGS</filename> is set with + three configuration options that can be passed using the + <filename>PACKAGECONFIG</filename> mechanism, thus + avoiding having to use <filename>EXTRA_OECONF</filename>. + </para> + + <para> + For additional information, see the + <link linkend='var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></link> + variable. + </para> + </glossdef> + </glossentry> + <glossentry id='var-PACKAGEGROUP_DISABLE_COMPLEMENTARY'><glossterm>PACKAGEGROUP_DISABLE_COMPLEMENTARY</glossterm> <info> PACKAGEGROUP_DISABLE_COMPLEMENTARY[doc] = "Prevents automatic creation of the normal complementary packages such as -dev and -dbg in a packagegroup recipe." @@ -8984,6 +9347,31 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN} </literallayout> </para> + + <para> + During packaging, the + <link linkend='ref-tasks-package'><filename>do_package</filename></link> + task goes through <filename>PACKAGES</filename> and uses + the + <link linkend='var-FILES'><filename>FILES</filename></link> + variable corresponding to each package to assign files to + the package. + If a file matches the <filename>FILES</filename> variable + for more than one package in <filename>PACKAGES</filename>, + it will be assigned to the earliest (leftmost) package. + </para> + + <para> + Packages in the variable's list that are empty (i.e. where + none of the patterns in + <filename>FILES_</filename><replaceable>pkg</replaceable> + match any files installed by the + <link linkend='ref-tasks-install'><filename>do_install</filename></link> + task) are not generated, unless generation is forced through + the + <link linkend='var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></link> + variable. + </para> </glossdef> </glossentry> @@ -9068,6 +9456,14 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" where <replaceable>x</replaceable> represents the maximum number of parallel threads <filename>make</filename> can run. + <note><title>Caution</title> + In order for <filename>PARALLEL_MAKE</filename> to be + effective, <filename>make</filename> must be called + with + <filename>${</filename><link linkend='var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></link><filename>}</filename>. + An easy way to ensure this is to use the + <filename>oe_runmake</filename> function. + </note> </para> <para> @@ -9114,16 +9510,24 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" task in order to specify parallel installation. This variable defaults to the value of <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>. - <note> - If the software being built experiences dependency - issues during the + <note><title>Notes and Cautions</title> + <para>In order for <filename>PARALLEL_MAKEINST</filename> + to be + effective, <filename>make</filename> must be called + with + <filename>${</filename><link linkend='var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></link><filename>}</filename>. + An easy way to ensure this is to use the + <filename>oe_runmake</filename> function.</para> + + <para>If the software being built experiences + dependency issues during the <filename>do_install</filename> task that result in race conditions, you can clear the <filename>PARALLEL_MAKEINST</filename> variable within the recipe as a workaround. For information on addressing race conditions, see the "<ulink url='&YOCTO_DOCS_DEV_URL;#debugging-parallel-make-races'>Debugging Parallel Make Races</ulink>" - section in the Yocto Project Development Manual. + section in the Yocto Project Development Manual.</para> </note> </para> </glossdef> @@ -9201,6 +9605,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" versioning scheme changes in some backwards incompatible way. </para> + + <para> + <filename>PE</filename> is the default value of the + <link linkend='var-PKGE'><filename>PKGE</filename></link> + variable. + </para> </glossdef> </glossentry> @@ -9316,14 +9726,16 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link> task packages data for each recipe and installs it into this temporary, shared area. - This directory defaults to the following: + This directory defaults to the following, which you should + not change: <literallayout class='monospaced'> ${STAGING_DIR_HOST}/pkgdata </literallayout> - </para> - - <para> - Do not change this default. + For examples of how this data is used, see the + "<link linkend='automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</link>" + section and the + "<link linkend='viewing-package-information-with-oe-pkgdata-util'>Viewing Package Information with <filename>oe-pkgdata-util</filename></link>" + section. </para> </glossdef> </glossentry> @@ -9354,45 +9766,41 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossentry id='var-PKGDESTWORK'><glossterm>PKGDESTWORK</glossterm> <info> - PKGDESTWORK[doc] = "Points to a temporary work area used by the do_package task to write output from the do_packagedata task." + PKGDESTWORK[doc] = "Points to a temporary work area where the do_package task saves package metadata." </info> <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - Points to a temporary work area used by the + Points to a temporary work area where the <link linkend='ref-tasks-package'><filename>do_package</filename></link> - task to write output from the - <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link> - task. + task saves package metadata. The <filename>PKGDESTWORK</filename> location defaults to the following: <literallayout class='monospaced'> ${WORKDIR}/pkgdata </literallayout> + Do not change this default. </para> <para> - The <filename>do_packagedata</filename> task then packages - the data in the temporary work area and installs it into a - shared directory pointed to by - <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>. - </para> - - <para> - Do not change this default. + The + <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link> + task copies the package metadata from + <filename>PKGDESTWORK</filename> to + <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link> + to make it available globally. </para> </glossdef> </glossentry> <glossentry id='var-PKGE'><glossterm>PKGE</glossterm> <info> - PKGE[doc] = "The epoch of the output package built by the OpenEmbedded build system." + PKGE[doc] = "The epoch of the package(s) built by the recipe." </info> <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - The epoch of the output package built by the - OpenEmbedded build system. + The epoch of the package(s) built by the recipe. By default, <filename>PKGE</filename> is set to <link linkend='var-PE'><filename>PE</filename></link>. </para> @@ -9401,13 +9809,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossentry id='var-PKGR'><glossterm>PKGR</glossterm> <info> - PKGR[doc] = "The revision of the output package built by the OpenEmbedded build system." + PKGR[doc] = "The revision of the package(s) built by the recipe." </info> <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - The revision of the output package built by the - OpenEmbedded build system. + The revision of the package(s) built by the recipe. By default, <filename>PKGR</filename> is set to <link linkend='var-PR'><filename>PR</filename></link>. </para> @@ -9416,13 +9823,13 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossentry id='var-PKGV'><glossterm>PKGV</glossterm> <info> - PKGV[doc] = "The version of the output package built by the OpenEmbedded build system." + PKGV[doc] = "The version of the package(s) built by the recipe." </info> <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - The version of the output package built by the - OpenEmbedded build system. + The version of the package(s) built by the + recipe. By default, <filename>PKGV</filename> is set to <link linkend='var-PV'><filename>PV</filename></link>. </para> @@ -9559,8 +9966,50 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - The revision of the recipe. - The default value for this variable is "r0". + The revision of the recipe. The default value for this + variable is "r0". + Subsequent revisions of the recipe conventionally have the + values "r1", "r2", and so forth. + When + <link linkend='var-PV'><filename>PV</filename></link> + increases, <filename>PR</filename> is conventionally reset + to "r0". + <note> + The OpenEmbedded build system does not need the aid of + <filename>PR</filename> to know when to rebuild a + recipe. + The build system uses the task + <ulink url='&YOCTO_DOCS_BB_URL;#checksums'>input checksums</ulink> + along with the + <link linkend='structure-build-tmp-stamps'>stamp</link> + and + <link linkend='shared-state-cache'>shared state cache</link> + mechanisms. + </note> + The <filename>PR</filename> variable primarily becomes + significant when a package manager dynamically installs + packages on an already built image. + In this case, <filename>PR</filename>, which is the default + value of + <link linkend='var-PKGR'><filename>PKGR</filename></link>, + helps the package manager distinguish which package is the + most recent one in cases where many packages have the same + <filename>PV</filename> (i.e. <filename>PKGV</filename>). + A component having many packages with the same + <filename>PV</filename> usually means that the packages all + install the same upstream version, but with later + (<filename>PR</filename>) version packages including + packaging fixes. + <note> + <filename>PR</filename> does not need to be increased + for changes that do not change the package contents or + metadata. + </note> + Because manually managing <filename>PR</filename> can be + cumbersome and error-prone, an automated solution exists. + See the + "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service'>Working With a PR Service</ulink>" + section for more information. </para> </glossdef> </glossentry> @@ -9619,9 +10068,34 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" numbers that could potentially change. Here are two examples: <literallayout class='monospaced'> - PREFERRED_VERSION_python = "2.7.3" + PREFERRED_VERSION_python = "3.4.0" PREFERRED_VERSION_linux-yocto = "3.19%" </literallayout> + <note> + The specified version is matched against + <link linkend='var-PV'><filename>PV</filename></link>, + which does not necessarily match the version part of + the recipe's filename. + For example, consider two recipes + <filename>foo_1.2.bb</filename> and + <filename>foo_git.bb</filename> where + <filename>foo_git.bb</filename> contains the following + assignment: + <literallayout class='monospaced'> + PV = "1.1+git${SRCPV}" + </literallayout> + In this case, the correct way to select + <filename>foo_git.bb</filename> is by using an + assignment such as the following: + <literallayout class='monospaced'> + PREFERRED_VERSION_foo = "1.1+git%" + </literallayout> + Compare that previous example against the following + incorrect example, which does not work: + <literallayout class='monospaced'> + PREFERRED_VERSION_foo = "git" + </literallayout> + </note> Sometimes the <filename>PREFERRED_VERSION</filename> variable can be set by configuration files in a way that is hard to change. @@ -9639,6 +10113,13 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <literallayout class='monospaced'> PREFERRED_VERSION_linux-yocto_forcevariable = "3.4%" </literallayout> + <note> + The <filename>_forcevariable</filename> override is + not handled specially. + This override only works because the default value of + <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link> + includes "forcevariable". + </note> </para> </glossdef> </glossentry> @@ -9751,6 +10232,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" libplds4.so" </literallayout> </para> + + <para> + For more information, see the + "<link linkend='automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</link>" + section. + </para> </glossdef> </glossentry> @@ -9784,6 +10271,51 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" The <filename>PROVIDES</filename> statement results in the "libav" recipe also being known as "libpostproc". </para> + + <para> + In addition to providing recipes under alternate names, + the <filename>PROVIDES</filename> mechanism is also used + to implement virtual targets. + A virtual target is a name that corresponds to some + particular functionality (e.g. a Linux kernel). + Recipes that provide the functionality in question list the + virtual target in <filename>PROVIDES</filename>. + Recipes that depend on the functionality in question can + include the virtual target in + <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link> + to leave the choice of provider open. + </para> + + <para> + Conventionally, virtual targets have names on the form + "virtual/function" (e.g. "virtual/kernel"). + The slash is simply part of the name and has no + syntactical significance. + </para> + + <para> + The + <link linkend='var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></link> + variable is used to select which particular recipe + provides a virtual target. + <note> + <para>A corresponding mechanism for virtual runtime + dependencies (packages) exists. + However, the mechanism does not depend on any special + functionality beyond ordinary variable assignments. + For example, + <filename>VIRTUAL-RUNTIME_dev_manager</filename> + refers to the package of the component that manages + the <filename>/dev</filename> directory.</para> + + <para>Setting the "preferred provider" for runtime + dependencies is as simple as using the following + assignment in a configuration file:</para> + <literallayout class='monospaced'> + VIRTUAL-RUNTIME_dev_manager = "udev" + </literallayout> + </note> + </para> </glossdef> </glossentry> @@ -9846,12 +10378,19 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" The version of the recipe. The version is normally extracted from the recipe filename. For example, if the recipe is named - <filename>expat_2.0.1.bb</filename>, then the default value of <filename>PV</filename> - will be "2.0.1". + <filename>expat_2.0.1.bb</filename>, then the default value + of <filename>PV</filename> will be "2.0.1". <filename>PV</filename> is generally not overridden within - a recipe unless it is building an unstable (i.e. development) version from a source code repository + a recipe unless it is building an unstable (i.e. + development) version from a source code repository (e.g. Git or Subversion). </para> + + <para> + <filename>PV</filename> is the default value of the + <link linkend='var-PKGV'><filename>PKGV</filename></link> + variable. + </para> </glossdef> </glossentry> @@ -9993,40 +10532,59 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm> <info> - RDEPENDS[doc] = "Lists a package's runtime dependencies (i.e. other packages) that must be installed for the package to be built. They must be the names of other packages as listed in the PACKAGES variable, not recipe names (PN)." + RDEPENDS[doc] = "Lists runtime dependencies of a package." </info> <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - Lists a package's runtime dependencies (i.e. other packages) - that must be installed in order for the built package to run - correctly. - If a package in this list cannot be found during the build, - you will get a build error. + Lists runtime dependencies of a package. + These dependencies are other packages that must be + installed in order for the package to function correctly. + As an example, the following assignment declares that the + package <filename>foo</filename> needs the packages + <filename>bar</filename> and <filename>baz</filename> to + be installed: + <literallayout class='monospaced'> + RDEPENDS_foo = "bar baz" + </literallayout> + The most common types of package runtime dependencies are + automatically detected and added. + Therefore, most recipes do not need to set + <filename>RDEPENDS</filename>. + For more information, see the + "<link linkend='automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</link>" + section. </para> <para> - When you use the <filename>RDEPENDS</filename> variable - in a recipe, you are essentially stating that the recipe's + The practical effect of the above + <filename>RDEPENDS</filename> assignment is that + <filename>bar</filename> and <filename>baz</filename> + will be declared as dependencies inside the package + <filename>foo</filename> when it is written out by one of + the + <link linkend='ref-tasks-package_write_deb'><filename>do_package_write_*</filename></link> + tasks. + Exactly how this is done depends on which package format + is used, which is determined by + <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>. + When the corresponding package manager installs the + package, it will know to also install the packages on + which it depends. + </para> + + <para> + To ensure that the packages <filename>bar</filename> and + <filename>baz</filename> get built, the previous + <filename>RDEPENDS</filename> assignment also causes a task + dependency to be added. + This dependency is from the recipe's <link linkend='ref-tasks-build'><filename>do_build</filename></link> - task depends on the existence of a specific package. - Consider this simple example for two recipes named "a" and - "b" that produce similarly named IPK packages. - In this example, the <filename>RDEPENDS</filename> - statement appears in the "a" recipe: - <literallayout class='monospaced'> - RDEPENDS_${PN} = "b" - </literallayout> - Here, the dependency is such that the - <filename>do_build</filename> task for recipe "a" depends - on the - <link linkend='ref-tasks-package_write_ipk'><filename>do_package_write_ipk</filename></link> - task of recipe "b". - This means the package file for "b" must be available when - the output for recipe "a" has been completely built. - More importantly, package "a" will be marked as depending - on package "b" in a manner that is understood by the - package manager. + (not to be confused with + <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>) + task to the <filename>do_package_write_*</filename> + task of the recipes that build <filename>bar</filename> and + <filename>baz</filename>. </para> <para> @@ -10046,7 +10604,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <para> Because the <filename>RDEPENDS</filename> variable applies to packages being built, you should always use the variable - in a form with an attached package name. + in a form with an attached package name (remember that a + single recipe can build multiple packages). For example, suppose you are building a development package that depends on the <filename>perl</filename> package. In this case, you would use the following @@ -10059,38 +10618,33 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" Thus, the <filename>RDEPENDS</filename> variable has the <filename>${PN}-dev</filename> package name as part of the variable. + <note> + <title>Caution</title> + <filename>RDEPENDS_${PN}-dev</filename> includes + <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename> + by default. + This default is set in the BitBake configuration file + (<filename>meta/conf/bitbake.conf</filename>). + Be careful not to accidentally remove + <filename>${PN}</filename> when modifying + <filename>RDEPENDS_${PN}-dev</filename>. + Use the "+=" operator rather than the "=" operator. + </note> </para> <para> - The package name you attach to the - <filename>RDEPENDS</filename> variable must appear - as it would in the <filename>PACKAGES</filename> - namespace before any renaming of the output package by - classes like - <link linkend='ref-classes-debian'><filename>debian</filename></link>. - </para> - - <para> - In many cases you do not need to explicitly add - runtime dependencies using - <filename>RDEPENDS</filename> since some automatic - handling occurs: - <itemizedlist> - <listitem><para><emphasis><filename>shlibdeps</filename></emphasis>: If - a runtime package contains a shared library - (<filename>.so</filename>), the build - processes the library in order to determine other - libraries to which it is dynamically linked. - The build process adds these libraries to - <filename>RDEPENDS</filename> when creating the runtime - package.</para></listitem> - <listitem><para><emphasis><filename>pcdeps</filename></emphasis>: If - the package ships a <filename>pkg-config</filename> - information file, the build process uses this file - to add items to the <filename>RDEPENDS</filename> - variable to create the runtime packages. - </para></listitem> - </itemizedlist> + The package names you use with + <filename>RDEPENDS</filename> must appear as they would in + the <filename>PACKAGES</filename> variable. + The + <link linkend='var-PKG'><filename>PKG</filename></link> + variable allows a different name to be used for + the final package (e.g. the + <link linkend='ref-classes-debian'><filename>debian</filename></link> + class uses this to rename packages), but this final package + name cannot be used with <filename>RDEPENDS</filename>, + which makes sense as <filename>RDEPENDS</filename> is meant + to be independent of the package format used. </para> <para> @@ -10123,6 +10677,11 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" For information on build-time dependencies, see the <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link> variable. + You can also see the + "<ulink url='&YOCTO_DOCS_BB_URL;#tasks'>Tasks</ulink>" and + "<ulink url='&YOCTO_DOCS_BB_URL;#dependencies'>Dependencies</ulink>" + sections in the BitBake User Manual for additional + information on tasks and dependencies. </para> </glossdef> </glossentry> @@ -10150,28 +10709,6 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-RM_OLD_IMAGE'><glossterm>RM_OLD_IMAGE</glossterm> - <info> - RM_OLD_IMAGE[doc] = "Reclaims disk space by removing previously built versions of the same image from the images directory pointed to by the DEPLOY_DIR variable." - </info> - <glossdef> - <para role="glossdeffirst"> -<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - Reclaims disk space by removing previously built - versions of the same image from the - <filename>images</filename> directory pointed to by the - <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link> - variable. - </para> - - <para> - Set this variable to "1" in your - <filename>local.conf</filename> file to remove these - images. - </para> - </glossdef> - </glossentry> - <glossentry id='var-RM_WORK_EXCLUDE'><glossterm>RM_WORK_EXCLUDE</glossterm> <info> RM_WORK_EXCLUDE[doc] = "With rm_work enabled, this variable specifies a list of packages whose work directories should not be removed." @@ -10802,6 +11339,33 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> + <glossentry id='var-SDK_INCLUDE_TOOLCHAIN'><glossterm>SDK_INCLUDE_TOOLCHAIN</glossterm> + <info> + SDK_INCLUDE_TOOLCHAIN[doc] = "When set to "1", specifies to include the toolchain in the extensible SDK." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + When set to "1", specifies to include the toolchain in the + extensible SDK. + Including the toolchain is useful particularly when + <link linkend='var-SDK_EXT_TYPE'><filename>SDK_EXT_TYPE</filename></link> + is set to "minimal" to keep the SDK reasonably small + but you still want to provide a usable toolchain. + For example, suppose you want to use the toolchain from an + IDE (e.g. Eclipse) or from other tools and you do not + want to perform additional steps to install the toolchain. + </para> + + <para> + The <filename>SDK_INCLUDE_TOOLCHAIN</filename> variable + defaults to "0" if <filename>SDK_EXT_TYPE</filename> + is set to "minimal", and defaults to "1" if + <filename>SDK_EXT_TYPE</filename> is set to "full". + </para> + </glossdef> + </glossentry> + <glossentry id='var-SDK_INHERIT_BLACKLIST'><glossterm>SDK_INHERIT_BLACKLIST</glossterm> <info> SDK_INHERIT_BLACKLIST[doc] = "A list of classes to remove from the INHERIT value globally within the extensible SDK configuration." @@ -11336,15 +11900,24 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossentry id='var-SERIAL_CONSOLES_CHECK'><glossterm>SERIAL_CONSOLES_CHECK</glossterm> <info> - SERIAL_CONSOLES_CHECK[doc] = "Similar to SERIAL_CONSOLES except the device is checked for existence before attempting to enable it. Supported only by SysVinit." + SERIAL_CONSOLES_CHECK[doc] = "Selected SERIAL_CONSOLES to check against /proc/console before enabling using getty. Supported only by SysVinit." </info> <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - Similar to - <link linkend='var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></link> - except the device is checked for existence before attempting - to enable it. + Specifies serial consoles, which must be listed in + <link linkend='var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></link>, + to check against <filename>/proc/console</filename> + before enabling them using getty. + This variable allows aliasing in the format: + <device>:<alias>. + If a device was listed as "sclp_line0" + in <filename>/dev/</filename> and "ttyS0" was listed + in <filename>/proc/console</filename>, you would do the + following: + <literallayout class='monospaced'> + SERIAL_CONSOLES_CHECK = "slcp_line0:ttyS0" + </literallayout> This variable is currently only supported with SysVinit (i.e. not with systemd). </para> @@ -11982,7 +12555,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" directory structure. <literallayout class='monospaced'> SSTATE_MIRRORS ?= "\ - file://.* http://<replaceable>someserver</replaceable>.tld/share/sstate/PATH \n \ + file://.* http://<replaceable>someserver</replaceable>.tld/share/sstate/PATH;downloadfilename=PATH \n \ file://.* file:///<replaceable>some-local-dir</replaceable>/sstate/PATH" </literallayout> </para> @@ -12129,28 +12702,71 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossentry id='var-STAGING_DIR_HOST'><glossterm>STAGING_DIR_HOST</glossterm> <info> - STAGING_DIR_HOST[doc] = "Specifies the path to the primary sysroot directory for which the target is being built." + STAGING_DIR_HOST[doc] = "Specifies the path to the sysroot directory for the system that the component is built to run on." </info> <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - Specifies the path to the primary sysroot directory for - which the target is being built. - Depending on the type of recipe and the build target, the - recipe's value is as follows: + Specifies the path to the sysroot directory for the system + that the component is built to run on (the system that hosts + the component). + For most recipes, this sysroot is the one that the recipe's + <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link> + task copies files into. + Exceptions include <filename>-native</filename> recipes, + where the <filename>do_populate_sysroot</filename> task + instead uses + <link linkend='var-STAGING_DIR_NATIVE'><filename>STAGING_DIR_NATIVE</filename></link>. + Depending on the type of recipe and the build target, + <filename>STAGING_DIR_HOST</filename> can have the + following values: <itemizedlist> <listitem><para>For recipes building for the target - machine, the value is "${STAGING_DIR}/${MACHINE}". - </para></listitem> + machine, the value is + "${<link linkend='var-STAGING_DIR'>STAGING_DIR</link>}/${<link linkend='var-MACHINE'>MACHINE</link>}". + </para></listitem> <listitem><para>For native recipes building - for the build host, the value is empty given the - assumption that when building for the build host, - the build host's own directories should be used. + for the build host, the value is empty given the + assumption that when building for the build host, + the build host's own directories should be used. + <note><para> + <filename>-native</filename> recipes are not + installed into host paths like such as + <filename>/usr</filename>. + Rather, these recipes are installed into + <filename>STAGING_DIR_NATIVE</filename>. + When compiling <filename>-native</filename> + recipes, standard build environment variables + such as + <link linkend='var-CPPFLAGS'><filename>CPPFLAGS</filename></link> + and + <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link> + are set up so that both host paths and + <filename>STAGING_DIR_NATIVE</filename> are + searched for libraries and headers using, for + example, GCC's <filename>-isystem</filename> + option.</para> + + <para>This emphasizes that the + <filename>STAGING_DIR*</filename> variables + should be viewed as input variables by tasks + such as + <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>, + <link linkend='ref-tasks-compile'><filename>do_compile</filename></link>, + and + <link linkend='ref-tasks-install'><filename>do_install</filename></link>. + Having the real system root correspond to + <filename>STAGING_DIR_HOST</filename> makes + conceptual sense for + <filename>-native</filename> recipes, as + they make use of host headers and libraries. + </para> + </note> </para></listitem> <listitem><para>For native SDK recipes that build for the SDK (<filename>nativesdk</filename>), the value is - "${STAGING_DIR}/${MULTIMACH_HOST_SYS}". + "${STAGING_DIR}/${<link linkend='var-MULTIMACH_HOST_SYS'>MULTIMACH_HOST_SYS</link>}". </para></listitem> </itemizedlist> </para> @@ -12159,27 +12775,29 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossentry id='var-STAGING_DIR_NATIVE'><glossterm>STAGING_DIR_NATIVE</glossterm> <info> - STAGING_DIR_NATIVE[doc] = "Specifies the path to the sysroot directory for the build host." + STAGING_DIR_NATIVE[doc] = "Specifies the path to the sysroot directory used when building components that run on the build host itself." </info> <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - Specifies the path to the sysroot directory for the - build host. + Specifies the path to the sysroot directory used when + building components that run on the build host itself. </para> </glossdef> </glossentry> <glossentry id='var-STAGING_DIR_TARGET'><glossterm>STAGING_DIR_TARGET</glossterm> <info> - STAGING_DIR_TARGET[doc] = "Specifies the path to the sysroot directory for the target for which the current recipe is being built." + STAGING_DIR_TARGET[doc] = "Specifies the path to the sysroot used for the system for which the component generates code." </info> <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - Specifies the path to the sysroot directory for the - target for which the current recipe is being built. - In most cases, this path is the + Specifies the path to the sysroot used for the system for + which the component generates code. + For components that do not generate code, which is the + majority, <filename>STAGING_DIR_TARGET</filename> is set + to match <link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>. </para> @@ -12190,10 +12808,12 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" Using terminology from GNU, the primary system is referred to as the "HOST" and the secondary, or different, system is referred to as the "TARGET". - Thus, the binaries run on the "HOST" system and + Thus, the binaries run on the "HOST" system and generate binaries for the "TARGET" system. - <filename>STAGING_DIR_TARGET</filename> points to the - sysroot used for the "TARGET" system. + The <filename>STAGING_DIR_HOST</filename> variable points + to the sysroot used for the "HOST" system, while + <filename>STAGING_DIR_TARGET</filename> + points to the sysroot used for the "TARGET" system. </para> </glossdef> </glossentry> @@ -12335,6 +12955,13 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </para> <para> + For information on how BitBake uses stamp files to determine + if a task should be rerun, see the + "<link linkend='stamp-files-and-the-rerunning-of-tasks'>Stamp Files and the Rerunning of Tasks</link>" + section. + </para> + + <para> See <link linkend='var-STAMPS_DIR'><filename>STAMPS_DIR</filename></link>, <link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>, <link linkend='var-PN'><filename>PN</filename></link>, @@ -12519,6 +13146,95 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> + <glossentry id='var-SYSROOT_DIRS'><glossterm>SYSROOT_DIRS</glossterm> + <info> + SYSROOT_DIRS[doc] = "Directories that are staged into the sysroot by the do_populate_sysroot task." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Directories that are staged into the sysroot by the + <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link> + task. + By default, the following directories are staged: + <literallayout class='monospaced'> + SYSROOT_DIRS = " \ + ${includedir} \ + ${libdir} \ + ${base_libdir} \ + ${nonarch_base_libdir} \ + ${datadir} \ + " + </literallayout> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-SYSROOT_DIRS_BLACKLIST'><glossterm>SYSROOT_DIRS_BLACKLIST</glossterm> + <info> + SYSROOT_DIRS_BLACKLIST[doc] = "Directories that are not staged into the sysroot by the do_populate_sysroot task." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Directories that are not staged into the sysroot by the + <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link> + task. + You can use this variable to exclude certain subdirectories + of directories listed in + <link linkend='var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></link> + from staging. + By default, the following directories are not staged: + <literallayout class='monospaced'> + SYSROOT_DIRS_BLACKLIST = " \ + ${mandir} \ + ${docdir} \ + ${infodir} \ + ${datadir}/locale \ + ${datadir}/applications \ + ${datadir}/fonts \ + ${datadir}/pixmaps \ + " + </literallayout> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-SYSROOT_DIRS_NATIVE'><glossterm>SYSROOT_DIRS_NATIVE</glossterm> + <info> + SYSROOT_DIRS_NATIVE[doc] = "Extra directories staged into the sysroot by the do_populate_sysroot task for -native recipes, in addition to those specified in SYSROOT_DIRS." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Extra directories staged into the sysroot by the + <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link> + task for <filename>-native</filename> recipes, in addition + to those specified in + <link linkend='var-SYSROOT_DIRS'><filename>SYSROOT_DIRS</filename></link>. + By default, the following extra directories are staged: + <literallayout class='monospaced'> + SYSROOT_DIRS_NATIVE = " \ + ${bindir} \ + ${sbindir} \ + ${base_bindir} \ + ${base_sbindir} \ + ${libexecdir} \ + ${sysconfdir} \ + ${localstatedir} \ + " + </literallayout> + <note> + Programs built by <filename>-native</filename> recipes + run directly from the sysroot + (<link linkend='var-STAGING_DIR_NATIVE'><filename>STAGING_DIR_NATIVE</filename></link>), + which is why additional directories containing program + executables and supporting files need to be staged. + </note> + </para> + </glossdef> + </glossentry> + <glossentry id='var-SYSROOT_PREPROCESS_FUNCS'><glossterm>SYSROOT_PREPROCESS_FUNCS</glossterm> <info> SYSROOT_PREPROCESS_FUNCS[doc] = "A list of functions to execute after files are staged into the sysroot. These functions are usually used to apply additional processing on the staged files, or to stage additional files." @@ -12565,6 +13281,92 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> + <glossentry id='var-SYSTEMD_BOOT_CFG'><glossterm>SYSTEMD_BOOT_CFG</glossterm> + <info> + SYSTEMD_BOOT_CFG[doc] = "When EFI_PROVIDER is set to "systemd-boot", the SYSTEMD_BOOT_CFG variable specifies the configuration file that should be used." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + When + <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link> + is set to "systemd-boot", the + <filename>SYSTEMD_BOOT_CFG</filename> variable specifies the + configuration file that should be used. + By default, the + <link linkend='ref-classes-systemd-boot'><filename>systemd-boot</filename></link> + class sets the <filename>SYSTEMD_BOOT_CFG</filename> as + follows: + <literallayout class='monospaced'> + SYSTEMD_BOOT_CFG ?= "${<link linkend='var-S'>S</link>}/loader.conf" + </literallayout> + </para> + + <para> + For information on Systemd-boot, see the + <ulink url='http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/'>Systemd-boot documentation</ulink>. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-SYSTEMD_BOOT_ENTRIES'><glossterm>SYSTEMD_BOOT_ENTRIES</glossterm> + <info> + SYSTEMD_BOOT_ENTRIES[doc] = "When EFI_PROVIDER is set to "systemd-boot", the SYSTEMD_BOOT_ENTRIES variable specifies a list of entry files (*.conf) to be installed containing one boot entry per file." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + When + <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link> + is set to "systemd-boot", the + <filename>SYSTEMD_BOOT_ENTRIES</filename> variable specifies + a list of entry files + (<filename>*.conf</filename>) to be installed + containing one boot entry per file. + By default, the + <link linkend='ref-classes-systemd-boot'><filename>systemd-boot</filename></link> + class sets the <filename>SYSTEMD_BOOT_ENTRIES</filename> as + follows: + <literallayout class='monospaced'> + SYSTEMD_BOOT_ENTRIES ?= "" + </literallayout> + </para> + + <para> + For information on Systemd-boot, see the + <ulink url='http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/'>Systemd-boot documentation</ulink>. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-SYSTEMD_BOOT_TIMEOUT'><glossterm>SYSTEMD_BOOT_TIMEOUT</glossterm> + <info> + SYSTEMD_BOOT_TIMEOUT[doc] = "When EFI_PROVIDER is set to "systemd-boot", the SYSTEMD_BOOT_TIMEOUT variable specifies the boot menu timeout in seconds." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + When + <link linkend='var-EFI_PROVIDER'><filename>EFI_PROVIDER</filename></link> + is set to "systemd-boot", the + <filename>SYSTEMD_BOOT_TIMEOUT</filename> variable specifies + the boot menu timeout in seconds. + By default, the + <link linkend='ref-classes-systemd-boot'><filename>systemd-boot</filename></link> + class sets the <filename>SYSTEMD_BOOT_TIMEOUT</filename> as + follows: + <literallayout class='monospaced'> + SYSTEMD_BOOT_TIMEOUT ?= "10" + </literallayout> + </para> + + <para> + For information on Systemd-boot, see the + <ulink url='http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/'>Systemd-boot documentation</ulink>. + </para> + </glossdef> + </glossentry> + <glossentry id='var-SYSTEMD_PACKAGES'><glossterm>SYSTEMD_PACKAGES</glossterm> <info> SYSTEMD_PACKAGES[doc] = "For recipes that inherit the systemd class, this variable locates the systemd unit files when they are not found in the main recipe's package." @@ -14255,7 +15057,9 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" task. Normally, invalid configure options are simply not passed to the configure script (e.g. should be removed from - <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>). + <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link> + or + <link linkend='var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></link>). However, common options, for example, exist that are passed to all configure scripts at a class level that might not be valid for some configure scripts. @@ -14300,6 +15104,84 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> + <glossentry id='var-UPSTREAM_CHECK_GITTAGREGEX'><glossterm>UPSTREAM_CHECK_GITTAGREGEX</glossterm> + <info> + UPSTREAM_CHECK_GITTAGREGEX[doc] = "Filters relevant Git tags when fetching source from an upstream Git repository." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + When the + <link linkend='ref-classes-distrodata'><filename>distrodata</filename></link> + class is enabled globally, you can perform a per-recipe + check for what the latest upstream source code version is + by calling + <filename>bitbake -c checkpkg</filename> <replaceable>recipe</replaceable>. + If the recipe source code is provided from Git + repositories, the OpenEmbedded build system determines the + latest upstream version by picking the latest tag from the + list of all repository tags. + You can use the + <filename>UPSTREAM_CHECK_GITTAGREGEX</filename> + variable to provide a regular expression to filter only the + relevant tags should the default filter not work + correctly. + <literallayout class='monospaced'> + UPSTREAM_CHECK_GITTAGREGEX = "git_tag_regex" + </literallayout> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-UPSTREAM_CHECK_REGEX'><glossterm>UPSTREAM_CHECK_REGEX</glossterm> + <info> + UPSTREAM_CHECK_REGEX[doc] = "The regular expression the package checking system uses to parse the page pointed to by UPSTREAM_CHECK_URI." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + When the + <link linkend='ref-classes-distrodata'><filename>distrodata</filename></link> + class is enabled globally, use the + <filename>UPSTREAM_CHECK_REGEX</filename> variable to + specify a different regular expression instead of the + default one when the package checking system is parsing + the page found using + <link linkend='var-UPSTREAM_CHECK_URI'><filename>UPSTREAM_CHECK_URI</filename></link>. + <literallayout class='monospaced'> + UPSTREAM_CHECK_REGEX = "package_regex" + </literallayout> + </para> + </glossdef> + </glossentry> + + <glossentry id='var-UPSTREAM_CHECK_URI'><glossterm>UPSTREAM_CHECK_URI</glossterm> + <info> + UPSTREAM_CHECK_URI[doc] = "The URL used by the package checking system to get the latest version of the package when source files are fetched from an upstream Git repository." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + When the + <link linkend='ref-classes-distrodata'><filename>distrodata</filename></link> + class is enabled globally, you can perform a per-recipe + check for what the latest upstream source code version is + by calling <filename>bitbake -c checkpkg</filename> + <replaceable>recipe</replaceable>. + If the source code is provided from tarballs, the latest + version is determined by fetching the directory listing + where the tarball is and attempting to find a later tarball. + When this approach does not work, you can use + <filename>UPSTREAM_CHECK_URI</filename> to + provide a different URI that contains the link to the + latest tarball. + <literallayout class='monospaced'> + UPSTREAM_CHECK_URI = "recipe_url" + </literallayout> + </para> + </glossdef> + </glossentry> + <glossentry id='var-USE_DEVFS'><glossterm>USE_DEVFS</glossterm> <info> USE_DEVFS[doc] = "Determines if devtmpfs is used for /dev population." @@ -14381,16 +15263,18 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossentry id='var-USERADD_ERROR_DYNAMIC'><glossterm>USERADD_ERROR_DYNAMIC</glossterm> <info> - USERADD_ERROR_DYNAMIC[doc] = "Forces the OpenEmbedded build system to produce an error if the user identification (uid) and group identification (gid) values are not defined in files/passwd and files/group files." + USERADD_ERROR_DYNAMIC[doc] = "If set to 'error', forces the OpenEmbedded build system to produce an error if the user identification (uid) and group identification (gid) values are not defined in files/passwd and files/group files. If set to 'warn', a warning will be issued instead." </info> <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - Forces the OpenEmbedded build system to produce an error - if the user identification (<filename>uid</filename>) and - group identification (<filename>gid</filename>) values - are not defined in <filename>files/passwd</filename> + If set to "error", forces the OpenEmbedded build system to + produce an error if the user identification + (<filename>uid</filename>) and group identification + (<filename>gid</filename>) values are not defined + in <filename>files/passwd</filename> and <filename>files/group</filename> files. + If set to "warn", a warning will be issued instead. </para> <para> @@ -14406,7 +15290,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" your <filename>local.conf</filename> file as follows: <literallayout class='monospaced'> - USERADD_ERROR_DYNAMIC = "1" + USERADD_ERROR_DYNAMIC = "error" </literallayout> Overriding the default behavior implies you are going to also take steps to set static <filename>uid</filename> and @@ -14562,7 +15446,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossentry id='var-USERADDEXTENSION'><glossterm>USERADDEXTENSION</glossterm> <info> - USERADDEXTENSION[doc] = "When set to "useradd-staticids", causes the OpenEmbedded build system to base all user and group additions on a static passwd and group files found in BBPATH." + USERADDEXTENSION[doc] = "When set to 'useradd-staticids', causes the OpenEmbedded build system to base all user and group additions on a static passwd and group files found in BBPATH." </info> <glossdef> <para role="glossdeffirst"> diff --git a/import-layers/yocto-poky/documentation/ref-manual/ref-varlocality.xml b/import-layers/yocto-poky/documentation/ref-manual/ref-varlocality.xml index d3f873298..54524d5b6 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/ref-varlocality.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/ref-varlocality.xml @@ -176,16 +176,18 @@ <para> This section lists variables that define extra build information for recipes. <itemizedlist> + <listitem><para><filename><link linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE + </link></filename></para></listitem> <listitem><para><filename><link linkend='var-EXTRA_OECMAKE'>EXTRA_OECMAKE</link> </filename></para></listitem> <listitem><para><filename><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link> </filename></para></listitem> <listitem><para><filename><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link> </filename></para></listitem> + <listitem><para><filename><link linkend='var-PACKAGECONFIG_CONFARGS'>PACKAGECONFIG_CONFARGS</link> + </filename></para></listitem> <listitem><para><filename><link linkend='var-PACKAGES'>PACKAGES</link></filename> </para></listitem> - <listitem><para><filename><link linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE - </link></filename></para></listitem> </itemizedlist> </para> </section> diff --git a/import-layers/yocto-poky/documentation/ref-manual/technical-details.xml b/import-layers/yocto-poky/documentation/ref-manual/technical-details.xml index f06382ab5..9bb09fb94 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/technical-details.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/technical-details.xml @@ -690,6 +690,125 @@ addtask do_deploy_setscene do_deploy[dirs] = "${DEPLOYDIR} ${B}" </literallayout> + The following list explains the previous example: + <itemizedlist> + <listitem><para> + Adding "do_deploy" to <filename>SSTATETASKS</filename> + adds some required sstate-related processing, which is + implemented in the + <link linkend='ref-classes-sstate'><filename>sstate</filename></link> + class, to before and after the + <link linkend='ref-tasks-deploy'><filename>do_deploy</filename></link> + task. + </para></listitem> + <listitem><para> + The + <filename>do_deploy[sstate-inputdirs] = "${DEPLOYDIR}"</filename> + declares that <filename>do_deploy</filename> places its + output in <filename>${DEPLOYDIR}</filename> when run + normally (i.e. when not using the sstate cache). + This output becomes the input to the shared state cache. + </para></listitem> + <listitem><para> + The + <filename>do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}"</filename> + line causes the contents of the shared state cache to be + copied to <filename>${DEPLOY_DIR_IMAGE}</filename>. + <note> + If <filename>do_deploy</filename> is not already in + the shared state cache or if its input checksum + (signature) has changed from when the output was + cached, the task will be run to populate the shared + state cache, after which the contents of the shared + state cache is copied to + <filename>${DEPLOY_DIR_IMAGE}</filename>. + If <filename>do_deploy</filename> is in the shared + state cache and its signature indicates that the + cached output is still valid (i.e. if no + relevant task inputs have changed), then the contents + of the shared state cache will be copied directly to + <filename>${DEPLOY_DIR_IMAGE}</filename> by the + <filename>do_deploy_setscene</filename> task instead, + skipping the <filename>do_deploy</filename> task. + </note> + </para></listitem> + <listitem><para> + The following task definition is glue logic needed to make + the previous settings effective: + <literallayout class='monospaced'> + python do_deploy_setscene () { + sstate_setscene(d) + } + addtask do_deploy_setscene + </literallayout> + <filename>sstate_setscene()</filename> takes the flags + above as input and accelerates the + <filename>do_deploy</filename> task through the + shared state cache if possible. + If the task was accelerated, + <filename>sstate_setscene()</filename> returns True. + Otherwise, it returns False, and the normal + <filename>do_deploy</filename> task runs. + For more information, see the + "<ulink url='&YOCTO_DOCS_BB_URL;#setscene'>setscene</ulink>" + section in the BitBake User Manual. + </para></listitem> + <listitem><para> + The <filename>do_deploy[dirs] = "${DEPLOYDIR} ${B}"</filename> + line creates <filename>${DEPLOYDIR}</filename> and + <filename>${B}</filename> before the + <filename>do_deploy</filename> task runs, and also sets + the current working directory of + <filename>do_deploy</filename> to + <filename>${B}</filename>. + For more information, see the + "<ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'>Variable Flags</ulink>" + section in the BitBake User Manual. + <note> + In cases where + <filename>sstate-inputdirs</filename> and + <filename>sstate-outputdirs</filename> would be the + same, you can use + <filename>sstate-plaindirs</filename>. + For example, to preserve the + <filename>${PKGD}</filename> and + <filename>${PKGDEST}</filename> output from the + <link linkend='ref-tasks-package'><filename>do_package</filename></link> + task, use the following: + <literallayout class='monospaced'> + do_package[sstate-plaindirs] = "${PKGD} ${PKGDEST}" + </literallayout> + </note> + </para></listitem> + <listitem><para> + <filename>sstate-inputdirs</filename> and + <filename>sstate-outputdirs</filename> can also be used + with multiple directories. + For example, the following declares + <filename>PKGDESTWORK</filename> and + <filename>SHLIBWORK</filename> as shared state + input directories, which populates the shared state + cache, and <filename>PKGDATA_DIR</filename> and + <filename>SHLIBSDIR</filename> as the corresponding + shared state output directories: + <literallayout class='monospaced'> + do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}" + do_package[sstate-outputdirs] = "${PKGDATA_DIR} ${SHLIBSDIR}" + </literallayout> + </para></listitem> + <listitem><para> + These methods also include the ability to take a lockfile + when manipulating shared state directory structures, + for cases where file additions or removals are sensitive: + <literallayout class='monospaced'> + do_package[sstate-lockfile] = "${PACKAGELOCK}" + </literallayout> + </para></listitem> + </itemizedlist> + </para> + +<!-- + <para> In this example, we add some extra flags to the task, a name field ("deploy"), an input directory where the task sends data, and the output directory where the data from the task should eventually be copied. @@ -713,6 +832,7 @@ shared state directory structures since some cases are sensitive to file additions or removals. </para> +--> <para> Behind the scenes, the shared state code works by looking in @@ -722,7 +842,7 @@ Here is an example: <literallayout class='monospaced'> SSTATE_MIRRORS ?= "\ - file://.* http://someserver.tld/share/sstate/PATH \n \ + file://.* http://someserver.tld/share/sstate/PATH;downloadfilename=PATH \n \ file://.* file:///some/local/dir/sstate/PATH" </literallayout> <note> @@ -781,56 +901,15 @@ <title>Debugging</title> <para> - When things go wrong, debugging needs to be straightforward. - Because of this, the Yocto Project includes strong debugging - tools: - <itemizedlist> - <listitem><para>Whenever a shared state package is written - out into the - <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>, - a corresponding <filename>.siginfo</filename> file is - also written. - This file contains a pickled Python database of all - the Metadata that went into creating the hash for a - given shared state package. - Whenever a stamp is written into the stamp directory - <link linkend='var-STAMP'><filename>STAMP</filename></link>, - a corresponding <filename>.sigdata</filename> file - is created that contains the same hash data that - represented the executed task. - </para></listitem> - <listitem><para>You can use BitBake to dump out the - signature construction information without executing - tasks by using either of the following BitBake - command-line options: - <literallayout class='monospaced'> - ‐‐dump-signatures=<replaceable>SIGNATURE_HANDLER</replaceable> - -S <replaceable>SIGNATURE_HANDLER</replaceable> - </literallayout> - <note> - Two common values for - <replaceable>SIGNATURE_HANDLER</replaceable> are - "none" and "printdiff" to only dump the signature - or to compare the dumped signature with the - cached one, respectively. - </note> - Using BitBake with either of these options causes - BitBake to dump out <filename>.sigdata</filename> files - in the stamp directory for every task it would have - executed instead of building the specified target - package. - </para></listitem> - <listitem><para>There is a - <filename>bitbake-diffsigs</filename> command that - can process <filename>.sigdata</filename> and - <filename>.siginfo</filename> files. - If you specify one of these files, BitBake dumps out - the dependency information in the file. - If you specify two files, BitBake compares the two - files and dumps out the differences between the two. - This more easily helps answer the question of "What - changed between X and Y?"</para></listitem> - </itemizedlist> + Seeing what metadata went into creating the input signature + of a shared state (sstate) task can be a useful debugging aid. + This information is available in signature information + (<filename>siginfo</filename>) files in + <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>. + For information on how to view and interpret information in + <filename>siginfo</filename> files, see the + "<link linkend='usingpoky-viewing-task-variable-dependencies'>Viewing Task Variable Dependencies</link>" + section. </para> </section> @@ -900,6 +979,222 @@ </section> </section> +<section id='automatically-added-runtime-dependencies'> + <title>Automatically Added Runtime Dependencies</title> + + <para> + The OpenEmbedded build system automatically adds common types of + runtime dependencies between packages, which means that you do not + need to explicitly declare the packages using + <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>. + Three automatic mechanisms exist (<filename>shlibdeps</filename>, + <filename>pcdeps</filename>, and <filename>depchains</filename>) that + handle shared libraries, package configuration (pkg-config) modules, + and <filename>-dev</filename> and <filename>-dbg</filename> packages, + respectively. + For other types of runtime dependencies, you must manually declare + the dependencies. + <itemizedlist> + <listitem><para> + <filename>shlibdeps</filename>: + During the + <link linkend='ref-tasks-package'><filename>do_package</filename></link> + task of each recipe, all shared libraries installed by the + recipe are located. + For each shared library, the package that contains the shared + library is registered as providing the shared library. + More specifically, the package is registered as providing the + <ulink url='https://en.wikipedia.org/wiki/Soname'>soname</ulink> + of the library. + The resulting shared-library-to-package mapping + is saved globally in + <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link> + by the + <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link> + task.</para> + + <para>Simultaneously, all executables and shared libraries + installed by the recipe are inspected to see what shared + libraries they link against. + For each shared library dependency that is found, + <filename>PKGDATA_DIR</filename> is queried to + see if some package (likely from a different recipe) contains + the shared library. + If such a package is found, a runtime dependency is added from + the package that depends on the shared library to the package + that contains the library.</para> + + <para>The automatically added runtime dependency also includes + a version restriction. + This version restriction specifies that at least the current + version of the package that provides the shared library must be + used, as if + "<replaceable>package</replaceable> (>= <replaceable>version</replaceable>)" + had been added to + <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>. + This forces an upgrade of the package containing the shared + library when installing the package that depends on the + library, if needed.</para> + + <para>If you want to avoid a package being registered as + providing a particular shared library (e.g. because the library + is for internal use only), then add the library to + <link linkend='var-PRIVATE_LIBS'><filename>PRIVATE_LIBS</filename></link> + inside the package's recipe. + </para></listitem> + <listitem><para> + <filename>pcdeps</filename>: + During the + <link linkend='ref-tasks-package'><filename>do_package</filename></link> + task of each recipe, all pkg-config modules + (<filename>*.pc</filename> files) installed by the recipe are + located. + For each module, the package that contains the module is + registered as providing the module. + The resulting module-to-package mapping is saved globally in + <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link> + by the + <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link> + task.</para> + + <para>Simultaneously, all pkg-config modules installed by the + recipe are inspected to see what other pkg-config modules they + depend on. + A module is seen as depending on another module if it contains + a "Requires:" line that specifies the other module. + For each module dependency, + <filename>PKGDATA_DIR</filename> is queried to see if some + package contains the module. + If such a package is found, a runtime dependency is added from + the package that depends on the module to the package that + contains the module. + <note> + The <filename>pcdeps</filename> mechanism most often infers + dependencies between <filename>-dev</filename> packages. + </note> + </para></listitem> + <listitem><para> + <filename>depchains</filename>: + If a package <filename>foo</filename> depends on a package + <filename>bar</filename>, then <filename>foo-dev</filename> + and <filename>foo-dbg</filename> are also made to depend on + <filename>bar-dev</filename> and <filename>bar-dbg</filename>, + respectively. + Taking the <filename>-dev</filename> packages as an example, + the <filename>bar-dev</filename> package might provide + headers and shared library symlinks needed by + <filename>foo-dev</filename>, which shows the need + for a dependency between the packages.</para> + + <para>The dependencies added by <filename>depchains</filename> + are in the form of + <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>. + <note> + By default, <filename>foo-dev</filename> also has an + <filename>RDEPENDS</filename>-style dependency on + <filename>foo</filename>, because the default value of + <filename>RDEPENDS_${PN}-dev</filename> (set in + <filename>bitbake.conf</filename>) includes + "${PN}". + </note></para> + + <para>To ensure that the dependency chain is never broken, + <filename>-dev</filename> and <filename>-dbg</filename> + packages are always generated by default, even if the packages + turn out to be empty. + See the + <link linkend='var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></link> + variable for more information. + </para></listitem> + </itemizedlist> + </para> + + <para> + The <filename>do_package</filename> task depends on the + <link linkend='ref-tasks-packagedata'><filename>do_packagedata</filename></link> + task of each recipe in + <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link> + through use of a + <filename>[</filename><ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>deptask</filename></ulink><filename>]</filename> + declaration, which guarantees that the required + shared-library/module-to-package mapping information will be available + when needed as long as <filename>DEPENDS</filename> has been + correctly set. + </para> +</section> + +<section id='fakeroot-and-pseudo'> + <title>Fakeroot and Pseudo</title> + + <para> + Some tasks are easier to implement when allowed to perform certain + operations that are normally reserved for the root user. + For example, the + <link linkend='ref-tasks-install'><filename>do_install</filename></link> + task benefits from being able to set the UID and GID of installed files + to arbitrary values. + </para> + + <para> + One approach to allowing tasks to perform root-only operations + would be to require BitBake to run as root. + However, this method is cumbersome and has security issues. + The approach that is actually used is to run tasks that benefit from + root privileges in a "fake" root environment. + Within this environment, the task and its child processes believe that + they are running as the root user, and see an internally consistent + view of the filesystem. + As long as generating the final output (e.g. a package or an image) + does not require root privileges, the fact that some earlier steps ran + in a fake root environment does not cause problems. + </para> + + <para> + The capability to run tasks in a fake root environment is known as + "fakeroot", which is derived from the BitBake keyword/variable + flag that requests a fake root environment for a task. + In current versions of the OpenEmbedded build system, + the program that implements fakeroot is known as Pseudo. + </para> + + <para> + Pseudo overrides system calls through the + <filename>LD_PRELOAD</filename> mechanism to give the + illusion of running as root. + To keep track of "fake" file ownership and permissions resulting from + operations that require root permissions, an sqlite3 + database is used. + This database is stored in + <filename>${</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link><filename>}/pseudo/files.db</filename> + for individual recipes. + Storing the database in a file as opposed to in memory + gives persistence between tasks, and even between builds. + <note><title>Caution</title> + If you add your own task that manipulates the same files or + directories as a fakeroot task, then that task should also run + under fakeroot. + Otherwise, the task will not be able to run root-only operations, + and will not see the fake file ownership and permissions set by the + other task. + You should also add a dependency on + <filename>virtual/fakeroot-native:do_populate_sysroot</filename>, + giving the following: + <literallayout class='monospaced'> + fakeroot do_mytask () { + ... + } + do_mytask[depends] += "virtual/fakeroot-native:do_populate_sysroot" + </literallayout> + </note> + For more information, see the + <ulink url='&YOCTO_DOCS_BB_URL;#var-FAKEROOT'><filename>FAKEROOT*</filename></ulink> + variables in the BitBake User Manual. + You can also reference this + <ulink url='http://www.ibm.com/developerworks/opensource/library/os-aapseudo1/index.html'>Pseudo</ulink> + article. + </para> +</section> + <section id='x32'> <title>x32</title> diff --git a/import-layers/yocto-poky/documentation/ref-manual/usingpoky.xml b/import-layers/yocto-poky/documentation/ref-manual/usingpoky.xml index a7bf32d45..f7345547c 100644 --- a/import-layers/yocto-poky/documentation/ref-manual/usingpoky.xml +++ b/import-layers/yocto-poky/documentation/ref-manual/usingpoky.xml @@ -119,8 +119,8 @@ </para> </section> -<section id='usingpoky-debugging'> - <title>Debugging Build Failures</title> +<section id='usingpoky-debugging-tools-and-techniques'> + <title>Debugging Tools and Techniques</title> <para> The exact method for debugging build failures depends on the nature of @@ -163,23 +163,420 @@ <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual'>BitBake User Manual</ulink>. </note> + <section id='usingpoky-debugging-viewing-logs-from-failed-tasks'> + <title>Viewing Logs from Failed Tasks</title> - <section id='usingpoky-debugging-taskfailures'> - <title>Task Failures</title> + <para> + You can find the log for a task in the file + <filename>${</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link><filename>}/temp/log.do_</filename><replaceable>taskname</replaceable>. + For example, the log for the + <link linkend='ref-tasks-compile'><filename>do_compile</filename></link> + task of the QEMU minimal image for the x86 machine + (<filename>qemux86</filename>) might be in + <filename>tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/temp/log.do_compile</filename>. + To see the commands + <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink> ran + to generate a log, look at the corresponding + <filename>run.do_</filename><replaceable>taskname</replaceable> + file in the same directory. + </para> + + <para> + <filename>log.do_</filename><replaceable>taskname</replaceable> and + <filename>run.do_</filename><replaceable>taskname</replaceable> + are actually symbolic links to + <filename>log.do_</filename><replaceable>taskname</replaceable><filename>.</filename><replaceable>pid</replaceable> + and + <filename>log.run_</filename><replaceable>taskname</replaceable><filename>.</filename><replaceable>pid</replaceable>, + where <replaceable>pid</replaceable> is the PID the task had when + it ran. + The symlinks always point to the files corresponding to the most + recent run. + </para> + </section> + + <section id='usingpoky-debugging-viewing-variable-values'> + <title>Viewing Variable Values</title> + <para> + BitBake's <filename>-e</filename> option is used to display + variable values after parsing. + The following command displays the variable values after the + configuration files (i.e. <filename>local.conf</filename>, + <filename>bblayers.conf</filename>, + <filename>bitbake.conf</filename> and so forth) have been + parsed: + <literallayout class='monospaced'> + $ bitbake -e + </literallayout> + The following command displays variable values after a specific + recipe has been parsed. + The variables include those from the configuration as well: + <literallayout class='monospaced'> + $ bitbake -e recipename + </literallayout> + <note><para> + Each recipe has its own private set of variables (datastore). + Internally, after parsing the configuration, a copy of the + resulting datastore is made prior to parsing each recipe. + This copying implies that variables set in one recipe will + not be visible to other recipes.</para> + + <para>Likewise, each task within a recipe gets a private + datastore based on the recipe datastore, which means that + variables set within one task will not be visible to + other tasks.</para> + </note> + </para> + + <para> + In the output of <filename>bitbake -e</filename>, each variable is + preceded by a description of how the variable got its value, + including temporary values that were later overriden. + This description also includes variable flags (varflags) set on + the variable. + The output can be very helpful during debugging. + </para> + + <para> + Variables that are exported to the environment are preceded by + <filename>export</filename> in the output of + <filename>bitbake -e</filename>. + See the following example: + <literallayout class='monospaced'> + export CC="i586-poky-linux-gcc -m32 -march=i586 --sysroot=/home/ulf/poky/build/tmp/sysroots/qemux86" + </literallayout> + </para> + + <para> + In addition to variable values, the output of the + <filename>bitbake -e</filename> and + <filename>bitbake -e</filename> <replaceable>recipe</replaceable> + commands includes the following information: + <itemizedlist> + <listitem><para> + The output starts with a tree listing all configuration + files and classes included globally, recursively listing + the files they include or inherit in turn. + Much of the behavior of the OpenEmbedded build system + (including the behavior of the + <link linkend='normal-recipe-build-tasks'>normal recipe build tasks</link>) + is implemented in the + <link linkend='ref-classes-base'><filename>base</filename></link> + class and the classes it inherits, rather than being built + into BitBake itself. + </para></listitem> + <listitem><para> + After the variable values, all functions appear in the + output. + For shell functions, variables referenced within the + function body are expanded. + If a function has been modified using overrides or + using override-style operators like + <filename>_append</filename> and + <filename>_prepend</filename>, then the final assembled + function body appears in the output. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='viewing-package-information-with-oe-pkgdata-util'> + <title>Viewing Package Information with <filename>oe-pkgdata-util</filename></title> + + <para> + You can use the <filename>oe-pkgdata-util</filename> command-line + utility to query + <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link> + and display various package-related information. + When you use the utility, you must use it to view information + on packages that have already been built. + </para> + + <para> + Following are a few of the available + <filename>oe-pkgdata-util</filename> subcommands. + <note> + You can use the standard * and ? globbing wildcards as part of + package names and paths. + </note> + <itemizedlist> + <listitem><para> + <filename>oe-pkgdata-util list-pkgs [</filename><replaceable>pattern</replaceable><filename>]</filename>: + Lists all packages that have been built, optionally + limiting the match to packages that match + <replaceable>pattern</replaceable>. + </para></listitem> + <listitem><para> + <filename>oe-pkgdata-util list-pkg-files </filename><replaceable>package</replaceable><filename> ...</filename>: + Lists the files and directories contained in the given + packages. + <note> + <para> + A different way to view the contents of a package is + to look at the + <filename>${</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link><filename>}/packages-split</filename> + directory of the recipe that generates the + package. + This directory is created by the + <link linkend='ref-tasks-package'><filename>do_package</filename></link> + task and has one subdirectory for each package the + recipe generates, which contains the files stored in + that package.</para> + <para> + If you want to inspect the + <filename>${WORKDIR}/packages-split</filename> + directory, make sure that + <link linkend='ref-classes-rm-work'><filename>rm_work</filename></link> + is not enabled when you build the recipe. + </para> + </note> + </para></listitem> + <listitem><para> + <filename>oe-pkgdata-util find-path </filename><replaceable>path</replaceable><filename> ...</filename>: + Lists the names of the packages that contain the given + paths. + For example, the following tells us that + <filename>/usr/share/man/man1/make.1</filename> + is contained in the <filename>make-doc</filename> + package: + <literallayout class='monospaced'> + $ oe-pkgdata-util find-path /usr/share/man/man1/make.1 + make-doc: /usr/share/man/man1/make.1 + </literallayout> + </para></listitem> + <listitem><para> + <filename>oe-pkgdata-util lookup-recipe </filename><replaceable>package</replaceable><filename> ...</filename>: + Lists the name of the recipes that + produce the given packages. + </para></listitem> + </itemizedlist> + </para> - <para>The log file for shell tasks is available in - <filename>${WORKDIR}/temp/log.do_<replaceable>taskname</replaceable>.pid</filename>. - For example, the <filename>do_compile</filename> task for the QEMU minimal image for the x86 - machine (<filename>qemux86</filename>) might be - <filename>tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/temp/log.do_compile.20830</filename>. - To see what - <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink> - runs to generate that log, look at the corresponding - <filename>run.do_<replaceable>taskname</replaceable>.pid</filename> file located in the same directory. + <para> + For more information on the <filename>oe-pkgdata-util</filename> + command, use the help facility: + <literallayout class='monospaced'> + $ oe-pkgdata-util ‐‐help + $ oe-pkgdata-util <replaceable>subcommand</replaceable> --help + </literallayout> </para> + </section> + + <section id='usingpoky-viewing-dependencies-between-recipes-and-tasks'> + <title>Viewing Dependencies Between Recipes and Tasks</title> <para> - Presently, the output from Python tasks is sent directly to the console. + Sometimes it can be hard to see why BitBake wants to build other + recipes before the one you have specified. + Dependency information can help you understand why a recipe is + built. + </para> + + <para> + To generate dependency information for a recipe, run the following + command: + <literallayout class='monospaced'> + $ bitbake -g <replaceable>recipename</replaceable> + </literallayout> + This command writes the following files in the current directory: + <itemizedlist> + <listitem><para> + <filename>pn-buildlist</filename>: A list of + recipes/targets involved in building + <replaceable>recipename</replaceable>. + "Involved" here means that at least one task from the + recipe needs to run when building + <replaceable>recipename</replaceable> from scratch. + Targets that are in + <link linkend='var-ASSUME_PROVIDED'><filename>ASSUME_PROVIDED</filename></link> + are not listed. + </para></listitem> + <listitem><para> + <filename>pn-depends.dot</filename>: A graph showing + dependencies between build-time targets (recipes). + </para></listitem> + <listitem><para> + <filename>package-depends.dot</filename>: A graph showing + known dependencies between runtime targets. + </para></listitem> + <listitem><para> + <filename>task-depends.dot</filename>: A graph showing + dependencies between tasks. + </para></listitem> + </itemizedlist> + </para> + + <para> + The graphs are in + <ulink url='https://en.wikipedia.org/wiki/DOT_%28graph_description_language%29'>DOT</ulink> + format and can be converted to images (e.g. using the + <filename>dot</filename> tool from + <ulink url='http://www.graphviz.org/'>Graphviz</ulink>). + <note><title>Notes</title> + <itemizedlist> + <listitem><para> + DOT files use a plain text format. + The graphs generated using the + <filename>bitbake -g</filename> command are often so + large as to be difficult to read without special + pruning (e.g. with Bitbake's + <filename>-I</filename> option) and processing. + Despite the form and size of the graphs, the + corresponding <filename>.dot</filename> files can still + be possible to read and provide useful information. + </para> + + <para>As an example, the + <filename>task-depends.dot</filename> file contains + lines such as the following: + <literallayout class='monospaced'> + "libxslt.do_configure" -> "libxml2.do_populate_sysroot" + </literallayout> + The above example line reveals that the + <link linkend='ref-tasks-configure'><filename>do_configure</filename></link> + task in <filename>libxslt</filename> depends on the + <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link> + task in <filename>libxml2</filename>, which is a normal + <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link> + dependency between the two recipes. + </para></listitem> + <listitem><para> + For an example of how <filename>.dot</filename> files + can be processed, see the + <filename>scripts/contrib/graph-tool</filename> Python + script, which finds and displays paths between graph + nodes. + </para></listitem> + </itemizedlist> + </note> + </para> + + <para> + You can use a different method to view dependency information + by using the following command: + <literallayout class='monospaced'> + $ bitbake -g -u depexp <replaceable>recipename</replaceable> + </literallayout> + This command displays a GUI window from which you can view + build-time and runtime dependencies for the recipes involved in + building <replaceable>recipename</replaceable>. + </para> + </section> + + <section id='usingpoky-viewing-task-variable-dependencies'> + <title>Viewing Task Variable Dependencies</title> + + <para> + As mentioned in the + "<ulink url='&YOCTO_DOCS_BB_URL;#checksums'>Checksums (Signatures)</ulink>" + section of the BitBake User Manual, BitBake tries to automatically + determine what variables a task depends on so that it can rerun + the task if any values of the variables change. + This determination is usually reliable. + However, if you do things like construct variable names at runtime, + then you might have to manually declare dependencies on those + variables using <filename>vardeps</filename> as described in the + "<ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'>Variable Flags</ulink>" + section of the BitBake User Manual. + </para> + + <para> + If you are unsure whether a variable dependency is being picked up + automatically for a given task, you can list the variable + dependencies BitBake has determined by doing the following: + <orderedlist> + <listitem><para> + Build the recipe containing the task: + <literallayout class='monospaced'> + $ bitbake <replaceable>recipename</replaceable> + </literallayout> + </para></listitem> + <listitem><para> + Inside the + <link linkend='var-STAMPS_DIR'><filename>STAMPS_DIR</filename></link> + directory, find the signature data + (<filename>sigdata</filename>) file that corresponds to the + task. + The <filename>sigdata</filename> files contain a pickled + Python database of all the metadata that went into creating + the input checksum for the task. + As an example, for the + <link linkend='ref-tasks-fetch'><filename>do_fetch</filename></link> + task of the <filename>db</filename> recipe, the + <filename>sigdata</filename> file might be found in the + following location: + <literallayout class='monospaced'> + ${BUILDDIR}/tmp/stamps/i586-poky-linux/db/6.0.30-r1.do_fetch.sigdata.7c048c18222b16ff0bcee2000ef648b1 + </literallayout> + For tasks that are accelerated through the shared state + (<link linkend='shared-state-cache'>sstate</link>) + cache, an additional <filename>siginfo</filename> file is + written into + <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link> + along with the cached task output. + The <filename>siginfo</filename> files contain exactly the + same information as <filename>sigdata</filename> files. + </para></listitem> + <listitem><para> + Run <filename>bitbake-dumpsig</filename> on the + <filename>sigdata</filename> or + <filename>siginfo</filename> file. + Here is an example: + <literallayout class='monospaced'> + $ bitbake-dumpsig ${BUILDDIR}/tmp/stamps/i586-poky-linux/db/6.0.30-r1.do_fetch.sigdata.7c048c18222b16ff0bcee2000ef648b1 + </literallayout> + In the output of the above command, you will find a line + like the following, which lists all the (inferred) variable + dependencies for the task. + This list also includes indirect dependencies from + variables depending on other variables, recursively. + <literallayout class='monospaced'> + Task dependencies: ['PV', 'SRCREV', 'SRC_URI', 'SRC_URI[md5sum]', 'SRC_URI[sha256sum]', 'base_do_fetch'] + </literallayout> + <note> + Functions (e.g. <filename>base_do_fetch</filename>) + also count as variable dependencies. + These functions in turn depend on the variables they + reference. + </note> + The output of <filename>bitbake-dumpsig</filename> also includes + the value each variable had, a list of dependencies for each + variable, and + <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_HASHBASE_WHITELIST'><filename>BB_HASHBASE_WHITELIST</filename></ulink> + information. + </para></listitem> + </orderedlist> + </para> + + <para> + There is also a <filename>bitbake-diffsigs</filename> command for + comparing two <filename>siginfo</filename> or + <filename>sigdata</filename> files. + This command can be helpful when trying to figure out what changed + between two versions of a task. + If you call <filename>bitbake-diffsigs</filename> with just one + file, the command behaves like + <filename>bitbake-dumpsig</filename>. + </para> + + <para> + You can also use BitBake to dump out the signature construction + information without executing tasks by using either of the + following BitBake command-line options: + <literallayout class='monospaced'> + ‐‐dump-signatures=<replaceable>SIGNATURE_HANDLER</replaceable> + -S <replaceable>SIGNATURE_HANDLER</replaceable> + </literallayout> + <note> + Two common values for + <replaceable>SIGNATURE_HANDLER</replaceable> are "none" and + "printdiff", which dump only the signature or compare the + dumped signature with the cached one, respectively. + </note> + Using BitBake with either of these options causes BitBake to dump + out <filename>sigdata</filename> files in the + <filename>stamps</filename> directory for every task it would have + executed instead of building the specified target package. </para> </section> @@ -187,7 +584,7 @@ <title>Running Specific Tasks</title> <para> - Any given package consists of a set of tasks. + Any given recipe consists of a set of tasks. The standard BitBake behavior in most cases is: <filename>do_fetch</filename>, <filename>do_unpack</filename>, @@ -209,15 +606,39 @@ </para> <para> - If you wish to rerun a task, use the <filename>-f</filename> force - option. - For example, the following sequence forces recompilation after - changing files in the work directory. + The <filename>-c</filename> option respects task dependencies, + which means that all other tasks (including tasks from other + recipes) that the specified task depends on will be run before the + task. + Even when you manually specify a task to run with + <filename>-c</filename>, BitBake will only run the task if it + considers it "out of date". + See the + "<link linkend='stamp-files-and-the-rerunning-of-tasks'>Stamp Files and the Rerunning of Tasks</link>" + section for how BitBake determines whether a task is "out of date". + </para> + + <para> + If you want to force an up-to-date task to be rerun (e.g. + because you made manual modifications to the recipe's + <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link> + that you want to try out), then you can use the + <filename>-f</filename> option. + <note> + The reason <filename>-f</filename> is never required when + running the + <link linkend='ref-tasks-devshell'><filename>do_devshell</filename></link> + task is because the + <filename>[</filename><ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>nostamp</filename></ulink><filename>]</filename> + variable flag is already set for the task. + </note> + The following example shows one way you can use the + <filename>-f</filename> option: <literallayout class='monospaced'> $ bitbake matchbox-desktop . . - <replaceable>make some changes to the source code in the work directory</replaceable> + make some changes to the source code in the work directory . . $ bitbake matchbox-desktop -c compile -f @@ -236,6 +657,50 @@ </para> <para> + Another, shorter way to rerun a task and all + <link linkend='normal-recipe-build-tasks'>normal recipe build tasks</link> + that depend on it is to use the <filename>-C</filename> + option. + <note> + This option is upper-cased and is separate from the + <filename>-c</filename> option, which is lower-cased. + </note> + Using this option invalidates the given task and then runs the + <link linkend='ref-tasks-build'><filename>do_build</filename></link> + task, which is the default task if no task is given, and the + tasks on which it depends. + You could replace the final two commands in the previous example + with the following single command: + <literallayout class='monospaced'> + $ bitbake matchbox-desktop -C compile + </literallayout> + Internally, the <filename>-f</filename> and + <filename>-C</filename> options work by tainting (modifying) the + input checksum of the specified task. + This tainting indirectly causes the task and its + dependent tasks to be rerun through the normal task dependency + mechanisms. + <note> + BitBake explicitly keeps track of which tasks have been + tainted in this fashion, and will print warnings such as the + following for builds involving such tasks: + <literallayout class='monospaced'> + WARNING: /home/ulf/poky/meta/recipes-sato/matchbox-desktop/matchbox-desktop_2.1.bb.do_compile is tainted from a forced run + </literallayout> + The purpose of the warning is to let you know that the work + directory and build output might not be in the clean state they + would be in for a "normal" build, depending on what actions + you took. + To get rid of such warnings, you can remove the work directory + and rebuild the recipe, as follows: + <literallayout class='monospaced'> + $ bitbake matchbox-desktop -c clean + $ bitbake matchbox-desktop + </literallayout> + </note> + </para> + + <para> You can view a list of tasks in a given package by running the <filename>do_listtasks</filename> task as follows: <literallayout class='monospaced'> @@ -246,24 +711,77 @@ </para> </section> - <section id='usingpoky-debugging-dependencies'> - <title>Dependency Graphs</title> + <section id='checking-for-missing-build-time-dependencies'> + <title>Checking for Missing Build-Time Dependencies</title> + + <para> + A recipe might build successfully even though some of its + build-time dependencies are missing from + <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>. + Following are the two most common ways in which that can happen: + <itemizedlist> + <listitem><para> + The build-time dependency just happens to already exist in + the staging sysroot + (<link linkend='var-STAGING_DIR_HOST'><filename>STAGING_DIR_HOST</filename></link>) + by the time the recipe is built. + This situation occurs when the build-time dependency is + built earlier during recipe processing. + </para></listitem> + <listitem><para> + The component built by the recipe conditionally enables + functionality depending on whether it can find the + build-time dependency in the staging sysroot. + If the build-time dependency is missing, the corresponding + functionality is disabled. + This condition is known as a "floating dependency". + </para></listitem> + </itemizedlist> + </para> <para> - Sometimes it can be hard to see why BitBake wants to build - other packages before building a given package you have specified. - The <filename>bitbake -g <replaceable>targetname</replaceable></filename> command - creates the <filename>pn-buildlist</filename>, - <filename>pn-depends.dot</filename>, - <filename>package-depends.dot</filename>, and - <filename>task-depends.dot</filename> files in the current - directory. - These files show what will be built and the package and task - dependencies, which are useful for debugging problems. - You can use the - <filename>bitbake -g -u depexp <replaceable>targetname</replaceable></filename> - command to display the results in a more human-readable form. + Because dealing with the second case is more complex, focus will + be on the first case. + The + <link linkend='ref-classes-insane'><filename>build-deps</filename></link> + QA check checks that every library the component linked against is + declared as a build-time dependency. + If that is not the case, then the first situation described in the + previous list exists, and <filename>build-deps</filename> reports + a missing build-time dependency. </para> + + <para> + Another, more manual, way to check a recipe for missing build-time + dependencies of the first type is to build with an empty staging + sysroot. + This method can also find missing build-time dependencies + that are not in the form of libraries, which the + <filename>build-deps</filename> QA check is unable to find. + </para> + + <para> + An easy way to empty the staging sysroots is to simply remove + <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>, + which is usually + <filename>${</filename><link linkend='var-BUILDDIR'><filename>BUILDDIR</filename></link><filename>}/tmp</filename>, + as it includes the staging sysroots. + Another, faster method to empty the staging sysroots is to use the + <filename>scripts/wipe-sysroot</filename> script, + which removes just the staging sysroots and keeps everything else + in <filename>TMPDIR</filename>. + <note> + The <filename>scripts/</filename> directory appears in + <filename>PATH</filename> after running the build environment + initialization script (i.e. + <link linkend='structure-core-script'><filename>oe-init-build-env</filename></link> + or + <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>), + which results in the ability to to run + <filename>wipe-sysroot</filename> immediately. + </note> + </para> + </section> <section id='usingpoky-debugging-bitbake'> @@ -336,48 +854,76 @@ </para> </section> - <section id='usingpoky-debugging-variables'> - <title>Variables</title> - <para> - You can use the <filename>-e</filename> BitBake option to - display the parsing environment for a configuration. - The following displays the general parsing environment: - <literallayout class='monospaced'> - $ bitbake -e - </literallayout> - This next example shows the parsing environment for a specific - recipe: - <literallayout class='monospaced'> - $ bitbake -e <replaceable>recipename</replaceable> - </literallayout> - </para> - </section> - <section id='recipe-logging-mechanisms'> <title>Recipe Logging Mechanisms</title> <para> - Best practices exist while writing recipes that both log build progress and - act on build conditions such as warnings and errors. - Both Python and Bash language bindings exist for the logging mechanism: + The Yocto Project provides several logging functions for producing + debugging output and reporting errors and warnings. + For Python functions, the following logging functions exist. + All of these functions log to + <filename>${T}/log.do_</filename><replaceable>task</replaceable>, + and can also log to standard output (stdout) with the right + settings: <itemizedlist> - <listitem><para><emphasis>Python:</emphasis> For Python functions, BitBake - supports several loglevels: <filename>bb.fatal</filename>, - <filename>bb.error</filename>, <filename>bb.warn</filename>, - <filename>bb.note</filename>, <filename>bb.plain</filename>, - and <filename>bb.debug</filename>.</para></listitem> - <listitem><para><emphasis>Bash:</emphasis> For Bash functions, the same set - of loglevels exist and are accessed with a similar syntax: - <filename>bbfatal</filename>, <filename>bberror</filename>, - <filename>bbwarn</filename>, <filename>bbnote</filename>, - <filename>bbplain</filename>, and <filename>bbdebug</filename>.</para></listitem> + <listitem><para> + <filename>bb.plain(</filename><replaceable>msg</replaceable><filename>)</filename>: + Writes <replaceable>msg</replaceable> as is to the log while + also logging to stdout. + </para></listitem> + <listitem><para> + <filename>bb.note(</filename><replaceable>msg</replaceable><filename>)</filename>: + Writes "NOTE: <replaceable>msg</replaceable>" to the log. + Also logs to stdout if BitBake is called with "-v". + </para></listitem> + <listitem><para> + <filename>bb.debug(</filename><replaceable>level</replaceable><filename>, </filename><replaceable>msg</replaceable><filename>)</filename>: + Writes "DEBUG: <replaceable>msg</replaceable>" to the log. + Also logs to stdout if the log level is greater than or + equal to <replaceable>level</replaceable>. + See the + "<ulink url='&YOCTO_DOCS_BB_URL;#usage-and-syntax'>-D</ulink>" + option in the BitBake User Manual for more information. + </para></listitem> + <listitem><para> + <filename>bb.warn(</filename><replaceable>msg</replaceable><filename>)</filename>: + Writes "WARNING: <replaceable>msg</replaceable>" to the log + while also logging to stdout. + </para></listitem> + <listitem><para> + <filename>bb.error(</filename><replaceable>msg</replaceable><filename>)</filename>: + Writes "ERROR: <replaceable>msg</replaceable>" to the log + while also logging to stdout. + <note> + Calling this function does not cause the task to fail. + </note> + </para></listitem> + <listitem><para> + <filename>bb.fatal(</filename><replaceable>msg</replaceable><filename>)</filename>: + This logging function is similar to + <filename>bb.error(</filename><replaceable>msg</replaceable><filename>)</filename> + but also causes the calling task to fail. + <note> + <filename>bb.fatal()</filename> raises an exception, + which means you do not need to put a "return" + statement after the function. + </note> + </para></listitem> </itemizedlist> </para> <para> - For guidance on how logging is handled in both Python and Bash recipes, see the - <filename>logging.bbclass</filename> file in the + The same logging functions are also available in shell functions, + under the names + <filename>bbplain</filename>, <filename>bbnote</filename>, + <filename>bbdebug</filename>, <filename>bbwarn</filename>, + <filename>bberror</filename>, and <filename>bbfatal</filename>. + The + <link linkend='ref-classes-logging'><filename>logging</filename></link> + class implements these functions. + See that class in the <filename>meta/classes</filename> folder of the - <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> + for information. </para> <section id='logging-with-python'> @@ -456,18 +1002,92 @@ <para> Here are some other tips that you might find useful: <itemizedlist> - <listitem><para>When adding new packages, it is worth watching for - undesirable items making their way into compiler command lines. - For example, you do not want references to local system files like - <filename>/usr/lib/</filename> or <filename>/usr/include/</filename>. + <listitem><para> + When adding new packages, it is worth watching for + undesirable items making their way into compiler command + lines. + For example, you do not want references to local system + files like + <filename>/usr/lib/</filename> or + <filename>/usr/include/</filename>. </para></listitem> - <listitem><para>If you want to remove the <filename>psplash</filename> + <listitem><para> + If you want to remove the <filename>psplash</filename> boot splashscreen, - add <filename>psplash=false</filename> to the kernel command line. + add <filename>psplash=false</filename> to the kernel + command line. Doing so prevents <filename>psplash</filename> from loading and thus allows you to see the console. It is also possible to switch out of the splashscreen by - switching the virtual console (e.g. Fn+Left or Fn+Right on a Zaurus). + switching the virtual console (e.g. Fn+Left or Fn+Right + on a Zaurus). + </para></listitem> + <listitem><para> + Removing + <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> + (usually <filename>tmp/</filename>, within the + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>) + can often fix temporary build issues. + Removing <filename>TMPDIR</filename> is usually a + relatively cheap operation, because task output will be + cached in + <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link> + (usually <filename>sstate-cache/</filename>, which is + also in the Build Directory). + <note> + Removing <filename>TMPDIR</filename> might be a + workaround rather than a fix. + Consequently, trying to determine the underlying cause + of an issue before removing the directory is a good + idea. + </note> + </para></listitem> + <listitem><para> + Understanding how a feature is used in practice within + existing recipes can be very helpful. + It is recommended that you configure some method that + allows you to quickly search through files.</para> + + <para>Using GNU Grep, you can use the following shell + function to recursively search through common + recipe-related files, skipping binary files, + <filename>.git</filename> directories, and the + Build Directory (assuming its name starts with + "build"): + <literallayout class='monospaced'> + g() { + grep -Ir \ + --exclude-dir=.git \ + --exclude-dir='build*' \ + --include='*.bb*' \ + --include='*.inc*' \ + --include='*.conf*' \ + --include='*.py*' \ + "$@" + } + </literallayout> + Following are some usage examples: + <literallayout class='monospaced'> + $ g FOO # Search recursively for "FOO" + $ g -i foo # Search recursively for "foo", ignoring case + $ g -w FOO # Search recursively for "FOO" as a word, ignoring e.g. "FOOBAR" + </literallayout> + If figuring out how some feature works requires a lot of + searching, it might indicate that the documentation should + be extended or improved. + In such cases, consider filing a documentation bug using + the Yocto Project implementation of + <ulink url='https://bugzilla.yoctoproject.org/'>Bugzilla</ulink>. + For general information on how to submit a bug against + the Yocto Project, see the + "<ulink url='&YOCTO_DOCS_DEV_URL;#tracking-bugs'>Tracking Bugs</ulink>" + section in the Yocto Project Development Manual. + <note> + The manuals might not be the right place to document + variables that are purely internal and have a limited + scope (e.g. internal variables used to implement a + single <filename>.bbclass</filename> file). + </note> </para></listitem> </itemizedlist> </para> @@ -951,6 +1571,19 @@ * PR changed from "r0" to "r1" * PV changed from "0.1.10" to "0.1.12" </literallayout> + <note> + The <filename>buildhistory-diff</filename> tool requires + the <filename>GitPython</filename> package. + Be sure to install it using Pip3 as follows: + <literallayout class='monospaced'> + $ pip3 install GitPython --user + </literallayout> + Alternatively, you can install + <filename>python3-git</filename> using the appropriate + distribution package manager (e.g. + <filename>apt-get</filename>, <filename>dnf</filename>, or + <filename>zipper</filename>). + </note> </para> <para> diff --git a/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-add-flow.png b/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-add-flow.png Binary files differindex c09e60e35..985ac331f 100644 --- a/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-add-flow.png +++ b/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-add-flow.png diff --git a/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-modify-flow.png b/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-modify-flow.png Binary files differindex cd06c0181..fd684ffbe 100644 --- a/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-modify-flow.png +++ b/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-modify-flow.png diff --git a/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-upgrade-flow.png b/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-upgrade-flow.png Binary files differnew file mode 100644 index 000000000..65474dad0 --- /dev/null +++ b/import-layers/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-upgrade-flow.png diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-customizing.xml b/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-customizing.xml index 79326077f..e8a8b8cc9 100644 --- a/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-customizing.xml +++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-customizing.xml @@ -381,6 +381,19 @@ section for more information. </note> </para> + + <para> + You can explicitly control whether or not to include the toolchain + when you build an SDK by setting the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_TOOLCHAIN'><filename>SDK_INCLUDE_TOOLCHAIN</filename></ulink> + variable to "1". + In particular, it is useful to include the toolchain when you + have set <filename>SDK_EXT_TYPE</filename> to + "minimal", which by default, excludes the toolchain. + Also, it is helpful if you are building a small SDK for use with + an IDE, such as Eclipse, or some other tool where you do not want + to take extra steps to install a toolchain. + </para> </section> </appendix> <!-- diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-mars.xml b/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-mars.xml new file mode 100644 index 000000000..144e0720a --- /dev/null +++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-mars.xml @@ -0,0 +1,871 @@ +<!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; ] > + +<appendix id='sdk-appendix-mars'> + <title>Using Eclipse Mars</title> + + <para> + This release of the Yocto Project supports both the Neon and Mars + versions of the Eclipse IDE. + This appendix presents information that describes how to obtain and + configure the Mars version of Eclipse. + It also provides a basic project example that you can work through + from start to finish. + For general information on using the Eclipse IDE and the Yocto + Project Eclipse Plug-In, see the + "<link linkend='sdk-developing-applications-using-eclipse'>Developing Applications Using <trademark class='trade'>Eclipse</trademark></link>" + section. + </para> + + <section id='mars-setting-up-the-eclipse-ide'> + <title>Setting Up the Mars Version of the Eclipse IDE</title> + + <para> + To develop within the Eclipse IDE, you need to do the following: + <orderedlist> + <listitem><para>Install the Mars version of the Eclipse + IDE.</para></listitem> + <listitem><para>Configure the Eclipse IDE. + </para></listitem> + <listitem><para>Install the Eclipse Yocto Plug-in. + </para></listitem> + <listitem><para>Configure the Eclipse Yocto Plug-in. + </para></listitem> + </orderedlist> + <note> + Do not install Eclipse from your distribution's package + repository. + Be sure to install Eclipse from the official Eclipse + download site as directed in the next section. + </note> + </para> + + <section id='mars-installing-eclipse-ide'> + <title>Installing the Mars Eclipse IDE</title> + + <para> + Follow these steps to locate, install, and configure + Mars Eclipse: + <orderedlist> + <listitem><para><emphasis>Locate the Mars Download:</emphasis> + Open a browser and go to + <ulink url='http://www.eclipse.org/mars/'>http://www.eclipse.org/mars/</ulink>. + </para></listitem> + <listitem><para><emphasis>Download the Tarball:</emphasis> + Click the "Download" button and then use the "Linux + for Eclipse IDE for C++ Developers" + appropriate for your development system + (e.g. + <ulink url='http://www.eclipse.org/downloads/download.php?file=/technology/epp/downloads/release/mars/2/eclipse-cpp-mars-2-linux-gtk-x86_64.tar.gz'>64-bit under Linux for Eclipse IDE for C++ Developers</ulink> + if your development system is a Linux 64-bit machine. + </para></listitem> + <listitem><para><emphasis>Unpack the Tarball:</emphasis> + Move to a clean directory and unpack the tarball. + Here is an example: + <literallayout class='monospaced'> + $ cd ~ + $ tar -xzvf ~/Downloads/eclipse-cpp-mars-2-linux-gtk-x86_64.tar.gz + </literallayout> + Everything unpacks into a folder named "Eclipse". + </para></listitem> + <listitem><para><emphasis>Launch Eclipse:</emphasis> + Double click the "Eclipse" file in the folder to + launch Eclipse. + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='mars-configuring-the-mars-eclipse-ide'> + <title>Configuring the Mars Eclipse IDE</title> + + <para> + Follow these steps to configure the Mars Eclipse IDE. + <note> + Depending on how you installed Eclipse and what you have + already done, some of the options will not appear. + If you cannot find an option as directed by the manual, + it has already been installed. + </note> + <orderedlist> + <listitem><para>Be sure Eclipse is running and + you are in your workbench. + </para></listitem> + <listitem><para>Select "Install New Software" from + the "Help" pull-down menu. + </para></listitem> + <listitem><para>Select + "Mars - http://download.eclipse.org/releases/mars" + from the "Work with:" pull-down menu. + </para></listitem> + <listitem><para>Expand the box next to + "Linux Tools" and select "C/C++ Remote + (Over TCF/TE) Run/Debug Launcher" and + "TM Terminal". + </para></listitem> + <listitem><para>Expand the box next to "Mobile and + Device Development" and select the following + boxes: + <literallayout class='monospaced'> + C/C++ Remote (Over TCF/TE) Run/Debug Launcher + Remote System Explorer User Actions + TM Terminal + TCF Remote System Explorer add-in + TCF Target Explorer + </literallayout> + </para></listitem> + <listitem><para>Expand the box next to + "Programming Languages" and select the + following boxes: + <literallayout class='monospaced'> + C/C++ Autotools Support + C/C++ Development Tools SDK + </literallayout> + </para></listitem> + <listitem><para> + Complete the installation by clicking through + appropriate "Next" and "Finish" buttons. + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='mars-installing-the-eclipse-yocto-plug-in'> + <title>Installing or Accessing the Mars Eclipse Yocto Plug-in</title> + + <para> + You can install the Eclipse Yocto Plug-in into the Eclipse + IDE one of two ways: use the Yocto Project's Eclipse + Update site to install the pre-built plug-in or build and + install the plug-in from the latest source code. + </para> + + <section id='mars-new-software'> + <title>Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site</title> + + <para> + To install the Mars Eclipse Yocto Plug-in from the update + site, follow these steps: + <orderedlist> + <listitem><para>Start up the Eclipse IDE. + </para></listitem> + <listitem><para>In Eclipse, select "Install New + Software" from the "Help" menu. + </para></listitem> + <listitem><para>Click "Add..." in the "Work with:" + area. + </para></listitem> + <listitem><para>Enter + <filename>&ECLIPSE_DL_PLUGIN_URL;/mars</filename> + in the URL field and provide a meaningful name + in the "Name" field. + </para></listitem> + <listitem><para>Click "OK" to have the entry added + to the "Work with:" drop-down list. + </para></listitem> + <listitem><para>Select the entry for the plug-in + from the "Work with:" drop-down list. + </para></listitem> + <listitem><para>Check the boxes next to the following: + <literallayout class='monospaced'> + Yocto Project SDK Plug-in + Yocto Project Documentation plug-in + </literallayout> + </para></listitem> + <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> + </section> + + <section id='mars-zip-file-method'> + <title>Installing the Plug-in Using the Latest Source Code</title> + + <para> + To install the Mars Eclipse Yocto Plug-in from the latest + source code, follow these steps: + <orderedlist> + <listitem><para>Be sure your development system + has JDK 1.7+ + </para></listitem> + <listitem><para>install X11-related packages: + <literallayout class='monospaced'> + $ sudo apt-get install xauth + </literallayout> + </para></listitem> + <listitem><para>In a new terminal shell, create a Git + repository with: + <literallayout class='monospaced'> + $ cd ~ + $ git clone git://git.yoctoproject.org/eclipse-poky + </literallayout> + </para></listitem> + <listitem><para>Use Git to checkout the correct + tag: + <literallayout class='monospaced'> + $ cd ~/eclipse-poky + $ git checkout mars/yocto-&DISTRO; + </literallayout> + This puts you in a detached HEAD state, which + is fine since you are only going to be building + and not developing. + </para></listitem> + <listitem><para>Change to the + <filename>scripts</filename> + directory within the Git repository: + <literallayout class='monospaced'> + $ cd scripts + </literallayout> + </para></listitem> + <listitem><para>Set up the local build environment + by running the setup script: + <literallayout class='monospaced'> + $ ./setup.sh + </literallayout> + 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. + </para></listitem> + <listitem><para>Run the <filename>build.sh</filename> + script as directed. + Be sure to provide the tag name, documentation + branch, and a release name.</para> + <para> + Following is an example: + <literallayout class='monospaced'> + $ ECLIPSE_HOME=/home/scottrif/eclipse-poky/scripts/eclipse ./build.sh -l mars/yocto-&DISTRO; master yocto-&DISTRO; 2>&1 | tee build.log + </literallayout> + The previous example command adds the tag you + need for <filename>mars/yocto-&DISTRO;</filename> + to <filename>HEAD</filename>, then tells the + build script to use the local (-l) Git checkout + for the build. + After running the script, the file + <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. + </para></listitem> + <listitem><para>Click "Add". + </para></listitem> + <listitem><para>Provide anything you want in the + "Name" field. + </para></listitem> + <listitem><para>Click "Archive" and browse to the + ZIP file you built earlier. + This ZIP file should not be "unzipped", and must + be the <filename>*archive.zip</filename> file + created by running the + <filename>build.sh</filename> script. + </para></listitem> + <listitem><para>Click the "OK" button. + </para></listitem> + <listitem><para>Check the boxes that appear in + the installation window to install the + following: + <literallayout class='monospaced'> + Yocto Project SDK Plug-in + Yocto Project Documentation plug-in + </literallayout> + </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>Restart the Eclipse IDE if + necessary. + </para></listitem> + </orderedlist> + </para> + + <para> + At this point you should be able to configure the + Eclipse Yocto Plug-in as described in the + "<link linkend='mars-configuring-the-eclipse-yocto-plug-in'>Configuring the Mars Eclipse Yocto Plug-in</link>" + section.</para> + </section> + </section> + + <section id='mars-configuring-the-eclipse-yocto-plug-in'> + <title>Configuring the Mars Eclipse Yocto Plug-in</title> + + <para> + Configuring the Mars Eclipse Yocto Plug-in involves setting the + Cross Compiler options and the Target options. + The configurations you choose become the default settings + for all projects. + You do have opportunities to change them later when + you configure the project (see the following section). + </para> + + <para> + To start, you need to do the following from within the + Eclipse IDE: + <itemizedlist> + <listitem><para>Choose "Preferences" from the + "Window" menu to display the Preferences Dialog. + </para></listitem> + <listitem><para>Click "Yocto Project SDK" to display + the configuration screen. + </para></listitem> + </itemizedlist> + The following sub-sections describe how to configure the + the plug-in. + <note> + Throughout the descriptions, a start-to-finish example for + preparing a QEMU image for use with Eclipse is referenced + as the "wiki" and is linked to the example on the + <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'> Cookbook guide to Making an Eclipse Debug Capable Image</ulink> + wiki page. + </note> + </para> + + <section id='mars-configuring-the-cross-compiler-options'> + <title>Configuring the Cross-Compiler Options</title> + + <para> + Cross Compiler options enable Eclipse to use your specific + cross compiler toolchain. + To configure these options, you must select + the type of toolchain, point to the toolchain, specify + the sysroot location, and select the target + architecture. + <itemizedlist> + <listitem><para><emphasis>Selecting the Toolchain Type:</emphasis> + Choose between + <filename>Standalone pre-built toolchain</filename> + and + <filename>Build system derived toolchain</filename> + for Cross Compiler Options. + <itemizedlist> + <listitem><para><emphasis> + <filename>Standalone Pre-built Toolchain:</filename></emphasis> + Select this type when you are using + a stand-alone cross-toolchain. + For example, suppose you are an + application developer and do not + need to build a target image. + Instead, you just want to use an + architecture-specific toolchain on + an existing kernel and target root + filesystem. + In other words, you have downloaded + and installed a pre-built toolchain + for an existing image. + </para></listitem> + <listitem><para><emphasis> + <filename>Build System Derived Toolchain:</filename></emphasis> + Select this type if you built the + toolchain as part of the + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. + When you select + <filename>Build system derived toolchain</filename>, + you are using the toolchain built and + bundled inside the Build Directory. + For example, suppose you created a + suitable image using the steps in the + <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>. + In this situation, you would select the + <filename>Build system derived toolchain</filename>. + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para><emphasis>Specify the Toolchain Root Location:</emphasis> + If you are using a stand-alone pre-built + toolchain, you should be pointing to where it is + installed (e.g. + <filename>/opt/poky/&DISTRO;</filename>). + See the + "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>" + section for information about how the SDK is + installed.</para> + <para>If you are using a build system derived + toolchain, the path you provide for the + <filename>Toolchain Root Location</filename> + field is the + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> + from which you run the + <filename>bitbake</filename> command (e.g + <filename>/home/scottrif/poky/build</filename>).</para> + <para>For more information, see the + "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>" + section. + </para></listitem> + <listitem><para><emphasis>Specify Sysroot Location:</emphasis> + This location is where the root filesystem for + the target hardware resides. + </para> + <para>This location depends on where you + separately extracted and installed the target + filesystem. + As an example, suppose you prepared an image + using the steps in the + <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>. + If so, the <filename>MY_QEMU_ROOTFS</filename> + directory is found in the + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> + and you would browse to and select that directory + (e.g. <filename>/home/scottrif/build/MY_QEMU_ROOTFS</filename>). + </para> + <para>For more information on how to install the + toolchain and on how to extract and install the + sysroot filesystem, see the + "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>" + section. + </para></listitem> + <listitem><para><emphasis>Select the Target Architecture:</emphasis> + The target architecture is the type of hardware + you are going to use or emulate. + Use the pull-down + <filename>Target Architecture</filename> menu + to make your selection. + The pull-down menu should have the supported + architectures. + If the architecture you need is not listed in + the menu, you will need to build the image. + See the + "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>" + section of the Yocto Project Quick Start for + more information. + You can also see the + <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='mars-configuring-the-target-options'> + <title>Configuring the Target Options</title> + + <para> + You can choose to emulate hardware using the QEMU + emulator, or you can choose to run your image on actual + hardware. + <itemizedlist> + <listitem><para><emphasis>QEMU:</emphasis> + Select this option if you will be using the + QEMU emulator. + If you are using the emulator, you also need to + locate the kernel and specify any custom + options.</para> + <para>If you selected the + <filename>Build system derived toolchain</filename>, + the target kernel you built will be located in + the + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> + in + <filename>tmp/deploy/images/<replaceable>machine</replaceable></filename> + directory. + As an example, suppose you performed the steps in + the + <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>. + In this case, you specify your Build Directory path + followed by the image (e.g. + <filename>/home/scottrif/poky/build/tmp/deploy/images/qemux86/bzImage-qemux86.bin</filename>). + </para> + <para>If you selected the standalone pre-built + toolchain, the pre-built image you downloaded is + located in the directory you specified when you + downloaded the image.</para> + <para>Most custom options are for advanced QEMU + users to further customize their QEMU instance. + These options are specified between paired + angled brackets. + Some options must be specified outside the + brackets. + In particular, the options + <filename>serial</filename>, + <filename>nographic</filename>, and + <filename>kvm</filename> must all be outside the + brackets. + Use the <filename>man qemu</filename> command + to get help on all the options and their use. + The following is an example: + <literallayout class='monospaced'> + serial ‘<-m 256 -full-screen>’ + </literallayout></para> + <para> + Regardless of the mode, Sysroot is already + defined as part of the Cross-Compiler Options + configuration in the + <filename>Sysroot Location:</filename> field. + </para></listitem> + <listitem><para><emphasis>External HW:</emphasis> + Select this option if you will be using actual + hardware.</para></listitem> + </itemizedlist> + </para> + + <para> + Click the "Apply" and "OK" to save your plug-in + configurations. + </para> + </section> + </section> + </section> + + <section id='mars-creating-the-project'> + <title>Creating the Project</title> + + <para> + You can create two types of projects: Autotools-based, or + Makefile-based. + This section describes how to create Autotools-based projects + from within the Eclipse IDE. + For information on creating Makefile-based projects in a + terminal window, see the + "<link linkend='makefile-based-projects'>Makefile-Based Projects</link>" + section. + <note> + Do not use special characters in project names + (e.g. spaces, underscores, etc.). Doing so can + cause configuration to fail. + </note> + </para> + + <para> + To create a project based on a Yocto template and then display + the source code, follow these steps: + <orderedlist> + <listitem><para>Select "C Project" from the "File -> New" menu. + </para></listitem> + <listitem><para>Expand <filename>Yocto Project SDK Autotools Project</filename>. + </para></listitem> + <listitem><para>Select <filename>Hello World ANSI C Autotools Projects</filename>. + This is an Autotools-based project based on a Yocto + template. + </para></listitem> + <listitem><para>Put a name in the <filename>Project name:</filename> + field. + Do not use hyphens as part of the name + (e.g. <filename>hello</filename>). + </para></listitem> + <listitem><para>Click "Next". + </para></listitem> + <listitem><para>Add appropriate information in the various + fields. + </para></listitem> + <listitem><para>Click "Finish". + </para></listitem> + <listitem><para>If the "open perspective" prompt appears, + click "Yes" so that you in the C/C++ perspective. + </para></listitem> + <listitem><para>The left-hand navigation pane shows your + project. + You can display your source by double clicking the + project's source file. + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='mars-configuring-the-cross-toolchains'> + <title>Configuring the Cross-Toolchains</title> + + <para> + The earlier section, + "<link linkend='mars-configuring-the-eclipse-yocto-plug-in'>Configuring the Mars Eclipse Yocto Plug-in</link>", + sets up the default project configurations. + You can override these settings for a given project by following + these steps: + <orderedlist> + <listitem><para>Select "Yocto Project Settings" from + the "Project -> Properties" menu. + This selection brings up the Yocto Project Settings + Dialog and allows you to make changes specific to an + individual project.</para> + <para>By default, the Cross Compiler Options and Target + Options for a project are inherited from settings you + provided using the Preferences Dialog as described + earlier in the + "<link linkend='mars-configuring-the-eclipse-yocto-plug-in'>Configuring the Mars Eclipse Yocto Plug-in</link>" section. + The Yocto Project Settings Dialog allows you to override + those default settings for a given project. + </para></listitem> + <listitem><para>Make or verify your configurations for the + project and click "OK". + </para></listitem> + <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. + The script also runs <filename>libtoolize</filename>, + <filename>aclocal</filename>, + <filename>autoconf</filename>, + <filename>autoheader</filename>, + <filename>automake --a</filename>, and + <filename>./configure</filename>. + Click on the "Console" tab beneath your source code to + see the results of reconfiguring your project. + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='mars-building-the-project'> + <title>Building the Project</title> + + <para> + To build the project select "Build All" from the + "Project" menu. + The console should update and you can note the cross-compiler + you are using. + <note> + When building "Yocto Project SDK Autotools" projects, the + Eclipse IDE might display error messages for + Functions/Symbols/Types that cannot be "resolved", even when + the related include file is listed at the project navigator and + when the project is able to build. + For these cases only, it is recommended to add a new linked + folder to the appropriate sysroot. + Use these steps to add the linked folder: + <orderedlist> + <listitem><para> + Select the project. + </para></listitem> + <listitem><para> + Select "Folder" from the + <filename>File > New</filename> menu. + </para></listitem> + <listitem><para> + In the "New Folder" Dialog, select "Link to alternate + location (linked folder)". + </para></listitem> + <listitem><para> + Click "Browse" to navigate to the include folder inside + the same sysroot location selected in the Yocto Project + configuration preferences. + </para></listitem> + <listitem><para> + Click "OK". + </para></listitem> + <listitem><para> + Click "Finish" to save the linked folder. + </para></listitem> + </orderedlist> + </note> + </para> + </section> + + <section id='mars-starting-qemu-in-user-space-nfs-mode'> + <title>Starting QEMU in User-Space NFS Mode</title> + + <para> + To start the QEMU emulator from within Eclipse, follow these + steps: + <note> + See the + "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>" + chapter in the Yocto Project Development Manual + for more information on using QEMU. + </note> + <orderedlist> + <listitem><para>Expose and select "External Tools + Configurations ..." from the "Run -> External Tools" menu. + </para></listitem> + <listitem><para> + Locate and select your image in the navigation panel to + the left (e.g. <filename>qemu_i586-poky-linux</filename>). + </para></listitem> + <listitem><para> + Click "Run" to launch QEMU. + <note> + The host on which you are running QEMU must have + the <filename>rpcbind</filename> utility running to be + able to make RPC calls on a server on that machine. + If QEMU does not invoke and you receive error messages + involving <filename>rpcbind</filename>, follow the + suggestions to get the service running. + As an example, on a new Ubuntu 16.04 LTS installation, + you must do the following in order to get QEMU to + launch: + <literallayout class='monospaced'> + $ sudo apt-get install rpcbind + </literallayout> + After installing <filename>rpcbind</filename>, you + need to edit the + <filename>/etc/init.d/rpcbind</filename> file to + include the following line: + <literallayout class='monospaced'> + OPTIONS="-i -w" + </literallayout> + After modifying the file, you need to start the + service: + <literallayout class='monospaced'> + $ sudo service portmap restart + </literallayout> + </note> + </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 + needed for running in user-space NFS mode. + </para></listitem> + <listitem><para>Wait for QEMU to launch. + </para></listitem> + <listitem><para>Once QEMU launches, you can begin operating + within that environment. + 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. + The IP address of the QEMU machine appears in the + xterm window. + You can use this address to help you see which particular + IP address the instance of QEMU is using. + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='mars-deploying-and-debugging-the-application'> + <title>Deploying and Debugging the Application</title> + + <para> + Once the QEMU emulator is running the image, you can deploy + your application using the Eclipse IDE and then use + the emulator to perform debugging. + Follow these steps to deploy the application. + <note> + Currently, Eclipse does not support SSH port forwarding. + Consequently, if you need to run or debug a remote + application using the host display, you must create a + tunneling connection from outside Eclipse and keep + that connection alive during your work. + For example, in a new terminal, run the following: + <literallayout class='monospaced'> + $ ssh -XY <replaceable>user_name</replaceable>@<replaceable>remote_host_ip</replaceable> + </literallayout> + Using the above form, here is an example: + <literallayout class='monospaced'> + $ ssh -XY root@192.168.7.2 + </literallayout> + After running the command, add the command to be executed + in Eclipse's run configuration before the application + as follows: + <literallayout class='monospaced'> + export DISPLAY=:10.0 + </literallayout> + Be sure to not destroy the connection during your QEMU + session (i.e. do not + exit out of or close that shell). + </note> + <orderedlist> + <listitem><para>Select "Debug Configurations..." from the + "Run" menu.</para></listitem> + <listitem><para>In the left area, expand + <filename>C/C++Remote Application</filename>. + </para></listitem> + <listitem><para>Locate your project and select it to bring + up a new tabbed view in the Debug Configurations Dialog. + </para></listitem> + <listitem><para>Click on the "Debugger" tab to see the + cross-tool debugger you are using. + Be sure to change to the debugger perspective in Eclipse. + </para></listitem> + <listitem><para>Click on the "Main" tab. + </para></listitem> + <listitem><para>Create a new connection to the QEMU instance + by clicking on "new".</para></listitem> + <listitem><para>Select <filename>SSH</filename>, which means + Secure Socket Shell. + Optionally, you can select an TCF connection instead. + </para></listitem> + <listitem><para>Click "Next". + </para></listitem> + <listitem><para>Clear out the "Connection name" field and + enter any name you want for the connection. + </para></listitem> + <listitem><para>Put the IP address for the connection in + the "Host" field. + For QEMU, the default is <filename>192.168.7.2</filename>. + However, if a previous QEMU session did not exit + cleanly, the IP address increments (e.g. + <filename>192.168.7.3</filename>). + <note> + You can find the IP address for the current QEMU + session by looking in the xterm that opens when + you launch QEMU. + </note> + </para></listitem> + <listitem><para>Enter <filename>root</filename>, which + is the default for QEMU, for the "User" field. + Be sure to leave the password field empty. + </para></listitem> + <listitem><para>Click "Finish" to close the + New Connections Dialog. + </para></listitem> + <listitem><para>If necessary, use the drop-down menu now in the + "Connection" field and pick the IP Address you entered. + </para></listitem> + <listitem><para>Assuming you are connecting as the root user, + which is the default for QEMU x86-64 SDK images provided by + the Yocto Project, in the "Remote Absolute File Path for + C/C++ Application" field, browse to + <filename>/home/root</filename>. + You could also browse to any other path you have write + access to on the target such as + <filename>/usr/bin</filename>. + This location is where your application will be located on + the QEMU system. + If you fail to browse to and specify an appropriate + location, QEMU will not understand what to remotely + launch. + Eclipse is helpful in that it auto fills your application + name for you assuming you browsed to a directory. + <note> + If you are prompted to provide a username and to + optionally set a password, be sure you provide + "root" as the username and you leave the password + field blank. + </note> + </para></listitem> + <listitem><para> + Be sure you change to the "Debug" perspective in Eclipse. + </para></listitem> + <listitem><para>Click "Debug" + </para></listitem> + <listitem><para>Accept the debug perspective. + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='mars-using-Linuxtools'> + <title>Using Linuxtools</title> + + <para> + As mentioned earlier in the manual, performance tools exist + (Linuxtools) that enhance your development experience. + These tools are aids in developing and debugging applications and + images. + You can run these tools from within the Eclipse IDE through the + "Linuxtools" menu. + </para> + + <para> + For information on how to configure and use these tools, see + <ulink url='http://www.eclipse.org/linuxtools/'>http://www.eclipse.org/linuxtools/</ulink>. + </para> + </section> +</appendix> +<!-- +vim: expandtab tw=80 ts=4 +--> diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-obtain.xml b/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-obtain.xml index 3d4e364bf..3156f7725 100644 --- a/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-obtain.xml +++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-appendix-obtain.xml @@ -13,20 +13,20 @@ You can use existing, pre-built toolchains by locating and running an SDK installer script that ships with the Yocto Project. Using this method, you select and download an architecture-specific - toolchain installer and then run the script to hand-install the + SDK installer and then run the script to hand-install the toolchain. </para> <para> You can find SDK installers here: <itemizedlist> - <listitem><para><emphasis>Standard SDK Installers</emphasis> + <listitem><para><emphasis>Standard SDK Installers:</emphasis> Go to <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink> and find the folder that matches your host development system (i.e. <filename>i686</filename> for 32-bit machines or <filename>x86_64</filename> for 64-bit machines).</para> - <para>Go into that folder and download the toolchain installer + <para>Go into that folder and download the SDK installer whose name includes the appropriate target architecture. The toolchains provided by the Yocto Project are based off of the <filename>core-image-sato</filename> image and contain @@ -39,9 +39,14 @@ poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh </literallayout> </para></listitem> - <listitem><para><emphasis>Extensible SDK Installers</emphasis> - Installers for the extensible SDK are in + <listitem><para><emphasis>Extensible SDK Installers:</emphasis> + Installers for the extensible SDK are also located in <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>. + These installers have the string + <filename>ext</filename> as part of their names: + <literallayout class='monospaced'> + poky-glibc-x86_64-core-image-sato-core2-64-toolchain-ext-&DISTRO;.sh + </literallayout> </para></listitem> </itemizedlist> </para> @@ -51,8 +56,8 @@ <title>Building an SDK Installer</title> <para> - As an alternative to locating and downloading a toolchain installer, - you can build the toolchain installer assuming you have first sourced + As an alternative to locating and downloading a SDK installer, + you can build the SDK installer assuming you have first sourced the environment setup script. See the "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>" @@ -69,7 +74,7 @@ </para> <para> - To build the toolchain installer for a standard SDK and populate + To build the SDK installer for a standard SDK and populate the SDK image, use the following command: <literallayout class='monospaced'> $ bitbake <replaceable>image</replaceable> -c populate_sdk @@ -78,28 +83,38 @@ <literallayout class='monospaced'> $ bitbake <replaceable>image</replaceable> -c populate_sdk_ext </literallayout> - These commands result in a toolchain installer that contains the sysroot + These commands result in a SDK installer that contains the sysroot that matches your target root filesystem. </para> <para> - When the <filename>bitbake</filename> command completes, the toolchain + When the <filename>bitbake</filename> command completes, the SDK installer will be in <filename>tmp/deploy/sdk</filename> in the Build Directory. - <note> - By default, this toolchain does not build static binaries. - If you want to use the toolchain to build these types of libraries, - you need to be sure your image has the appropriate static - development libraries. - Use the - <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>glibc</filename> static - development libraries: - <literallayout class='monospaced'> + <note><title>Notes</title> + <itemizedlist> + <listitem><para> + By default, this toolchain does not build static binaries. + If you want to use the toolchain to build these types of + libraries, you need to be sure your image has the + appropriate static development libraries. + Use the + <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>glibc</filename> + static development libraries: + <literallayout class='monospaced'> IMAGE_INSTALL_append = " glibc-staticdev" - </literallayout> + </literallayout> + </para></listitem> + <listitem><para> + For additional information on building the installer, + see the + <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>Cookbook guide to Making an Eclipse Debug Capable Image</ulink> + wiki page. + </para></listitem> + </itemizedlist> </note> </para> </section> @@ -168,7 +183,7 @@ <para> The following figure shows the resulting directory structure after - you install the Standard SDK by running the <filename>.sh</filename> + you install the Standard SDK by running the <filename>*.sh</filename> SDK installation script: </para> @@ -191,7 +206,7 @@ is the directory where the SDK is installed. By default, this directory is <filename>/opt/poky/</filename>. And, <replaceable>version</replaceable> represents the specific - snapshot of the SDK (e.g. <filename>&DISTRO;+snapshot</filename>). + snapshot of the SDK (e.g. <filename>&DISTRO;</filename>). Furthermore, <replaceable>target</replaceable> represents the target architecture (e.g. <filename>i586</filename>) and <replaceable>host</replaceable> represents the development system's @@ -209,7 +224,7 @@ <para> The following figure shows the resulting directory structure after - you install the Extensible SDK by running the <filename>.sh</filename> + you install the Extensible SDK by running the <filename>*.sh</filename> SDK installation script: </para> diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-extensible.xml b/import-layers/yocto-poky/documentation/sdk-manual/sdk-extensible.xml index 3e11fc97d..1496476be 100644 --- a/import-layers/yocto-poky/documentation/sdk-manual/sdk-extensible.xml +++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-extensible.xml @@ -4,1300 +4,1628 @@ <chapter id='sdk-extensible'> -<title>Using the Extensible SDK</title> - -<para> - This chapter describes the extensible SDK and how to use it. - The extensible SDK makes it easy to add new applications and libraries - to an image, modify the source for an existing component, test - changes on the target hardware, and ease integration into the rest of the - <ulink url='&YOCTO_DOCS_DEV_URL;#build-system-term'>OpenEmbedded build system</ulink>. -</para> - -<para> - Information in this chapter covers features that are not part of the - standard SDK. - In other words, the chapter presents information unique to the - extensible SDK only. - For information on how to use the standard SDK, see the - "<link linkend='sdk-using-the-standard-sdk'>Using the Standard SDK</link>" - chapter. -</para> - -<section id='sdk-setting-up-to-use-the-extensible-sdk'> - <title>Setting Up to Use the Extensible SDK</title> + <title>Using the Extensible SDK</title> <para> - Getting set up to use the extensible SDK is identical to getting set - up to use the standard SDK. - You still need to locate and run the installer and then run the - environment setup script. - See the - "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>" - and the - "<link linkend='sdk-running-the-sdk-environment-setup-script'>Running the SDK Environment Setup Script</link>" - sections for general information. - The following items highlight the only differences between getting - set up to use the extensible SDK as compared to the standard SDK: - <itemizedlist> - <listitem><para><emphasis>Default Installation Directory:</emphasis> - By default, the extensible SDK installs into the - <filename>poky_sdk</filename> folder of your home directory. - As with the standard SDK, you can choose to install the - extensible SDK in any location when you run the installer. - However, unlike the standard SDK, the location you choose needs - to be writable for whichever users need to use the SDK, - since files will need to be written under that directory during - the normal course of operation. - </para></listitem> - <listitem><para><emphasis>Build Tools and Build System:</emphasis> - The extensible SDK installer performs additional tasks as - compared to the standard SDK installer. - The extensible SDK installer extracts build tools specific - to the SDK and the installer also prepares the internal build - system within the SDK. - Here is example output for running the extensible SDK - installer: - <literallayout class='monospaced'> - $ ./poky-glibc-x86_64-core-image-minimal-core2-64-toolchain-ext-2.1+snapshot.sh - Poky (Yocto Project Reference Distro) Extensible SDK installer version 2.1+snapshot - =================================================================================== - Enter target directory for SDK (default: ~/poky_sdk): - You are about to install the SDK to "/home/scottrif/poky_sdk". Proceed[Y/n]? Y - Extracting SDK......................................................................done - Setting it up... - Extracting buildtools... - Preparing build system... - done - SDK has been successfully set up and is ready to be used. - Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g. - $ . /home/scottrif/poky_sdk/environment-setup-core2-64-poky-linux - </literallayout> - </para></listitem> - </itemizedlist> - </para> - - <para> - After installing the SDK, you need to run the SDK environment setup - script. - Here is the output: - <literallayout class='monospaced'> - $ source environment-setup-core2-64-poky-linux - SDK environment now set up; additionally you may now run devtool to perform development tasks. - Run devtool --help for further details. - </literallayout> - Once you run the environment setup script, you have - <filename>devtool</filename> available. - </para> -</section> - -<section id='using-devtool-in-your-sdk-workflow'> - <title>Using <filename>devtool</filename> in Your SDK Workflow</title> - - <para> - The cornerstone of the extensible SDK is a command-line tool - called <filename>devtool</filename>. - This tool provides a number of features that help - you build, test and package software within the extensible SDK, and - optionally integrate it into an image built by the OpenEmbedded build - system. - </para> - - <para> - The <filename>devtool</filename> command line is organized similarly - to - <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink> in that it has a - number of sub-commands for each function. - You can run <filename>devtool --help</filename> to see all the - commands. - </para> - - <para> - Two <filename>devtool</filename> subcommands that provide - entry-points into development are: - <itemizedlist> - <listitem><para><emphasis><filename>devtool add</filename></emphasis>: - Assists in adding new software to be built. - </para></listitem> - <listitem><para><emphasis><filename>devtool modify</filename></emphasis>: - Sets up an environment to enable you to modify the source of - an existing component. - </para></listitem> - </itemizedlist> - As with the OpenEmbedded build system, "recipes" represent software - packages within <filename>devtool</filename>. - When you use <filename>devtool add</filename>, a recipe is - automatically created. - When you use <filename>devtool modify</filename>, the specified - existing recipe is used in order to determine where to get the source - code and how to patch it. - In both cases, an environment is set up so that when you build the - recipe a source tree that is under your control is used in order to - allow you to make changes to the source as desired. - By default, both new recipes and the source go into a "workspace" - directory under the SDK. + This chapter describes the extensible SDK and how to install it. + Information covers the pieces of the SDK, how to install it, and + presents a look at using the <filename>devtool</filename> + functionality. + The extensible SDK makes it easy to add new applications and libraries + to an image, modify the source for an existing component, test + changes on the target hardware, and ease integration into the rest of + the + <ulink url='&YOCTO_DOCS_DEV_URL;#build-system-term'>OpenEmbedded build system</ulink>. + <note> + For a side-by-side comparison of main features supported for an + extensible SDK as compared to a standard SDK, see the + "<link linkend='sdk-manual-intro'>Introduction</link>" + section. + </note> </para> <para> - The remainder of this section presents the - <filename>devtool add</filename> and - <filename>devtool modify</filename> workflows. + In addition to the functionality available through + <filename>devtool</filename>, you can alternatively make use of the + toolchain directly, for example from Makefile, Autotools, and + Eclipse-based projects. + See the + "<link linkend='sdk-working-projects'>Using the SDK Toolchain Directly</link>" + chapter for more information. </para> - <section id='sdk-use-devtool-to-add-an-application'> - <title>Use <filename>devtool add</filename> to Add an Application</title> - - <para> - The <filename>devtool add</filename> command generates - a new recipe based on existing source code. - This command takes advantage of the - <ulink url='&YOCTO_DOCS_DEV_URL;#devtool-the-workspace-layer-structure'>workspace</ulink> - layer that many <filename>devtool</filename> commands - use. - The command is flexible enough to allow you to extract source - code into both the workspace or a separate local Git repository - and to use existing code that does not need to be extracted. - </para> - - <para> - Depending on your particular scenario, the arguments and options - you use with <filename>devtool add</filename> form different - combinations. - The following diagram shows common development flows - you would use with the <filename>devtool add</filename> - command: - </para> + <section id='sdk-extensible-sdk-intro'> + <title>Why use the Extensible SDK and What is in It?</title> <para> - <imagedata fileref="figures/sdk-devtool-add-flow.png" align="center" /> + The extensible SDK provides a cross-development toolchain and + libraries tailored to the contents of a specific image. + You would use the Extensible SDK if you want a toolchain experience + supplemented with the powerful set of <filename>devtool</filename> + commands tailored for the Yocto Project environment. </para> <para> - <orderedlist> - <listitem><para><emphasis>Generating the New Recipe</emphasis>: - The top part of the flow shows three scenarios by which - you could use <filename>devtool add</filename> to - generate a recipe based on existing source code.</para> - - <para>In a shared development environment, it is - typical where other developers are responsible for - various areas of source code. - As a developer, you are probably interested in using - that source code as part of your development using - the Yocto Project. - All you need is access to the code, a recipe, and a - controlled area in which to do your work.</para> - - <para>Within the diagram, three possible scenarios - feed into the <filename>devtool add</filename> workflow: - <itemizedlist> - <listitem><para><emphasis>Left</emphasis>: - The left scenario represents a common situation - where the source code does not exist locally - and needs to be extracted. - In this situation, you just let it get - extracted to the default workspace - you do not - want it in some specific location outside of the - workspace. - Thus, everything you need will be located in the - workspace: - <literallayout class='monospaced'> - $ devtool add <replaceable>recipe fetchuri</replaceable> - </literallayout> - With this command, <filename>devtool</filename> - creates a recipe and an append file in the - workspace as well as extracts the upstream - source files into a local Git repository also - within the <filename>sources</filename> folder. - </para></listitem> - <listitem><para><emphasis>Middle</emphasis>: - The middle scenario also represents a situation where - the source code does not exist locally. - In this case, the code is again upstream - and needs to be extracted to some - local area - this time outside of the default - workspace. - As always, if required <filename>devtool</filename> creates - a Git repository locally during the extraction. - Furthermore, the first positional argument - <replaceable>srctree</replaceable> in this case - identifies where the - <filename>devtool add</filename> command - will locate the extracted code outside of the - workspace: - <literallayout class='monospaced'> - $ devtool add <replaceable>recipe srctree fetchuri</replaceable> - </literallayout> - In summary, the source code is pulled from - <replaceable>fetchuri</replaceable> and extracted - into the location defined by - <replaceable>srctree</replaceable> as a local - Git repository.</para> - - <para>Within workspace, <filename>devtool</filename> - creates both the recipe and an append file - for the recipe. - </para></listitem> - <listitem><para><emphasis>Right</emphasis>: - The right scenario represents a situation - where the source tree (srctree) has been - previously prepared outside of the - <filename>devtool</filename> workspace. - </para> - - <para>The following command names the recipe - and identifies where the existing source tree - is located: - <literallayout class='monospaced'> - $ devtool add <replaceable>recipe srctree</replaceable> - </literallayout> - The command examines the source code and creates - a recipe for it placing the recipe into the - workspace.</para> - - <para>Because the extracted source code already exists, - <filename>devtool</filename> does not try to - relocate it into the workspace - just the new - the recipe is placed in the workspace.</para> - - <para>Aside from a recipe folder, the command - also creates an append folder and places an initial - <filename>*.bbappend</filename> within. - </para></listitem> - </itemizedlist> - </para></listitem> - <listitem><para><emphasis>Edit the Recipe</emphasis>: - At this point, you can use <filename>devtool edit-recipe</filename> - to open up the editor as defined by the - <filename>$EDITOR</filename> environment variable - and modify the file: - <literallayout class='monospaced'> - $ devtool edit-recipe <replaceable>recipe</replaceable> - </literallayout> - From within the editor, you can make modifications to the - recipe that take affect when you build it later. - </para></listitem> - <listitem><para><emphasis>Build the Recipe or Rebuild the Image</emphasis>: - At this point in the flow, the next step you - take depends on what you are going to do with - the new code.</para> - <para>If you need to take the build output and eventually - move it to the target hardware, you would use - <filename>devtool build</filename>: - <literallayout class='monospaced'> - $ devtool build <replaceable>recipe</replaceable> - </literallayout></para> - <para>On the other hand, if you want an image to - contain the recipe's packages for immediate deployment - onto a device (e.g. for testing purposes), you can use - the <filename>devtool build-image</filename> command: - <literallayout class='monospaced'> - $ devtool build-image <replaceable>image</replaceable> - </literallayout> - </para></listitem> - <listitem><para><emphasis>Deploy the Build Output</emphasis>: - When you use the <filename>devtool build</filename> - command to build out your recipe, you probably want to - see if the resulting build output works as expected on target - hardware. - <note> - This step assumes you have a previously built - image that is already either running in QEMU or - running on actual hardware. - Also, it is assumed that for deployment of the image - to the target, SSH is installed in the image and if - the image is running on real hardware that you have - network access to and from your development machine. - </note> - You can deploy your build output to that target hardware by - using the <filename>devtool deploy-target</filename> command: - <literallayout class='monospaced'> - $ devtool deploy-target <replaceable>recipe target</replaceable> - </literallayout> - The <replaceable>target</replaceable> is a live target machine - running as an SSH server.</para> - - <para>You can, of course, also deploy the image you build - using the <filename>devtool build-image</filename> command - to actual hardware. - However, <filename>devtool</filename> does not provide a - specific command that allows you to do this. - </para></listitem> - <listitem><para><emphasis>Optionally Update the Recipe With Patch Files</emphasis>: - Once you are satisfied with the recipe, if you have made - any changes to the source tree that you want to have - applied by the recipe, you need to generate patches - from those changes. - You do this before moving the recipe - to its final layer and cleaning up the workspace area - <filename>devtool</filename> uses. - This optional step is especially relevant if you are - using or adding third-party software.</para> - <para>To convert commits created using Git to patch files, - use the <filename>devtool update-recipe</filename> command. - <note> - Any changes you want to turn into patches must be - committed to the Git repository in the source tree. - </note> - <literallayout class='monospaced'> - $ devtool update-recipe <replaceable>recipe</replaceable> - </literallayout> - </para></listitem> - <listitem><para><emphasis>Move the Recipe to its Permanent Layer</emphasis>: - Before cleaning up the workspace, you need to move the - final recipe to its permanent layer. - You must do this before using the - <filename>devtool reset</filename> command if you want to - retain the recipe. - </para></listitem> - <listitem><para><emphasis>Reset the Recipe</emphasis>: - As a final step, you can restore the state such that - standard layers and the upstream source is used to build - the recipe rather than data in the workspace. - To reset the recipe, use the <filename>devtool reset</filename> - command: - <literallayout class='monospaced'> - $ devtool reset <replaceable>recipe</replaceable> - </literallayout> - </para></listitem> - </orderedlist> + The installed extensible SDK consists of several files and + directories. + Basically, it contains an SDK environment setup script, some + configuration files, an internal build system, and the + <filename>devtool</filename> functionality. </para> </section> - <section id='sdk-devtool-use-devtool-modify-to-modify-the-source-of-an-existing-component'> - <title>Use <filename>devtool modify</filename> to Modify the Source of an Existing Component</title> + <section id='sdk-setting-up-to-use-the-extensible-sdk'> + <title>Setting Up to Use the Extensible SDK</title> <para> - The <filename>devtool modify</filename> command prepares the - way to work on existing code that already has a recipe in - place. - The command is flexible enough to allow you to extract code, - specify the existing recipe, and keep track of and gather any - patch files from other developers that are - associated with the code. + The first thing you need to do is install the SDK on your host + development machine by running the <filename>*.sh</filename> + installation script. </para> <para> - Depending on your particular scenario, the arguments and options - you use with <filename>devtool modify</filename> form different - combinations. - The following diagram shows common development flows - you would use with the <filename>devtool modify</filename> - command: + You can download a tarball installer, which includes the + pre-built toolchain, the <filename>runqemu</filename> + script, the internal build system, <filename>devtool</filename>, + and support files from the appropriate directory under + <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>. + Toolchains are available for 32-bit and 64-bit x86 development + systems from the <filename>i686</filename> and + <filename>x86_64</filename> directories, respectively. + The toolchains the Yocto Project provides are based off the + <filename>core-image-sato</filename> image and contain + libraries appropriate for developing against that image. + Each type of development system supports five or more target + architectures. </para> <para> - <imagedata fileref="figures/sdk-devtool-modify-flow.png" align="center" /> - </para> + The names of the tarball installer scripts are such that a + string representing the host system appears first in the + filename and then is immediately followed by a string + representing the target architecture. + An extensible SDK has the string "-ext" as part of the name. + <literallayout class='monospaced'> + poky-glibc-<replaceable>host_system</replaceable>-<replaceable>image_type</replaceable>-<replaceable>arch</replaceable>-toolchain-ext-<replaceable>release_version</replaceable>.sh - <para> - <orderedlist> - <listitem><para><emphasis>Preparing to Modify the Code</emphasis>: - The top part of the flow shows three scenarios by which - you could use <filename>devtool modify</filename> to - prepare to work on source files. - Each scenario assumes the following: - <itemizedlist> - <listitem><para>The recipe exists in some layer external - to the <filename>devtool</filename> workspace. - </para></listitem> - <listitem><para>The source files exist upstream in an - un-extracted state or locally in a previously - extracted state. - </para></listitem> - </itemizedlist> - The typical situation is where another developer has - created some layer for use with the Yocto Project and - their recipe already resides in that layer. - Furthermore, their source code is readily available - either upstream or locally. - <itemizedlist> - <listitem><para><emphasis>Left</emphasis>: - The left scenario represents a common situation - where the source code does not exist locally - and needs to be extracted. - In this situation, the source is extracted - into the default workspace location. - The recipe, in this scenario, is in its own - layer outside the workspace - (i.e. - <filename>meta-</filename><replaceable>layername</replaceable>). - </para> - - <para>The following command identifies the recipe - and by default extracts the source files: - <literallayout class='monospaced'> - $ devtool modify <replaceable>recipe</replaceable> - </literallayout> - Once <filename>devtool</filename>locates the recipe, - it uses the - <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> - variable to locate the source code and - any local patch files from other developers are - located. - <note> - You cannot provide an URL for - <replaceable>srctree</replaceable> when using the - <filename>devtool modify</filename> command. - </note> - With this scenario, however, since no - <replaceable>srctree</replaceable> argument exists, the - <filename>devtool modify</filename> command by default - extracts the source files to a Git structure. - Furthermore, the location for the extracted source is the - default area within the workspace. - The result is that the command sets up both the source - code and an append file within the workspace with the - recipe remaining in its original location. - </para></listitem> - <listitem><para><emphasis>Middle</emphasis>: - The middle scenario represents a situation where - the source code also does not exist locally. - In this case, the code is again upstream - and needs to be extracted to some - local area as a Git repository. - The recipe, in this scenario, is again in its own - layer outside the workspace.</para> - - <para>The following command tells - <filename>devtool</filename> what recipe with - which to work and, in this case, identifies a local - area for the extracted source files that is outside - of the default workspace: - <literallayout class='monospaced'> - $ devtool modify <replaceable>recipe srctree</replaceable> - </literallayout> - As with all extractions, the command uses - the recipe's <filename>SRC_URI</filename> to locate the - source files. - Once the files are located, the command by default - extracts them. - Providing the <replaceable>srctree</replaceable> - argument instructs <filename>devtool</filename> where - place the extracted source.</para> - - <para>Within workspace, <filename>devtool</filename> - creates an append file for the recipe. - The recipe remains in its original location but - the source files are extracted to the location you - provided with <replaceable>srctree</replaceable>. - </para></listitem> - <listitem><para><emphasis>Right</emphasis>: - The right scenario represents a situation - where the source tree - (<replaceable>srctree</replaceable>) exists as a - previously extracted Git structure outside of - the <filename>devtool</filename> workspace. - In this example, the recipe also exists - elsewhere in its own layer. - </para> - - <para>The following command tells - <filename>devtool</filename> the recipe - with which to work, uses the "-n" option to indicate - source does not need to be extracted, and uses - <replaceable>srctree</replaceable> to point to the - previously extracted source files: - <literallayout class='monospaced'> - $ devtool modify -n <replaceable>recipe srctree</replaceable> - </literallayout> - </para> + Where: + <replaceable>host_system</replaceable> is a string representing your development system: - <para>Once the command finishes, it creates only - an append file for the recipe in the workspace. - The recipe and the source code remain in their - original locations. - </para></listitem> - </itemizedlist> - </para></listitem> - <listitem><para><emphasis>Edit the Source</emphasis>: - Once you have used the <filename>devtool modify</filename> - command, you are free to make changes to the source - files. - You can use any editor you like to make and save - your source code modifications. - </para></listitem> - <listitem><para><emphasis>Build the Recipe</emphasis>: - Once you have updated the source files, you can build - the recipe. - </para></listitem> - <listitem><para><emphasis>Deploy the Build Output</emphasis>: - When you use the <filename>devtool build</filename> - command to build out your recipe, you probably want to see - if the resulting build output works as expected on target - hardware. - <note> - This step assumes you have a previously built - image that is already either running in QEMU or - running on actual hardware. - Also, it is assumed that for deployment of the image - to the target, SSH is installed in the image and if - the image is running on real hardware that you have - network access to and from your development machine. - </note> - You can deploy your build output to that target hardware by - using the <filename>devtool deploy-target</filename> command: - <literallayout class='monospaced'> - $ devtool deploy-target <replaceable>recipe target</replaceable> - </literallayout> - The <replaceable>target</replaceable> is a live target machine - running as an SSH server.</para> - - <para>You can, of course, also deploy the image you build - using the <filename>devtool build-image</filename> command - to actual hardware. - However, <filename>devtool</filename> does not provide a - specific command that allows you to do this. - </para></listitem> - <listitem><para><emphasis>Optionally Create Patch Files for Your Changes</emphasis>: - After you have debugged your changes, you can - use <filename>devtool update-recipe</filename> to - generate patch files for all the commits you have - made. - <note> - Patch files are generated only for changes - you have committed. - </note> - <literallayout class='monospaced'> - $ devtool update-recipe <replaceable>recipe</replaceable> - </literallayout> - By default, the - <filename>devtool update-recipe</filename> command - creates the patch files in a folder named the same - as the recipe beneath the folder in which the recipe - resides, and updates the recipe's - <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> - statement to point to the generated patch files. - <note> - You can use the - "--append <replaceable>LAYERDIR</replaceable>" - option to cause the command to create append files - in a specific layer rather than the default - recipe layer. - </note> - </para></listitem> - <listitem><para><emphasis>Restore the Workspace</emphasis>: - The <filename>devtool reset</filename> restores the - state so that standard layers and upstream sources are - used to build the recipe rather than what is in the - workspace. - <literallayout class='monospaced'> - $ devtool reset <replaceable>recipe</replaceable> - </literallayout> - </para></listitem> - </orderedlist> - </para> - </section> -</section> + i686 or x86_64. -<section id='sdk-a-closer-look-at-devtool-add'> - <title>A Closer Look at <filename>devtool add</filename></title> + <replaceable>image_type</replaceable> is the image for which the SDK was built. - <para> - The <filename>devtool add</filename> command automatically creates a - recipe based on the source tree with which you provide it. - Currently, the command has support for the following: - <itemizedlist> - <listitem><para> - Autotools (<filename>autoconf</filename> and - <filename>automake</filename>) - </para></listitem> - <listitem><para> - CMake - </para></listitem> - <listitem><para> - Scons - </para></listitem> - <listitem><para> - <filename>qmake</filename> - </para></listitem> - <listitem><para> - Plain <filename>Makefile</filename> - </para></listitem> - <listitem><para> - Out-of-tree kernel module - </para></listitem> - <listitem><para> - Binary package (i.e. "-b" option) - </para></listitem> - <listitem><para> - Node.js module through - <filename>npm</filename> - </para></listitem> - <listitem><para> - Python modules that use <filename>setuptools</filename> - or <filename>distutils</filename> - </para></listitem> - </itemizedlist> - </para> + <replaceable>arch</replaceable> is a string representing the tuned target architecture: - <para> - Apart from binary packages, the determination of how a source tree - should be treated is automatic based on the files present within - that source tree. - For example, if a <filename>CMakeLists.txt</filename> file is found, - then the source tree is assumed to be using - CMake and is treated accordingly. - <note> - In most cases, you need to edit the automatically generated - recipe in order to make it build properly. - Typically, you would go through several edit and build cycles - until you can build the recipe. - Once the recipe can be built, you could use possible further - iterations to test the recipe on the target device. - </note> - </para> + i586, x86_64, powerpc, mips, armv7a or armv5te - <para> - The remainder of this section covers specifics regarding how parts - of the recipe are generated. - </para> + <replaceable>release_version</replaceable> is a string representing the release number of the + Yocto Project: - <section id='sdk-name-and-version'> - <title>Name and Version</title> + &DISTRO;, &DISTRO;+snapshot + </literallayout> + For example, the following SDK installer is for a 64-bit + development host system and a i586-tuned target architecture + based off the SDK for <filename>core-image-sato</filename> and + using the current &DISTRO; snapshot: + <literallayout class='monospaced'> + poky-glibc-x86_64-core-image-sato-i586-toolchain-ext-&DISTRO;.sh + </literallayout> + <note> + As an alternative to downloading an SDK, you can build the + SDK installer. + For information on building the installer, see the + "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>" + section. + Another helpful resource for building an installer is the + <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>Cookbook guide to Making an Eclipse Debug Capable Image</ulink> + wiki page. + This wiki page focuses on development when using the Eclipse + IDE. + </note> + </para> <para> - If you do not specify a name and version on the command - line, <filename>devtool add</filename> attempts to determine - the name and version of the software being built from - various metadata within the source tree. - Furthermore, the command sets the name of the created recipe - file accordingly. - If the name or version cannot be determined, the - <filename>devtool add</filename> command prints an error and - you must re-run the command with both the name and version - or just the name or version specified. + The SDK and toolchains are self-contained and by default are + installed into the <filename>poky_sdk</filename> folder in your + home directory. + You can choose to install the extensible SDK in any location when + you run the installer. + However, the location you choose needs to be writable for whichever + users need to use the SDK, since files will need to be written + under that directory during the normal course of operation. </para> <para> - Sometimes the name or version determined from the source tree - might be incorrect. - For such a case, you must reset the recipe: + The following command shows how to run the installer given a + toolchain tarball for a 64-bit x86 development host system and + a 64-bit x86 target architecture. + The example assumes the SDK installer is located in + <filename>~/Downloads/</filename>. + <note> + If you do not have write permissions for the directory + into which you are installing the SDK, the installer + notifies you and exits. + Be sure you have write permissions in the directory and + run the installer again. + </note> <literallayout class='monospaced'> - $ devtool reset -n <replaceable>recipename</replaceable> + $ ./poky-glibc-x86_64-core-image-minimal-core2-64-toolchain-ext-&DISTRO;.sh + Poky (Yocto Project Reference Distro) Extensible SDK installer version &DISTRO; + =================================================================================== + Enter target directory for SDK (default: ~/poky_sdk): + You are about to install the SDK to "/home/scottrif/poky_sdk". Proceed[Y/n]? Y + Extracting SDK......................................................................done + Setting it up... + Extracting buildtools... + Preparing build system... + done + SDK has been successfully set up and is ready to be used. + Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g. + $ . /home/scottrif/poky_sdk/environment-setup-core2-64-poky-linux </literallayout> - After running the <filename>devtool reset</filename> command, - you need to run <filename>devtool add</filename> again and - provide the name or the version. </para> </section> - <section id='sdk-dependency-detection-and-mapping'> - <title>Dependency Detection and Mapping</title> + <section id='sdk-running-the-extensible-sdk-environment-setup-script'> + <title>Running the Extensible SDK Environment Setup Script</title> <para> - The <filename>devtool add</filename> command attempts to - detect build-time dependencies and map them to other recipes - in the system. - During this mapping, the command fills in the names of those - recipes in the - <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink> - value within the recipe. - If a dependency cannot be mapped, then a comment is placed in - the recipe indicating such. - The inability to map a dependency might be caused because the - naming is not recognized or because the dependency simply is - not available. - For cases where the dependency is not available, you must use - the <filename>devtool add</filename> command to add an - additional recipe to satisfy the dependency and then come - back to the first recipe and add its name to - <filename>DEPENDS</filename>. + Once you have the SDK installed, you must run the SDK environment + setup script before you can actually use it. + This setup script resides in the directory you chose when you + installed the SDK, which is either the default + <filename>poky_sdk</filename> directory or the directory you + chose during installation. </para> <para> - If you need to add runtime dependencies, you can do so by - adding the following to your recipe: + Before running the script, be sure it is the one that matches the + architecture for which you are developing. + Environment setup scripts begin with the string + "<filename>environment-setup</filename>" and include as part of + their name the tuned target architecture. + As an example, the following commands set the working directory + to where the SDK was installed and then source the environment + setup script. + In this example, the setup script is for an IA-based + target machine using i586 tuning: <literallayout class='monospaced'> - RDEPENDS_${PN} += "dependency1 dependency2 ..." + $ cd /home/scottrif/poky_sdk + $ source environment-setup-core2-64-poky-linux + SDK environment now set up; additionally you may now run devtool to perform development tasks. + Run devtool --help for further details. + </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> - <note> - The <filename>devtool add</filename> command often cannot - distinguish between mandatory and optional dependencies. - Consequently, some of the detected dependencies might - in fact be optional. - When in doubt, consult the documentation or the configure - script for the software the recipe is building for further - details. - In some cases, you might find you can substitute the - dependency for an option to disable the associated - functionality passed to the configure script. - </note> </para> </section> - <section id='sdk-license-detection'> - <title>License Detection</title> + <section id='using-devtool-in-your-sdk-workflow'> + <title>Using <filename>devtool</filename> in Your SDK Workflow</title> <para> - The <filename>devtool add</filename> command attempts to - determine if the software you are adding is able to be - distributed under a common open-source license and sets the - <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink> - value accordingly. - You should double-check this value against the documentation - or source files for the software you are building and update - that <filename>LICENSE</filename> value if necessary. + The cornerstone of the extensible SDK is a command-line tool + called <filename>devtool</filename>. + This tool provides a number of features that help + you build, test and package software within the extensible SDK, and + optionally integrate it into an image built by the OpenEmbedded + build system. </para> <para> - The <filename>devtool add</filename> command also sets the - <ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></ulink> - value to point to all files that appear to be license-related. - However, license statements often appear in comments at the top - of source files or within documentation. - Consequently, you might need to amend the - <filename>LIC_FILES_CHKSUM</filename> variable to point to one - or more of those comments if present. - Setting <filename>LIC_FILES_CHKSUM</filename> is particularly - important for third-party software. - The mechanism attempts to ensure correct licensing should you - upgrade the recipe to a newer upstream version in future. - Any change in licensing is detected and you receive an error - prompting you to check the license text again. + The <filename>devtool</filename> command line is organized + similarly to + <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink> in that it has a + number of sub-commands for each function. + You can run <filename>devtool --help</filename> to see all the + commands. </para> <para> - If the <filename>devtool add</filename> command cannot - determine licensing information, the - <filename>LICENSE</filename> value is set to "CLOSED" and the - <filename>LIC_FILES_CHKSUM</filename> vaule remains unset. - This behavior allows you to continue with development but is - unlikely to be correct in all cases. - Consequently, you should check the documentation or source - files for the software you are building to determine the actual - license. + Three <filename>devtool</filename> subcommands that provide + entry-points into development are: + <itemizedlist> + <listitem><para> + <emphasis><filename>devtool add</filename></emphasis>: + Assists in adding new software to be built. + </para></listitem> + <listitem><para> + <emphasis><filename>devtool modify</filename></emphasis>: + Sets up an environment to enable you to modify the source of + an existing component. + </para></listitem> + <listitem><para> + <emphasis><filename>devtool upgrade</filename></emphasis>: + Updates an existing recipe so that you can build it for + an updated set of source files. + </para></listitem> + </itemizedlist> + As with the OpenEmbedded build system, "recipes" represent software + packages within <filename>devtool</filename>. + When you use <filename>devtool add</filename>, a recipe is + automatically created. + When you use <filename>devtool modify</filename>, the specified + existing recipe is used in order to determine where to get the source + code and how to patch it. + In both cases, an environment is set up so that when you build the + recipe a source tree that is under your control is used in order to + allow you to make changes to the source as desired. + By default, both new recipes and the source go into a "workspace" + directory under the SDK. </para> - </section> - - <section id='sdk-adding-makefile-only-software'> - <title>Adding Makefile-Only Software</title> <para> - The use of <filename>make</filename> by itself is very common - in both proprietary and open source software. - Unfortunately, Makefiles are often not written with - cross-compilation in mind. - Thus, <filename>devtool add</filename> often cannot do very - much to ensure that these Makefiles build correctly. - It is very common, for example, to explicitly call - <filename>gcc</filename> instead of using the - <filename>CC</filename> variable. - Usually, in a cross-compilation environment, - <filename>gcc</filename> is the compiler for the build host - and the cross-compiler is named something similar to - <filename>arm-poky-linux-gnueabi-gcc</filename> and might - require some arguments (e.g. to point to the associated sysroot - for the target machine). + The remainder of this section presents the + <filename>devtool add</filename>, + <filename>devtool modify</filename>, and + <filename>devtool upgrade</filename> workflows. </para> + <section id='sdk-use-devtool-to-add-an-application'> + <title>Use <filename>devtool add</filename> to Add an Application</title> + + <para> + The <filename>devtool add</filename> command generates + a new recipe based on existing source code. + This command takes advantage of the + <ulink url='&YOCTO_DOCS_DEV_URL;#devtool-the-workspace-layer-structure'>workspace</ulink> + layer that many <filename>devtool</filename> commands + use. + The command is flexible enough to allow you to extract source + code into both the workspace or a separate local Git repository + and to use existing code that does not need to be extracted. + </para> + + <para> + Depending on your particular scenario, the arguments and options + you use with <filename>devtool add</filename> form different + combinations. + The following diagram shows common development flows + you would use with the <filename>devtool add</filename> + command: + </para> + + <para> + <imagedata fileref="figures/sdk-devtool-add-flow.png" align="center" /> + </para> + + <para> + <orderedlist> + <listitem><para><emphasis>Generating the New Recipe</emphasis>: + The top part of the flow shows three scenarios by which + you could use <filename>devtool add</filename> to + generate a recipe based on existing source code.</para> + + <para>In a shared development environment, it is + typical where other developers are responsible for + various areas of source code. + As a developer, you are probably interested in using + that source code as part of your development using + the Yocto Project. + All you need is access to the code, a recipe, and a + controlled area in which to do your work.</para> + + <para>Within the diagram, three possible scenarios + feed into the <filename>devtool add</filename> workflow: + <itemizedlist> + <listitem><para><emphasis>Left</emphasis>: + The left scenario represents a common situation + where the source code does not exist locally + and needs to be extracted. + In this situation, you just let it get + extracted to the default workspace - you do not + want it in some specific location outside of the + workspace. + Thus, everything you need will be located in the + workspace: + <literallayout class='monospaced'> + $ devtool add <replaceable>recipe fetchuri</replaceable> + </literallayout> + With this command, <filename>devtool</filename> + creates a recipe and an append file in the + workspace as well as extracts the upstream + source files into a local Git repository also + within the <filename>sources</filename> folder. + </para></listitem> + <listitem><para><emphasis>Middle</emphasis>: + The middle scenario also represents a situation where + the source code does not exist locally. + In this case, the code is again upstream + and needs to be extracted to some + local area - this time outside of the default + workspace. + If required, <filename>devtool</filename> + always creates + a Git repository locally during the extraction. + Furthermore, the first positional argument + <replaceable>srctree</replaceable> in this case + identifies where the + <filename>devtool add</filename> command + will locate the extracted code outside of the + workspace: + <literallayout class='monospaced'> + $ devtool add <replaceable>recipe srctree fetchuri</replaceable> + </literallayout> + In summary, the source code is pulled from + <replaceable>fetchuri</replaceable> and extracted + into the location defined by + <replaceable>srctree</replaceable> as a local + Git repository.</para> + + <para>Within workspace, <filename>devtool</filename> + creates both the recipe and an append file + for the recipe. + </para></listitem> + <listitem><para><emphasis>Right</emphasis>: + The right scenario represents a situation + where the source tree (srctree) has been + previously prepared outside of the + <filename>devtool</filename> workspace. + </para> + + <para>The following command names the recipe + and identifies where the existing source tree + is located: + <literallayout class='monospaced'> + $ devtool add <replaceable>recipe srctree</replaceable> + </literallayout> + The command examines the source code and creates + a recipe for it placing the recipe into the + workspace.</para> + + <para>Because the extracted source code already exists, + <filename>devtool</filename> does not try to + relocate it into the workspace - just the new + the recipe is placed in the workspace.</para> + + <para>Aside from a recipe folder, the command + also creates an append folder and places an initial + <filename>*.bbappend</filename> within. + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para><emphasis>Edit the Recipe</emphasis>: + At this point, you can use <filename>devtool edit-recipe</filename> + to open up the editor as defined by the + <filename>$EDITOR</filename> environment variable + and modify the file: + <literallayout class='monospaced'> + $ devtool edit-recipe <replaceable>recipe</replaceable> + </literallayout> + From within the editor, you can make modifications to the + recipe that take affect when you build it later. + </para></listitem> + <listitem><para><emphasis>Build the Recipe or Rebuild the Image</emphasis>: + At this point in the flow, the next step you + take depends on what you are going to do with + the new code.</para> + <para>If you need to take the build output and eventually + move it to the target hardware, you would use + <filename>devtool build</filename>: + <literallayout class='monospaced'> + $ devtool build <replaceable>recipe</replaceable> + </literallayout></para> + <para>On the other hand, if you want an image to + contain the recipe's packages for immediate deployment + onto a device (e.g. for testing purposes), you can use + the <filename>devtool build-image</filename> command: + <literallayout class='monospaced'> + $ devtool build-image <replaceable>image</replaceable> + </literallayout> + </para></listitem> + <listitem><para><emphasis>Deploy the Build Output</emphasis>: + When you use the <filename>devtool build</filename> + command to build out your recipe, you probably want to + see if the resulting build output works as expected on target + hardware. + <note> + This step assumes you have a previously built + image that is already either running in QEMU or + running on actual hardware. + Also, it is assumed that for deployment of the image + to the target, SSH is installed in the image and if + the image is running on real hardware that you have + network access to and from your development machine. + </note> + You can deploy your build output to that target hardware by + using the <filename>devtool deploy-target</filename> command: + <literallayout class='monospaced'> + $ devtool deploy-target <replaceable>recipe target</replaceable> + </literallayout> + The <replaceable>target</replaceable> is a live target machine + running as an SSH server.</para> + + <para>You can, of course, also deploy the image you build + using the <filename>devtool build-image</filename> command + to actual hardware. + However, <filename>devtool</filename> does not provide a + specific command that allows you to do this. + </para></listitem> + <listitem><para> + <emphasis>Finish Your Work With the Recipe</emphasis>: + The <filename>devtool finish</filename> command creates + any patches corresponding to commits in the local + Git repository, moves the new recipe to a more permanent + layer, and then resets the recipe so that the recipe is + built normally rather than from the workspace. + <literallayout class='monospaced'> + $ devtool finish <replaceable>recipe layer</replaceable> + </literallayout> + <note> + Any changes you want to turn into patches must be + committed to the Git repository in the source tree. + </note></para> + + <para>As mentioned, the <filename>devtool finish</filename> + command moves the final recipe to its permanent layer. + </para> + + <para>As a final process of the + <filename>devtool finish</filename> command, the state + of the standard layers and the upstream source is + restored so that you can build the recipe from those + areas rather than the workspace. + <note> + You can use the <filename>devtool reset</filename> + command to put things back should you decide you + do not want to proceed with your work. + If you do use this command, realize that the source + tree is preserved. + </note> + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='sdk-devtool-use-devtool-modify-to-modify-the-source-of-an-existing-component'> + <title>Use <filename>devtool modify</filename> to Modify the Source of an Existing Component</title> + + <para> + The <filename>devtool modify</filename> command prepares the + way to work on existing code that already has a recipe in + place. + The command is flexible enough to allow you to extract code, + specify the existing recipe, and keep track of and gather any + patch files from other developers that are + associated with the code. + </para> + + <para> + Depending on your particular scenario, the arguments and options + you use with <filename>devtool modify</filename> form different + combinations. + The following diagram shows common development flows + you would use with the <filename>devtool modify</filename> + command: + </para> + + <para> + <imagedata fileref="figures/sdk-devtool-modify-flow.png" align="center" /> + </para> + + <para> + <orderedlist> + <listitem><para><emphasis>Preparing to Modify the Code</emphasis>: + The top part of the flow shows three scenarios by which + you could use <filename>devtool modify</filename> to + prepare to work on source files. + Each scenario assumes the following: + <itemizedlist> + <listitem><para>The recipe exists in some layer external + to the <filename>devtool</filename> workspace. + </para></listitem> + <listitem><para>The source files exist upstream in an + un-extracted state or locally in a previously + extracted state. + </para></listitem> + </itemizedlist> + The typical situation is where another developer has + created some layer for use with the Yocto Project and + their recipe already resides in that layer. + Furthermore, their source code is readily available + either upstream or locally. + <itemizedlist> + <listitem><para><emphasis>Left</emphasis>: + The left scenario represents a common situation + where the source code does not exist locally + and needs to be extracted. + In this situation, the source is extracted + into the default workspace location. + The recipe, in this scenario, is in its own + layer outside the workspace + (i.e. + <filename>meta-</filename><replaceable>layername</replaceable>). + </para> + + <para>The following command identifies the recipe + and by default extracts the source files: + <literallayout class='monospaced'> + $ devtool modify <replaceable>recipe</replaceable> + </literallayout> + Once <filename>devtool</filename>locates the recipe, + it uses the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + variable to locate the source code and + any local patch files from other developers are + located. + <note> + You cannot provide an URL for + <replaceable>srctree</replaceable> when using the + <filename>devtool modify</filename> command. + </note> + With this scenario, however, since no + <replaceable>srctree</replaceable> argument exists, the + <filename>devtool modify</filename> command by default + extracts the source files to a Git structure. + Furthermore, the location for the extracted source is the + default area within the workspace. + The result is that the command sets up both the source + code and an append file within the workspace with the + recipe remaining in its original location. + </para></listitem> + <listitem><para><emphasis>Middle</emphasis>: + The middle scenario represents a situation where + the source code also does not exist locally. + In this case, the code is again upstream + and needs to be extracted to some + local area as a Git repository. + The recipe, in this scenario, is again in its own + layer outside the workspace.</para> + + <para>The following command tells + <filename>devtool</filename> what recipe with + which to work and, in this case, identifies a local + area for the extracted source files that is outside + of the default workspace: + <literallayout class='monospaced'> + $ devtool modify <replaceable>recipe srctree</replaceable> + </literallayout> + As with all extractions, the command uses + the recipe's <filename>SRC_URI</filename> to locate the + source files. + Once the files are located, the command by default + extracts them. + Providing the <replaceable>srctree</replaceable> + argument instructs <filename>devtool</filename> where + place the extracted source.</para> + + <para>Within workspace, <filename>devtool</filename> + creates an append file for the recipe. + The recipe remains in its original location but + the source files are extracted to the location you + provided with <replaceable>srctree</replaceable>. + </para></listitem> + <listitem><para><emphasis>Right</emphasis>: + The right scenario represents a situation + where the source tree + (<replaceable>srctree</replaceable>) exists as a + previously extracted Git structure outside of + the <filename>devtool</filename> workspace. + In this example, the recipe also exists + elsewhere in its own layer. + </para> + + <para>The following command tells + <filename>devtool</filename> the recipe + with which to work, uses the "-n" option to indicate + source does not need to be extracted, and uses + <replaceable>srctree</replaceable> to point to the + previously extracted source files: + <literallayout class='monospaced'> + $ devtool modify -n <replaceable>recipe srctree</replaceable> + </literallayout> + </para> + + <para>Once the command finishes, it creates only + an append file for the recipe in the workspace. + The recipe and the source code remain in their + original locations. + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para><emphasis>Edit the Source</emphasis>: + Once you have used the <filename>devtool modify</filename> + command, you are free to make changes to the source + files. + You can use any editor you like to make and save + your source code modifications. + </para></listitem> + <listitem><para><emphasis>Build the Recipe</emphasis>: + Once you have updated the source files, you can build + the recipe. + </para></listitem> + <listitem><para><emphasis>Deploy the Build Output</emphasis>: + When you use the <filename>devtool build</filename> + command to build out your recipe, you probably want to see + if the resulting build output works as expected on target + hardware. + <note> + This step assumes you have a previously built + image that is already either running in QEMU or + running on actual hardware. + Also, it is assumed that for deployment of the image + to the target, SSH is installed in the image and if + the image is running on real hardware that you have + network access to and from your development machine. + </note> + You can deploy your build output to that target hardware by + using the <filename>devtool deploy-target</filename> command: + <literallayout class='monospaced'> + $ devtool deploy-target <replaceable>recipe target</replaceable> + </literallayout> + The <replaceable>target</replaceable> is a live target machine + running as an SSH server.</para> + + <para>You can, of course, also deploy the image you build + using the <filename>devtool build-image</filename> command + to actual hardware. + However, <filename>devtool</filename> does not provide a + specific command that allows you to do this. + </para></listitem> + <listitem><para> + <emphasis>Finish Your Work With the Recipe</emphasis>: + The <filename>devtool finish</filename> command creates + any patches corresponding to commits in the local + Git repository, updates the recipe to point to them + (or creates a <filename>.bbappend</filename> file to do + so, depending on the specified destination layer), and + then resets the recipe so that the recipe is built normally + rather than from the workspace. + <literallayout class='monospaced'> + $ devtool finish <replaceable>recipe layer</replaceable> + </literallayout> + <note> + Any changes you want to turn into patches must be + committed to the Git repository in the source tree. + </note></para> + + <para>Because there is no need to move the recipe, + <filename>devtool finish</filename> either updates the + original recipe in the original layer or the command + creates a <filename>.bbappend</filename> in a different + layer as provided by <replaceable>layer</replaceable>. + </para> + + <para>As a final process of the + <filename>devtool finish</filename> command, the state + of the standard layers and the upstream source is + restored so that you can build the recipe from those + areas rather than the workspace. + <note> + You can use the <filename>devtool reset</filename> + command to put things back should you decide you + do not want to proceed with your work. + If you do use this command, realize that the source + tree is preserved. + </note> + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='sdk-devtool-use-devtool-upgrade-to-create-a-version-of-the-recipe-that-supports-a-newer-version-of-the-software'> + <title>Use <filename>devtool upgrade</filename> to Create a Version of the Recipe that Supports a Newer Version of the Software</title> + + <para> + The <filename>devtool upgrade</filename> command updates + an existing recipe so that you can build it for an updated + set of source files. + The command is flexible enough to allow you to specify + source code revision and versioning schemes, extract code into + or out of the <filename>devtool</filename> workspace, and + work with any source file forms that the fetchers support. + </para> + + <para> + Depending on your particular scenario, the arguments and options + you use with <filename>devtool upgrade</filename> form different + combinations. + The following diagram shows a common development flow + you would use with the <filename>devtool modify</filename> + command: + </para> + + <para> + <imagedata fileref="figures/sdk-devtool-upgrade-flow.png" align="center" /> + </para> + + <para> + <orderedlist> + <listitem><para><emphasis>Initiate the Upgrade</emphasis>: + The top part of the flow shows a typical scenario by which + you could use <filename>devtool upgrade</filename>. + The following conditions exist: + <itemizedlist> + <listitem><para>The recipe exists in some layer external + to the <filename>devtool</filename> workspace. + </para></listitem> + <listitem><para>The source files for the new release + exist adjacent to the same location pointed to by + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + in the recipe (e.g. a tarball with the new version + number in the name, or as a different revision in + the upstream Git repository). + </para></listitem> + </itemizedlist> + A common situation is where third-party software has + undergone a revision so that it has been upgraded. + The recipe you have access to is likely in your own layer. + Thus, you need to upgrade the recipe to use the + newer version of the software: + <literallayout class='monospaced'> + $ devtool upgrade -V <replaceable>version recipe</replaceable> + </literallayout> + By default, the <filename>devtool upgrade</filename> command + extracts source code into the <filename>sources</filename> + directory in the workspace. + If you want the code extracted to any other location, you + need to provide the <replaceable>srctree</replaceable> + positional argument with the command as follows: + <literallayout class='monospaced'> + $ devtool upgrade -V <replaceable>version recipe srctree</replaceable> + </literallayout> + Also, in this example, the "-V" option is used to specify + the new version. + If the source files pointed to by the + <filename>SRC_URI</filename> statement in the recipe are + in a Git repository, you must provide the "-S" option and + specify a revision for the software.</para> + + <para>Once <filename>devtool</filename> locates the recipe, + it uses the <filename>SRC_URI</filename> variable to locate + the source code and any local patch files from other + developers are located. + The result is that the command sets up the source + code, the new version of the recipe, and an append file + all within the workspace. + </para></listitem> + <listitem><para><emphasis>Resolve any Conflicts created by the Upgrade</emphasis>: + At this point, there could be some conflicts due to the + software being upgraded to a new version. + This would occur if your recipe specifies some patch files in + <filename>SRC_URI</filename> that conflict with changes + made in the new version of the software. + If this is the case, you need to resolve the conflicts + by editing the source and following the normal + <filename>git rebase</filename> conflict resolution + process.</para> + <para>Before moving onto the next step, be sure to resolve any + such conflicts created through use of a newer or different + version of the software. + </para></listitem> + <listitem><para><emphasis>Build the Recipe</emphasis>: + Once you have your recipe in order, you can build it. + You can either use <filename>devtool build</filename> or + <filename>bitbake</filename>. + Either method produces build output that is stored + in + <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>. + </para></listitem> + <listitem><para><emphasis>Deploy the Build Output</emphasis>: + When you use the <filename>devtool build</filename> + command or <filename>bitbake</filename> to build out your + recipe, you probably want to see if the resulting build + output works as expected on target hardware. + <note> + This step assumes you have a previously built + image that is already either running in QEMU or + running on actual hardware. + Also, it is assumed that for deployment of the image + to the target, SSH is installed in the image and if + the image is running on real hardware that you have + network access to and from your development machine. + </note> + You can deploy your build output to that target hardware by + using the <filename>devtool deploy-target</filename> command: + <literallayout class='monospaced'> + $ devtool deploy-target <replaceable>recipe target</replaceable> + </literallayout> + The <replaceable>target</replaceable> is a live target machine + running as an SSH server.</para> + <para>You can, of course, also deploy the image you build + using the <filename>devtool build-image</filename> command + to actual hardware. + However, <filename>devtool</filename> does not provide a + specific command that allows you to do this. + </para></listitem> + <listitem><para> + <emphasis>Finish Your Work With the Recipe</emphasis>: + The <filename>devtool finish</filename> command creates + any patches corresponding to commits in the local + Git repository, moves the new recipe to a more permanent + layer, and then resets the recipe so that the recipe is + built normally rather than from the workspace. + If you specify a destination layer that is the same as + the original source, then the old version of the + recipe and associated files will be removed prior to + adding the new version. + <literallayout class='monospaced'> + $ devtool finish <replaceable>recipe layer</replaceable> + </literallayout> + <note> + Any changes you want to turn into patches must be + committed to the Git repository in the source tree. + </note></para> + <para>As a final process of the + <filename>devtool finish</filename> command, the state + of the standard layers and the upstream source is + restored so that you can build the recipe from those + areas rather than the workspace. + <note> + You can use the <filename>devtool reset</filename> + command to put things back should you decide you + do not want to proceed with your work. + If you do use this command, realize that the source + tree is preserved. + </note> + </para></listitem> + </orderedlist> + </para> + </section> + </section> + + <section id='sdk-a-closer-look-at-devtool-add'> + <title>A Closer Look at <filename>devtool add</filename></title> + <para> - When writing a recipe for Makefile-only software, keep the - following in mind: + The <filename>devtool add</filename> command automatically creates a + recipe based on the source tree with which you provide it. + Currently, the command has support for the following: <itemizedlist> <listitem><para> - You probably need to patch the Makefile to use - variables instead of hardcoding tools within the - toolchain such as <filename>gcc</filename> and - <filename>g++</filename>. + Autotools (<filename>autoconf</filename> and + <filename>automake</filename>) </para></listitem> <listitem><para> - The environment in which <filename>make</filename> runs - is set up with various standard variables for - compilation (e.g. <filename>CC</filename>, - <filename>CXX</filename>, and so forth) in a similar - manner to the environment set up by the SDK's - environment setup script. - One easy way to see these variables is to run the - <filename>devtool build</filename> command on the - recipe and then look in - <filename>oe-logs/run.do_compile</filename>. - Towards the top of this file you will see a list of - environment variables that are being set. - You can take advantage of these variables within the - Makefile. + CMake </para></listitem> <listitem><para> - If the Makefile sets a default for a variable using "=", - that default overrides the value set in the environment, - which is usually not desirable. - In this situation, you can either patch the Makefile - so it sets the default using the "?=" operator, or - you can alternatively force the value on the - <filename>make</filename> command line. - To force the value on the command line, add the - variable setting to - <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></ulink> - within the recipe as follows: - <literallayout class='monospaced'> - EXTRA_OEMAKE += "'CC=${CC}' 'CXX=${CXX}'" - </literallayout> - In the above example, single quotes are used around the - variable settings as the values are likely to contain - spaces because required default options are passed to - the compiler. + Scons </para></listitem> <listitem><para> - Hardcoding paths inside Makefiles is often problematic - in a cross-compilation environment. - This is particularly true because those hardcoded paths - often point to locations on the build host and thus - will either be read-only or will introduce - contamination into the cross-compilation by virtue of - being specific to the build host rather than the target. - Patching the Makefile to use prefix variables or other - path variables is usually the way to handle this. + <filename>qmake</filename> </para></listitem> <listitem><para> - Sometimes a Makefile runs target-specific commands such - as <filename>ldconfig</filename>. - For such cases, you might be able to simply apply - patches that remove these commands from the Makefile. + Plain <filename>Makefile</filename> + </para></listitem> + <listitem><para> + Out-of-tree kernel module + </para></listitem> + <listitem><para> + Binary package (i.e. "-b" option) </para></listitem> - </itemizedlist> - </para> - </section> - - <section id='sdk-adding-native-tools'> - <title>Adding Native Tools</title> - - <para> - Often, you need to build additional tools that run on the - build host system as opposed to the target. - You should indicate this using one of the following methods - when you run <filename>devtool add</filename>: - <itemizedlist> <listitem><para> - Specify the name of the recipe such that it ends - with "-native". - Specifying the name like this produces a recipe that - only builds for the build host. + Node.js module </para></listitem> <listitem><para> - Specify the "‐‐also-native" option with the - <filename>devtool add</filename> command. - Specifying this option creates a recipe file that still - builds for the target but also creates a variant with - a "-native" suffix that builds for the build host. + Python modules that use <filename>setuptools</filename> + or <filename>distutils</filename> </para></listitem> </itemizedlist> + </para> + + <para> + Apart from binary packages, the determination of how a source tree + should be treated is automatic based on the files present within + that source tree. + For example, if a <filename>CMakeLists.txt</filename> file is found, + then the source tree is assumed to be using + CMake and is treated accordingly. <note> - If you need to add a tool that is shipped as part of a - source tree that builds code for the target, you can - typically accomplish this by building the native and target - parts separately rather than within the same compilation - process. - Realize though that with the "‐‐also-native" option, you - can add the tool using just one recipe file. + In most cases, you need to edit the automatically generated + recipe in order to make it build properly. + Typically, you would go through several edit and build cycles + until you can build the recipe. + Once the recipe can be built, you could use possible further + iterations to test the recipe on the target device. </note> </para> - </section> - - <section id='sdk-adding-node-js-modules'> - <title>Adding Node.js Modules</title> <para> - You can use the <filename>devtool add</filename> command in the - following form to add Node.js modules: - <literallayout class='monospaced'> - $ devtool add "npm://registry.npmjs.org;name=forever;version=0.15.1" - </literallayout> - The name and version parameters are mandatory. - Lockdown and shrinkwrap files are generated and pointed to by - the recipe in order to freeze the version that is fetched for - the dependencies according to the first time. - This also saves checksums that are verified on future fetches. - Together, these behaviors ensure the reproducibility and - integrity of the build. - <note><title>Notes</title> + The remainder of this section covers specifics regarding how parts + of the recipe are generated. + </para> + + <section id='sdk-name-and-version'> + <title>Name and Version</title> + + <para> + If you do not specify a name and version on the command + line, <filename>devtool add</filename> attempts to determine + the name and version of the software being built from + various metadata within the source tree. + Furthermore, the command sets the name of the created recipe + file accordingly. + If the name or version cannot be determined, the + <filename>devtool add</filename> command prints an error and + you must re-run the command with both the name and version + or just the name or version specified. + </para> + + <para> + Sometimes the name or version determined from the source tree + might be incorrect. + For such a case, you must reset the recipe: + <literallayout class='monospaced'> + $ devtool reset -n <replaceable>recipename</replaceable> + </literallayout> + After running the <filename>devtool reset</filename> command, + you need to run <filename>devtool add</filename> again and + provide the name or the version. + </para> + </section> + + <section id='sdk-dependency-detection-and-mapping'> + <title>Dependency Detection and Mapping</title> + + <para> + The <filename>devtool add</filename> command attempts to + detect build-time dependencies and map them to other recipes + in the system. + During this mapping, the command fills in the names of those + recipes in the + <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink> + value within the recipe. + If a dependency cannot be mapped, then a comment is placed in + the recipe indicating such. + The inability to map a dependency might be caused because the + naming is not recognized or because the dependency simply is + not available. + For cases where the dependency is not available, you must use + the <filename>devtool add</filename> command to add an + additional recipe to satisfy the dependency and then come + back to the first recipe and add its name to + <filename>DEPENDS</filename>. + </para> + + <para> + If you need to add runtime dependencies, you can do so by + adding the following to your recipe: + <literallayout class='monospaced'> + RDEPENDS_${PN} += "dependency1 dependency2 ..." + </literallayout> + <note> + The <filename>devtool add</filename> command often cannot + distinguish between mandatory and optional dependencies. + Consequently, some of the detected dependencies might + in fact be optional. + When in doubt, consult the documentation or the configure + script for the software the recipe is building for further + details. + In some cases, you might find you can substitute the + dependency for an option to disable the associated + functionality passed to the configure script. + </note> + </para> + </section> + + <section id='sdk-license-detection'> + <title>License Detection</title> + + <para> + The <filename>devtool add</filename> command attempts to + determine if the software you are adding is able to be + distributed under a common open-source license and sets the + <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink> + value accordingly. + You should double-check this value against the documentation + or source files for the software you are building and update + that <filename>LICENSE</filename> value if necessary. + </para> + + <para> + The <filename>devtool add</filename> command also sets the + <ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></ulink> + value to point to all files that appear to be license-related. + However, license statements often appear in comments at the top + of source files or within documentation. + Consequently, you might need to amend the + <filename>LIC_FILES_CHKSUM</filename> variable to point to one + or more of those comments if present. + Setting <filename>LIC_FILES_CHKSUM</filename> is particularly + important for third-party software. + The mechanism attempts to ensure correct licensing should you + upgrade the recipe to a newer upstream version in future. + Any change in licensing is detected and you receive an error + prompting you to check the license text again. + </para> + + <para> + If the <filename>devtool add</filename> command cannot + determine licensing information, the + <filename>LICENSE</filename> value is set to "CLOSED" and the + <filename>LIC_FILES_CHKSUM</filename> value remains unset. + This behavior allows you to continue with development but is + unlikely to be correct in all cases. + Consequently, you should check the documentation or source + files for the software you are building to determine the actual + license. + </para> + </section> + + <section id='sdk-adding-makefile-only-software'> + <title>Adding Makefile-Only Software</title> + + <para> + The use of <filename>make</filename> by itself is very common + in both proprietary and open source software. + Unfortunately, Makefiles are often not written with + cross-compilation in mind. + Thus, <filename>devtool add</filename> often cannot do very + much to ensure that these Makefiles build correctly. + It is very common, for example, to explicitly call + <filename>gcc</filename> instead of using the + <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink> + variable. + Usually, in a cross-compilation environment, + <filename>gcc</filename> is the compiler for the build host + and the cross-compiler is named something similar to + <filename>arm-poky-linux-gnueabi-gcc</filename> and might + require some arguments (e.g. to point to the associated sysroot + for the target machine). + </para> + + <para> + When writing a recipe for Makefile-only software, keep the + following in mind: <itemizedlist> <listitem><para> - You must use quotes around the URL. - The <filename>devtool add</filename> does not require - the quotes, but the shell considers ";" as a splitter - between multiple commands. - Thus, without the quotes, - <filename>devtool add</filename> does not receive the - other parts, which results in several "command not - found" errors. + You probably need to patch the Makefile to use + variables instead of hardcoding tools within the + toolchain such as <filename>gcc</filename> and + <filename>g++</filename>. </para></listitem> <listitem><para> - In order to support adding - Node.js modules, a - <filename>nodejs</filename> recipe must be part of your - SDK in order to provide Node.js - itself. + The environment in which <filename>make</filename> runs + is set up with various standard variables for + compilation (e.g. <filename>CC</filename>, + <filename>CXX</filename>, and so forth) in a similar + manner to the environment set up by the SDK's + environment setup script. + One easy way to see these variables is to run the + <filename>devtool build</filename> command on the + recipe and then look in + <filename>oe-logs/run.do_compile</filename>. + Towards the top of this file you will see a list of + environment variables that are being set. + You can take advantage of these variables within the + Makefile. + </para></listitem> + <listitem><para> + If the Makefile sets a default for a variable using "=", + that default overrides the value set in the environment, + which is usually not desirable. + In this situation, you can either patch the Makefile + so it sets the default using the "?=" operator, or + you can alternatively force the value on the + <filename>make</filename> command line. + To force the value on the command line, add the + variable setting to + <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></ulink> + or + <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></ulink> + within the recipe. + Here is an example using <filename>EXTRA_OEMAKE</filename>: + <literallayout class='monospaced'> + EXTRA_OEMAKE += "'CC=${CC}' 'CXX=${CXX}'" + </literallayout> + In the above example, single quotes are used around the + variable settings as the values are likely to contain + spaces because required default options are passed to + the compiler. + </para></listitem> + <listitem><para> + Hardcoding paths inside Makefiles is often problematic + in a cross-compilation environment. + This is particularly true because those hardcoded paths + often point to locations on the build host and thus + will either be read-only or will introduce + contamination into the cross-compilation by virtue of + being specific to the build host rather than the target. + Patching the Makefile to use prefix variables or other + path variables is usually the way to handle this. + </para></listitem> + <listitem><para> + Sometimes a Makefile runs target-specific commands such + as <filename>ldconfig</filename>. + For such cases, you might be able to simply apply + patches that remove these commands from the Makefile. </para></listitem> </itemizedlist> - </note> - </para> - </section> -</section> - -<section id='sdk-working-with-recipes'> - <title>Working With Recipes</title> - - <para> - When building a recipe with <filename>devtool build</filename> the - typical build progression is as follows: - <orderedlist> - <listitem><para> - Fetch the source - </para></listitem> - <listitem><para> - Unpack the source - </para></listitem> - <listitem><para> - Configure the source - </para></listitem> - <listitem><para> - Compiling the source - </para></listitem> - <listitem><para> - Install the build output - </para></listitem> - <listitem><para> - Package the installed output - </para></listitem> - </orderedlist> - For recipes in the workspace, fetching and unpacking is disabled - as the source tree has already been prepared and is persistent. - Each of these build steps is defined as a function, usually with a - "do_" prefix. - These functions are typically shell scripts but can instead be written - in Python. - </para> + </para> + </section> - <para> - If you look at the contents of a recipe, you will see that the - recipe does not include complete instructions for building the - software. - Instead, common functionality is encapsulated in classes inherited - with the <filename>inherit</filename> directive, leaving the recipe - to describe just the things that are specific to the software to be - built. - A <ulink url='ref-classes-base'><filename>base</filename></ulink> - class exists that is implicitly inherited by all recipes and provides - the functionality that most typical recipes need. - </para> - - <para> - The remainder of this section presents information useful when - working with recipes. - </para> + <section id='sdk-adding-native-tools'> + <title>Adding Native Tools</title> - <section id='sdk-finding-logs-and-work-files'> - <title>Finding Logs and Work Files</title> + <para> + Often, you need to build additional tools that run on the + build host system as opposed to the target. + You should indicate this using one of the following methods + when you run <filename>devtool add</filename>: + <itemizedlist> + <listitem><para> + Specify the name of the recipe such that it ends + with "-native". + Specifying the name like this produces a recipe that + only builds for the build host. + </para></listitem> + <listitem><para> + Specify the "‐‐also-native" option with the + <filename>devtool add</filename> command. + Specifying this option creates a recipe file that still + builds for the target but also creates a variant with + a "-native" suffix that builds for the build host. + </para></listitem> + </itemizedlist> + <note> + If you need to add a tool that is shipped as part of a + source tree that builds code for the target, you can + typically accomplish this by building the native and target + parts separately rather than within the same compilation + process. + Realize though that with the "‐‐also-native" option, you + can add the tool using just one recipe file. + </note> + </para> + </section> + + <section id='sdk-adding-node-js-modules'> + <title>Adding Node.js Modules</title> + + <para> + You can use the <filename>devtool add</filename> command two + different ways to add Node.js modules: 1) Through + <filename>npm</filename> and, 2) from a repository or local + source. + </para> + + <para> + Use the following form to add Node.js modules through + <filename>npm</filename>: + <literallayout class='monospaced'> + $ devtool add "npm://registry.npmjs.org;name=forever;version=0.15.1" + </literallayout> + The name and version parameters are mandatory. + Lockdown and shrinkwrap files are generated and pointed to by + the recipe in order to freeze the version that is fetched for + the dependencies according to the first time. + This also saves checksums that are verified on future fetches. + Together, these behaviors ensure the reproducibility and + integrity of the build. + <note><title>Notes</title> + <itemizedlist> + <listitem><para> + You must use quotes around the URL. + The <filename>devtool add</filename> does not require + the quotes, but the shell considers ";" as a splitter + between multiple commands. + Thus, without the quotes, + <filename>devtool add</filename> does not receive the + other parts, which results in several "command not + found" errors. + </para></listitem> + <listitem><para> + In order to support adding + Node.js modules, a + <filename>nodejs</filename> recipe must be part of your + SDK in order to provide Node.js + itself. + </para></listitem> + </itemizedlist> + </note> + </para> + + <para> + As mentioned earlier, you can also add Node.js modules + directly from a repository or local source tree. + To add modules this way, use <filename>devtool add</filename> in + the following form: + <literallayout class='monospaced'> + $ devtool add https://github.com/diversario/node-ssdp + </literallayout> + In this example, <filename>devtool</filename> fetches the specified + Git repository, detects that the code is Node.js code, fetches + dependencies using <filename>npm</filename>, and sets + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + accordingly. + </para> + </section> + </section> - <para> - When you are debugging a recipe that you previously created using - <filename>devtool add</filename> or whose source you are modifying - by using the <filename>devtool modify</filename> command, after - the first run of <filename>devtool build</filename>, you will - find some symbolic links created within the source tree: - <filename>oe-logs</filename>, which points to the directory in - which log files and run scripts for each build step are created - and <filename>oe-workdir</filename>, which points to the temporary - work area for the recipe. - You can use these links to get more information on what is - happening at each build step. - </para> + <section id='sdk-working-with-recipes'> + <title>Working With Recipes</title> <para> - These locations under <filename>oe-workdir</filename> are - particularly useful: - <itemizedlist> - <listitem><para><filename>image/</filename>: - Contains all of the files installed at the - <ulink url='&YOCTO_DOCS_REF_URL;ref-tasks-install'><filename>do_install</filename></ulink> - stage. - Within a recipe, this directory is referred to by the - expression - <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename>. + When building a recipe with <filename>devtool build</filename> the + typical build progression is as follows: + <orderedlist> + <listitem><para> + Fetch the source + </para></listitem> + <listitem><para> + Unpack the source </para></listitem> - <listitem><para><filename>sysroot-destdir/</filename>: - Contains a subset of files installed within - <filename>do_install</filename> that have been put into the - shared sysroot. - For more information, see the - "<link linkend='sdk-sharing-files-between-recipes'>Sharing Files Between Recipes</link>" - section. + <listitem><para> + Configure the source </para></listitem> - <listitem><para><filename>packages-split/</filename>: - Contains subdirectories for each package produced by the - recipe. - For more information, see the - "<link linkend='sdk-packaging'>Packaging</link>" section. + <listitem><para> + Compiling the source </para></listitem> - </itemizedlist> - </para> - </section> - - <section id='sdk-setting-configure-arguments'> - <title>Setting Configure Arguments</title> - - <para> - If the software your recipe is building uses GNU autoconf, - then a fixed set of arguments is passed to it to enable - cross-compilation plus any extras specified by - <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></ulink> - set within the recipe. - If you wish to pass additional options, add them to - <filename>EXTRA_OECONF</filename>. - Other supported build tools have similar variables - (e.g. - <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECMAKE'><filename>EXTRA_OECMAKE</filename></ulink> - for CMake, - <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OESCONS'><filename>EXTRA_OESCONS</filename></ulink> - for Scons, and so forth). - If you need to pass anything on the <filename>make</filename> - command line, you can use <filename>EXTRA_OEMAKE</filename> to do - so. + <listitem><para> + Install the build output + </para></listitem> + <listitem><para> + Package the installed output + </para></listitem> + </orderedlist> + For recipes in the workspace, fetching and unpacking is disabled + as the source tree has already been prepared and is persistent. + Each of these build steps is defined as a function, usually with a + "do_" prefix. + These functions are typically shell scripts but can instead be written + in Python. </para> <para> - You can use the <filename>devtool configure-help</filename> command - to help you set the arguments listed in the previous paragraph. - The command determines the exact options being passed, and shows - them to you along with any custom arguments specified through - <filename>EXTRA_OECONF</filename>. - If applicable, the command also shows you the output of the - configure script's "‐‐help" option as a reference. + If you look at the contents of a recipe, you will see that the + recipe does not include complete instructions for building the + software. + Instead, common functionality is encapsulated in classes inherited + with the <filename>inherit</filename> directive, leaving the recipe + to describe just the things that are specific to the software to be + built. + A <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-base'><filename>base</filename></ulink> + class exists that is implicitly inherited by all recipes and provides + the functionality that most typical recipes need. </para> - </section> - - <section id='sdk-sharing-files-between-recipes'> - <title>Sharing Files Between Recipes</title> <para> - Recipes often need to use files provided by other recipes on - the build host. - For example, an application linking to a common library needs - access to the library itself and its associated headers. - The way this access is accomplished within the extensible SDK is - through the sysroot. - One sysroot exists per "machine" for which the SDK is being built. - In practical terms, this means a sysroot exists for the target - machine, and a sysroot exists for the build host. + The remainder of this section presents information useful when + working with recipes. </para> - <para> - Recipes should never write files directly into the sysroot. - Instead, files should be installed into standard locations - during the - <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink> - task within the - <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename> - directory. - A subset of these files automatically go into the sysroot. - The reason for this limitation is that almost all files that go - into the sysroot are cataloged in manifests in order to ensure - they can be removed later when a recipe is modified or removed. - Thus, the sysroot is able to remain free from stale files. - </para> + <section id='sdk-finding-logs-and-work-files'> + <title>Finding Logs and Work Files</title> + + <para> + When you are debugging a recipe that you previously created using + <filename>devtool add</filename> or whose source you are modifying + by using the <filename>devtool modify</filename> command, after + the first run of <filename>devtool build</filename>, you will + find some symbolic links created within the source tree: + <filename>oe-logs</filename>, which points to the directory in + which log files and run scripts for each build step are created + and <filename>oe-workdir</filename>, which points to the temporary + work area for the recipe. + You can use these links to get more information on what is + happening at each build step. + </para> + + <para> + These locations under <filename>oe-workdir</filename> are + particularly useful: + <itemizedlist> + <listitem><para><filename>image/</filename>: + Contains all of the files installed at the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink> + stage. + Within a recipe, this directory is referred to by the + expression + <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename>. + </para></listitem> + <listitem><para><filename>sysroot-destdir/</filename>: + Contains a subset of files installed within + <filename>do_install</filename> that have been put into the + shared sysroot. + For more information, see the + "<link linkend='sdk-sharing-files-between-recipes'>Sharing Files Between Recipes</link>" + section. + </para></listitem> + <listitem><para><filename>packages-split/</filename>: + Contains subdirectories for each package produced by the + recipe. + For more information, see the + "<link linkend='sdk-packaging'>Packaging</link>" section. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='sdk-setting-configure-arguments'> + <title>Setting Configure Arguments</title> + + <para> + If the software your recipe is building uses GNU autoconf, + then a fixed set of arguments is passed to it to enable + cross-compilation plus any extras specified by + <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></ulink> + or + <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></ulink> + set within the recipe. + If you wish to pass additional options, add them to + <filename>EXTRA_OECONF</filename> or + <filename>PACKAGECONFIG_CONFARGS</filename>. + Other supported build tools have similar variables + (e.g. + <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OECMAKE'><filename>EXTRA_OECMAKE</filename></ulink> + for CMake, + <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OESCONS'><filename>EXTRA_OESCONS</filename></ulink> + for Scons, and so forth). + If you need to pass anything on the <filename>make</filename> + command line, you can use <filename>EXTRA_OEMAKE</filename> or the + <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG_CONFARGS'><filename>PACKAGECONFIG_CONFARGS</filename></ulink> + variables to do so. + </para> + + <para> + You can use the <filename>devtool configure-help</filename> command + to help you set the arguments listed in the previous paragraph. + The command determines the exact options being passed, and shows + them to you along with any custom arguments specified through + <filename>EXTRA_OECONF</filename> or + <filename>PACKAGECONFIG_CONFARGS</filename>. + If applicable, the command also shows you the output of the + configure script's "‐‐help" option as a reference. + </para> + </section> + + <section id='sdk-sharing-files-between-recipes'> + <title>Sharing Files Between Recipes</title> + + <para> + Recipes often need to use files provided by other recipes on + the build host. + For example, an application linking to a common library needs + access to the library itself and its associated headers. + The way this access is accomplished within the extensible SDK is + through the sysroot. + One sysroot exists per "machine" for which the SDK is being built. + In practical terms, this means a sysroot exists for the target + machine, and a sysroot exists for the build host. + </para> + + <para> + Recipes should never write files directly into the sysroot. + Instead, files should be installed into standard locations + during the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink> + task within the + <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink><filename>}</filename> + directory. + A subset of these files automatically go into the sysroot. + The reason for this limitation is that almost all files that go + into the sysroot are cataloged in manifests in order to ensure + they can be removed later when a recipe is modified or removed. + Thus, the sysroot is able to remain free from stale files. + </para> + </section> + + <section id='sdk-packaging'> + <title>Packaging</title> + + <para> + Packaging is not always particularly relevant within the + extensible SDK. + However, if you examine how build output gets into the final image + on the target device, it is important to understand packaging + because the contents of the image are expressed in terms of + packages and not recipes. + </para> + + <para> + During the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink> + task, files installed during the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink> + task are split into one main package, which is almost always named + the same as the recipe, and several other packages. + This separation is done because not all of those installed files + are always useful in every image. + For example, you probably do not need any of the documentation + installed in a production image. + Consequently, for each recipe the documentation files are separated + into a <filename>-doc</filename> package. + Recipes that package software that has optional modules or + plugins might do additional package splitting as well. + </para> + + <para> + After building a recipe you can see where files have gone by + looking in the <filename>oe-workdir/packages-split</filename> + directory, which contains a subdirectory for each package. + Apart from some advanced cases, the + <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink> + and + <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink> + variables controls splitting. + The <filename>PACKAGES</filename> variable lists all of the + packages to be produced, while the <filename>FILES</filename> + variable specifies which files to include in each package, + using an override to specify the package. + For example, <filename>FILES_${PN}</filename> specifies the files + to go into the main package (i.e. the main package is named the + same as the recipe and + <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename> + evaluates to the recipe name). + The order of the <filename>PACKAGES</filename> value is significant. + For each installed file, the first package whose + <filename>FILES</filename> value matches the file is the package + into which the file goes. + Defaults exist for both the <filename>PACKAGES</filename> and + <filename>FILES</filename> variables. + Consequently, you might find you do not even need to set these + variables in your recipe unless the software the recipe is + building installs files into non-standard locations. + </para> + </section> </section> - <section id='sdk-packaging'> - <title>Packaging</title> - - <para> - Packaging is not always particularly relevant within the - extensible SDK. - However, if you examine how build output gets into the final image - on the target device, it is important to understand packaging - because the contents of the image are expressed in terms of - packages and not recipes. - </para> - - <para> - During the - <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink> - task, files installed during the - <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink> - task are split into one main package, which is almost always named - the same as the recipe, and several other packages. - This separation is done because not all of those installed files - are always useful in every image. - For example, you probably do not need any of the documentation - installed in a production image. - Consequently, for each recipe the documentation files are separated - into a <filename>-doc</filename> package. - Recipes that package software that has optional modules or - plugins might do additional package splitting as well. - </para> + <section id='sdk-restoring-the-target-device-to-its-original-state'> + <title>Restoring the Target Device to its Original State</title> <para> - After building a recipe you can see where files have gone by - looking in the <filename>oe-workdir/packages-split</filename> - directory, which contains a subdirectory for each package. - Apart from some advanced cases, the - <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink> - and - <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink> - variables controls splitting. - The <filename>PACKAGES</filename> variable lists all of the - packages to be produced, while the <filename>FILES</filename> - variable specifies which files to include in each package, - using an override to specify the package. - For example, <filename>FILES_${PN}</filename> specifies the files - to go into the main package (i.e. the main package is named the - same as the recipe and - <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename> - evaluates to the recipe name). - The order of the <filename>PACKAGES</filename> value is significant. - For each installed file, the first package whose - <filename>FILES</filename> value matches the file is the package - into which the file goes. - Defaults exist for both the <filename>PACKAGES</filename> and - <filename>FILES</filename> variables. - Consequently, you might find you do not even need to set these - variables in your recipe unless the software the recipe is - building installs files into non-standard locations. - </para> - </section> -</section> - -<section id='sdk-restoring-the-target-device-to-its-original-state'> - <title>Restoring the Target Device to its Original State</title> - - <para> - If you use the <filename>devtool deploy-target</filename> - command to write a recipe's build output to the target, and - you are working on an existing component of the system, then you - might find yourself in a situation where you need to restore the - original files that existed prior to running the - <filename>devtool deploy-target</filename> command. - Because the <filename>devtool deploy-target</filename> command - backs up any files it overwrites, you can use the - <filename>devtool undeploy-target</filename> to restore those files - and remove any other files the recipe deployed. - Consider the following example: - <literallayout class='monospaced'> + If you use the <filename>devtool deploy-target</filename> + command to write a recipe's build output to the target, and + you are working on an existing component of the system, then you + might find yourself in a situation where you need to restore the + original files that existed prior to running the + <filename>devtool deploy-target</filename> command. + Because the <filename>devtool deploy-target</filename> command + backs up any files it overwrites, you can use the + <filename>devtool undeploy-target</filename> to restore those files + and remove any other files the recipe deployed. + Consider the following example: + <literallayout class='monospaced'> $ devtool undeploy-target lighttpd root@192.168.7.2 - </literallayout> - If you have deployed multiple applications, you can remove them - all at once thus restoring the target device back to its - original state: - <literallayout class='monospaced'> + </literallayout> + If you have deployed multiple applications, you can remove them + all at once thus restoring the target device back to its + original state: + <literallayout class='monospaced'> $ devtool undeploy-target -a root@192.168.7.2 - </literallayout> - Information about files deployed to the target as well as any - backed up files are stored on the target itself. - This storage of course requires some additional space - on the target machine. - <note> - The <filename>devtool deploy-target</filename> and - <filename>devtool undeploy-target</filename> command do not - currently interact with any package management system on the - target device (e.g. RPM or OPKG). - Consequently, you should not intermingle operations - <filename>devtool deploy-target</filename> and the package - manager operations on the target device. - Doing so could result in a conflicting set of files. - </note> - </para> -</section> + </literallayout> + Information about files deployed to the target as well as any + backed up files are stored on the target itself. + This storage of course requires some additional space + on the target machine. + <note> + The <filename>devtool deploy-target</filename> and + <filename>devtool undeploy-target</filename> command do not + currently interact with any package management system on the + target device (e.g. RPM or OPKG). + Consequently, you should not intermingle operations + <filename>devtool deploy-target</filename> and the package + manager operations on the target device. + Doing so could result in a conflicting set of files. + </note> + </para> + </section> -<section id='sdk-installing-additional-items-into-the-extensible-sdk'> - <title>Installing Additional Items Into the Extensible SDK</title> + <section id='sdk-installing-additional-items-into-the-extensible-sdk'> + <title>Installing Additional Items Into the Extensible SDK</title> - <para> - The extensible SDK typically only comes with a small number of tools - and libraries out of the box. - If you have a minimal SDK, then it starts mostly empty and is - populated on-demand. - However, sometimes you will need to explicitly install extra items - into the SDK. - If you need these extra items, you can first search for the items - using the <filename>devtool search</filename> command. - For example, suppose you need to link to libGL but you are not sure - which recipe provides it. - You can use the following command to find out: - <literallayout class='monospaced'> + <para> + The extensible SDK typically only comes with a small number of tools + and libraries out of the box. + If you have a minimal SDK, then it starts mostly empty and is + populated on-demand. + However, sometimes you will need to explicitly install extra items + into the SDK. + If you need these extra items, you can first search for the items + using the <filename>devtool search</filename> command. + For example, suppose you need to link to libGL but you are not sure + which recipe provides it. + You can use the following command to find out: + <literallayout class='monospaced'> $ devtool search libGL mesa A free implementation of the OpenGL API - </literallayout> - Once you know the recipe (i.e. <filename>mesa</filename> in this - example), you can install it: - <literallayout class='monospaced'> + </literallayout> + Once you know the recipe (i.e. <filename>mesa</filename> in this + example), you can install it: + <literallayout class='monospaced'> $ devtool sdk-install mesa - </literallayout> - By default, the <filename>devtool sdk-install</filename> assumes the - item is available in pre-built form from your SDK provider. - If the item is not available and it is acceptable to build the item - from source, you can add the "-s" option as follows: - <literallayout class='monospaced'> + </literallayout> + By default, the <filename>devtool sdk-install</filename> assumes the + item is available in pre-built form from your SDK provider. + If the item is not available and it is acceptable to build the item + from source, you can add the "-s" option as follows: + <literallayout class='monospaced'> $ devtool sdk-install -s mesa - </literallayout> - It is important to remember that building the item from source takes - significantly longer than installing the pre-built artifact. - Also, if no recipe exists for the item you want to add to the SDK, you - must instead add it using the <filename>devtool add</filename> command. - </para> -</section> + </literallayout> + It is important to remember that building the item from source takes + significantly longer than installing the pre-built artifact. + Also, if no recipe exists for the item you want to add to the SDK, you + must instead add it using the <filename>devtool add</filename> command. + </para> + </section> -<section id='sdk-updating-the-extensible-sdk'> - <title>Updating the Extensible SDK</title> + <section id='sdk-updating-the-extensible-sdk'> + <title>Updating the Extensible SDK</title> - <para> - If you are working with an extensible SDK that gets occasionally - updated (e.g. typically when that SDK has been provided to you by - another party), then you will need to manually pull down those - updates to your installed SDK. - </para> + <para> + If you are working with an extensible SDK that gets occasionally + updated (e.g. typically when that SDK has been provided to you by + another party), then you will need to manually pull down those + updates to your installed SDK. + </para> - <para> - To update your installed SDK, run the following: - <literallayout class='monospaced'> + <para> + To update your installed SDK, run the following: + <literallayout class='monospaced'> $ devtool sdk-update - </literallayout> - The previous command assumes your SDK provider has set the default - update URL for you. - If that URL has not been set, you need to specify it yourself as - follows: - <literallayout class='monospaced'> + </literallayout> + The previous command assumes your SDK provider has set the default + update URL for you. + If that URL has not been set, you need to specify it yourself as + follows: + <literallayout class='monospaced'> $ devtool sdk-update <replaceable>path_to_update_directory</replaceable> - </literallayout> - <note> - The URL needs to point specifically to a published SDK and not an - SDK installer that you would download and install. - </note> - </para> -</section> - -<section id='sdk-creating-a-derivative-sdk-with-additional-components'> - <title>Creating a Derivative SDK With Additional Components</title> + </literallayout> + <note> + The URL needs to point specifically to a published SDK and not an + SDK installer that you would download and install. + </note> + </para> + </section> - <para> - You might need to produce an SDK that contains your own custom - libraries for sending to a third party (e.g., if you are a vendor with - customers needing to build their own software for the target platform). - If that is the case, then you can produce a derivative SDK based on - the currently installed SDK fairly easily. - Use these steps: - <orderedlist> - <listitem><para>If necessary, install an extensible SDK that - you want to use as a base for your derivative SDK. - </para></listitem> - <listitem><para>Source the environment script for the SDK. - </para></listitem> - <listitem><para>Add the extra libraries or other components - you want by using the <filename>devtool add</filename> - command. - </para></listitem> - <listitem><para>Run the <filename>devtool build-sdk</filename> - command. - </para></listitem> - </orderedlist> - The above procedure takes the recipes added to the workspace and - constructs a new SDK installer containing those recipes and the - resulting binary artifacts. - The recipes go into their own separate layer in the constructed - derivative SDK, leaving the workspace clean and ready for users - to add their own recipes. - </para> -</section> + <section id='sdk-creating-a-derivative-sdk-with-additional-components'> + <title>Creating a Derivative SDK With Additional Components</title> + <para> + You might need to produce an SDK that contains your own custom + libraries for sending to a third party (e.g., if you are a vendor with + customers needing to build their own software for the target platform). + If that is the case, then you can produce a derivative SDK based on + the currently installed SDK fairly easily. + Use these steps: + <orderedlist> + <listitem><para>If necessary, install an extensible SDK that + you want to use as a base for your derivative SDK. + </para></listitem> + <listitem><para>Source the environment script for the SDK. + </para></listitem> + <listitem><para>Add the extra libraries or other components + you want by using the <filename>devtool add</filename> + command. + </para></listitem> + <listitem><para>Run the <filename>devtool build-sdk</filename> + command. + </para></listitem> + </orderedlist> + The above procedure takes the recipes added to the workspace and + constructs a new SDK installer containing those recipes and the + resulting binary artifacts. + The recipes go into their own separate layer in the constructed + derivative SDK, leaving the workspace clean and ready for users + to add their own recipes. + </para> + </section> </chapter> <!-- vim: expandtab tw=80 ts=4 diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-intro.xml b/import-layers/yocto-poky/documentation/sdk-manual/sdk-intro.xml index 88ae77831..68401690d 100644 --- a/import-layers/yocto-poky/documentation/sdk-manual/sdk-intro.xml +++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-intro.xml @@ -11,41 +11,53 @@ <para> Welcome to the Yocto Project Software Development Kit (SDK) Developer's Guide. - This manual provides information that lets you use both the standard - Yocto Project SDK and an extensible SDK to develop applications and - images using the Yocto Project. + This manual provides information that explains how to use both the + Yocto Project extensible and standard SDKs to develop + applications and images. Additionally, the manual also provides information on how to use the popular <trademark class='trade'>Eclipse</trademark> IDE as part - of your application development workflow. + of your application development workflow within the SDK environment. + <note> + Prior to the 2.0 Release of the Yocto Project, application + development was primarily accomplished through the use of the + Application Development Toolkit (ADT) and the availability + of stand-alone cross-development toolchains and other tools. + With the 2.1 Release of the Yocto Project, application development + has transitioned to within a tool-rich extensible SDK and the more + traditional standard SDK. + </note> </para> <para> - Prior to the 2.0 Release of the Yocto Project, application - development was primarily accomplished through the use of the - Application Development Toolkit (ADT) and the availability - of stand-alone cross-development toolchains and other tools. - With the 2.1 Release of the Yocto Project, application development - has transitioned to within a more traditional SDK and extensible - SDK. - </para> - - <para> - A standard SDK consists of a cross-development toolchain that contains - a compiler, debugger, and various miscellaneous tools; libraries, - headers, and symbols to match an image; and environment setup script. - You can use this SDK to independently develop and test code that is - destined to run on some target machine. + All SDKs consist of the following: + <itemizedlist> + <listitem><para><emphasis>Cross-Development Toolchain</emphasis>: + This toolchain contains a compiler, debugger, and various + miscellaneous tools. + </para></listitem> + <listitem><para><emphasis>Libraries, Headers, and Symbols</emphasis>: + The libraries, headers, and symbols are specific to the image + (i.e. they match the image). + </para></listitem> + <listitem><para><emphasis>Environment Setup Script</emphasis>: + This <filename>*.sh</filename> file, once run, sets up the + cross-development environment by defining variables and + preparing for SDK use. + </para></listitem> + </itemizedlist> </para> <para> - An extensible SDK consists of everything that the standard SDK has plus - tools that allow you to easily add new applications and libraries to - an image, modify the source of an existing component, test changes on - the target hardware, and easily integrate an application into the + Additionally an extensible SDK has tools that allow you to easily add + new applications and libraries to an image, modify the source of an + existing component, test changes on the target hardware, and easily + integrate an application into the <ulink url='&YOCTO_DOCS_DEV_URL;#build-system-term'>OpenEmbedded build system</ulink>. </para> <para> + You can use an SDK to independently develop and test code + that is destined to run on some target machine. SDKs are completely self-contained. The binaries are linked against their own copy of <filename>libc</filename>, which results in no dependencies @@ -59,8 +71,8 @@ </para> <para> - Another feature for the SDKs is that only one set of cross-canadian - toolchain binaries are produced per architecture. + Another feature for the SDKs is that only one set of cross-compiler + toolchain binaries are produced for any given architecture. This feature takes advantage of the fact that the target 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 @@ -74,40 +86,122 @@ </para> <para> - Going beyond the actual SDK, the SDK development environment consists - of the following: + The SDK development environment consists of the following: <itemizedlist> - <listitem><para>An architecture-specific cross-toolchain and + <listitem><para>The self-contained SDK, which is an + architecture-specific cross-toolchain and matching sysroots (target and native) all built by the - OpenEmbedded build system. + OpenEmbedded build system (e.g. the SDK). The toolchain and sysroots are based on a <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> configuration and extensions, which allows you to cross-develop on the host machine for the target hardware. + Additionally, the extensible SDK contains the + <filename>devtool</filename> functionality. </para></listitem> <listitem><para>The Quick EMUlator (QEMU), which lets you simulate target hardware. QEMU is not literally part of the SDK. You must build and include this emulator separately. However, QEMU plays an important role in the development - process that revolves around use of and SDK. + process that revolves around use of the SDK. </para></listitem> <listitem><para>The Eclipse IDE Yocto Plug-in. - This plug-in is also available for you if you are an Eclipse + This plug-in is available for you if you are an Eclipse user. In the same manner as QEMU, the plug-in is not literally part of the SDK but is rather available for use as part of the development process. </para></listitem> - <listitem><para>Various user-space tools that greatly enhance - your application development experience. + <listitem><para>Various performance-related + <ulink url='http://www.eclipse.org/linuxtools/index.php'>tools</ulink> + that can enhance your development experience. These tools are also separate from the actual SDK but can be independently obtained and used in the development process. </para></listitem> </itemizedlist> </para> + <para> + In summary, the extensible and standard SDK share many features. + However, the extensible SDK has powerful development tools to help you + more quickly develop applications. + Following is a table that summarizes the primary differences between + the standard and extensible SDK types when considering which to + build: + <informaltable frame='none'> + <tgroup cols='3' align='left' colsep='1' rowsep='1'> + <colspec colname='c1' colwidth='1*'/> + <colspec colname='c2' colwidth='1*'/> + <colspec colname='c3' colwidth='1*'/> + <thead> + <row> + <entry align="left"><emphasis>Feature</emphasis></entry> + <entry align="left"><emphasis>Standard SDK</emphasis></entry> + <entry align="left"><emphasis>Extensible SDK</emphasis></entry> + </row> + </thead> + <tbody> + <row> + <entry align="left">Toolchain</entry> + <entry align="left">Yes</entry> + <entry align="left">Yes*</entry> + </row> + <row> + <entry align="left">Debugger</entry> + <entry align="left">Yes</entry> + <entry align="left">Yes*</entry> + </row> + <row> + <entry align="left">Size</entry> + <entry align="left">100+ MBytes</entry> + <entry align="left">1+ GBytes (or 300+ MBytes for minimal w/toolchain)</entry> + </row> + <row> + <entry align="left"><filename>devtool</filename></entry> + <entry align="left">No</entry> + <entry align="left">Yes</entry> + </row> + <row> + <entry align="left">Build Images</entry> + <entry align="left">No</entry> + <entry align="left">Yes</entry> + </row> + <row> + <entry align="left">Updateable</entry> + <entry align="left">No</entry> + <entry align="left">Yes</entry> + </row> + <row> + <entry align="left">Managed Sysroot**</entry> + <entry align="left">No</entry> + <entry align="left">Yes</entry> + </row> + <row> + <entry align="left">Installed Packages</entry> + <entry align="left">No***</entry> + <entry align="left">Yes****</entry> + </row> + <row> + <entry align="left">Construction</entry> + <entry align="left">Packages</entry> + <entry align="left">Shared State</entry> + </row> + </tbody> + </tgroup> + </informaltable> + <literallayout class='monospaced'> + * Extensible SDK will contain the toolchain and debugger if <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_EXT_TYPE'><filename>SDK_EXT_TYPE</filename></ulink> is "full" or <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_TOOLCHAIN'><filename>SDK_INCLUDE_TOOLCHAIN</filename></ulink> is "1", which is the default. + + ** Sysroot is managed through use of <filename>devtool</filename>. Thus, it is less likely that you will corrupt your SDK sysroot when you try to add additional libraries. + + *** Runtime package management can be added to the standard SDK but it is not supported by default. + + **** You must build and make the shared state available to extensible SDK users for "packages" you want to enable users to install. + </literallayout> + </para> + <section id='the-cross-development-toolchain'> <title>The Cross-Development Toolchain</title> @@ -117,7 +211,9 @@ consists of a cross-compiler, cross-linker, and cross-debugger that are used to develop user-space applications for targeted hardware. - This toolchain is created by running a toolchain installer script + Additionally, for an extensible SDK, the toolchain also has + built-in <filename>devtool</filename> functionality. + This toolchain is created by running a SDK installer script or through a <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> that is based on your Metadata configuration or extension for @@ -183,68 +279,36 @@ These extensions allow for cross-compilation, deployment, and execution of your output into a QEMU emulation session. You can also perform cross-debugging and profiling. - The environment also supports a suite of tools that allows you to - perform remote profiling, tracing, collection of power data, - collection of latency data, and collection of performance data. + The environment also supports many performance-related + <ulink url='http://www.eclipse.org/linuxtools/index.php'>tools</ulink> + that enhance your development experience. + <note> + Previous releases of the Eclipse Yocto Plug-in supported + "user-space tools" (i.e. LatencyTOP, PowerTOP, Perf, SystemTap, + and Lttng-ust) that also added to the development experience. + These tools have been deprecated beginning with this release + of the plug-in. + </note> </para> <para> For information about the application development workflow that uses the Eclipse IDE and for a detailed example of how to install and configure the Eclipse Yocto Project Plug-in, see the - "<link link='sdk-developing-applications-using-eclipse'>Developing Applications Using <trademark class='trade'>Eclipse</trademark></link>" + "<link linkend='sdk-developing-applications-using-eclipse'>Developing Applications Using <trademark class='trade'>Eclipse</trademark></link>" section. </para> </section> - <section id='user-space-tools'> - <title>User-Space Tools</title> + <section id='performance-enhancing-tools'> + <title>Performance Enhancing Tools</title> <para> - User-space tools are available as part of the SDK development - process and can be helpful. - The tools include LatencyTOP, PowerTOP, Perf, SystemTap, - and Lttng-ust. - These tools are common development tools for the Linux platform. - <itemizedlist> - <listitem><para><emphasis>LatencyTOP:</emphasis> LatencyTOP - focuses on latency that causes skips in audio, stutters in - your desktop experience, or situations that overload your - server even when you have plenty of CPU power left. - </para></listitem> - <listitem><para><emphasis>PowerTOP:</emphasis> Helps you - determine what software is using the most power. - You can find out more about PowerTOP at - <ulink url='https://01.org/powertop/'></ulink>.</para></listitem> - <listitem><para><emphasis>Perf:</emphasis> Performance counters - for Linux used to keep track of certain types of hardware - and software events. - For more information on these types of counters see - <ulink url='https://perf.wiki.kernel.org/'></ulink>. - For examples on how to setup and use this tool, see the - "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-perf'>perf</ulink>" - section in the Yocto Project Profiling and Tracing Manual. - </para></listitem> - <listitem><para><emphasis>SystemTap:</emphasis> A free software - infrastructure that simplifies information gathering about - a running Linux system. - This information helps you diagnose performance or - functional problems. - SystemTap is not available as a user-space tool through - the Eclipse IDE Yocto Plug-in. - See <ulink url='http://sourceware.org/systemtap'></ulink> - for more information on SystemTap. - For examples on how to setup and use this tool, see the - "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-systemtap'>SystemTap</ulink>" - section in the Yocto Project Profiling and Tracing Manual. - </para></listitem> - <listitem><para><emphasis>Lttng-ust:</emphasis> A User-space - Tracer designed to provide detailed information on - user-space activity. - See <ulink url='http://lttng.org/ust'></ulink> for more - information on Lttng-ust. - </para></listitem> - </itemizedlist> + Supported performance enhancing tools are available that let you + profile, debug, and perform tracing on your projects developed + using Eclipse. + For information on these tools see + <ulink url='http://www.eclipse.org/linuxtools/'>http://www.eclipse.org/linuxtools/</ulink>. </para> </section> </section> @@ -264,7 +328,7 @@ A developer can independently compile and test an object on their machine and then, when the object is ready for integration into an image, they can simply make it available to the machine that has the - the Yocto Project. + Yocto Project. Once the object is available, the image can be rebuilt using the Yocto Project to produce the modified image. </para> @@ -274,9 +338,9 @@ <orderedlist> <listitem><para><emphasis>Install the SDK for your target hardware:</emphasis> For information on how to install the SDK, see the - "<link url='sdk-installing-the-sdk'>Installing the SDK</link>" + "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>" section.</para></listitem> - <listitem><para><emphasis>Download the Target Image:</emphasis> + <listitem><para><emphasis>Download or Build the Target Image:</emphasis> The Yocto Project supports several target architectures and has many pre-built kernel images and root filesystem images.</para> @@ -303,12 +367,15 @@ 64-bit architecture). Download kernel, root filesystem, and any other files you need for your process. - <note>In order to use the root filesystem in QEMU, you - need to extract it. - See the - "<link url='sdk-extracting-the-root-filesystem'>Extracting the Root Filesystem</link>" - section for information on how to extract the root - filesystem.</note></para></listitem> + <note> + To use the root filesystem in QEMU, you + need to extract it. + See the + "<link linkend='sdk-extracting-the-root-filesystem'>Extracting the Root Filesystem</link>" + section for information on how to extract the root + filesystem. + </note> + </para></listitem> <listitem><para><emphasis>Develop and Test your Application:</emphasis> At this point, you have the tools to develop your application. @@ -316,7 +383,7 @@ emulator, you can go to <ulink url='http://wiki.qemu.org/Main_Page'>QEMU Home Page</ulink> to download and learn about the emulator. - You can see the + See the "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>" chapter in the Yocto Project Development Manual for information on using QEMU within the Yocto diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-manual-customization.xsl b/import-layers/yocto-poky/documentation/sdk-manual/sdk-manual-customization.xsl index dae992c07..efa8a84bb 100644 --- a/import-layers/yocto-poky/documentation/sdk-manual/sdk-manual-customization.xsl +++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-manual-customization.xsl @@ -1,12 +1,11 @@ <?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://downloads.yoctoproject.org/mirror/docbook-mirror/docbook-xsl-1.76.1/xhtml/docbook.xsl" /> ---> + <xsl:import href="http://downloads.yoctoproject.org/mirror/docbook-mirror/docbook-xsl-1.76.1/xhtml/docbook.xsl" /> +<!-- <xsl:import href="../template/1.76.1/docbook-xsl-1.76.1/xhtml/docbook.xsl" /> -<!-- <xsl:import href="http://docbook.sourceforge.net/release/xsl/1.76.1/xhtml/docbook.xsl" /> --> diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-manual-eclipse-customization.xsl b/import-layers/yocto-poky/documentation/sdk-manual/sdk-manual-eclipse-customization.xsl index 03555d6ca..77ba5f571 100644 --- a/import-layers/yocto-poky/documentation/sdk-manual/sdk-manual-eclipse-customization.xsl +++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-manual-eclipse-customization.xsl @@ -5,14 +5,12 @@ xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0"> -<!-- <xsl:import href="http://downloads.yoctoproject.org/mirror/docbook-mirror/docbook-xsl-1.76.1/eclipse/eclipse3.xsl" /> ---> - - <xsl:import href="../template/1.76.1/docbook-xsl-1.76.1/eclipse/eclipse3.xsl" /> <!-- + <xsl:import href="../template/1.76.1/docbook-xsl-1.76.1/eclipse/eclipse3.xsl" /> + <xsl:import href="http://docbook.sourceforge.net/release/xsl/1.76.1/eclipse/eclipse3.xsl" /> diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-manual.xml b/import-layers/yocto-poky/documentation/sdk-manual/sdk-manual.xml index c860782fb..6c72a0346 100644 --- a/import-layers/yocto-poky/documentation/sdk-manual/sdk-manual.xml +++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-manual.xml @@ -36,6 +36,11 @@ <date>April 2016</date> <revremark>Released with the Yocto Project 2.1 Release.</revremark> </revision> + <revision> + <revnumber>2.2</revnumber> + <date>October 2016</date> + <revremark>Released with the Yocto Project 2.2 Release.</revremark> + </revision> </revhistory> <copyright> @@ -61,14 +66,18 @@ <xi:include href="sdk-intro.xml"/> + <xi:include href="sdk-extensible.xml"/> + <xi:include href="sdk-using.xml"/> - <xi:include href="sdk-extensible.xml"/> + <xi:include href="sdk-working-projects.xml"/> <xi:include href="sdk-appendix-obtain.xml"/> <xi:include href="sdk-appendix-customizing.xml"/> + <xi:include href="sdk-appendix-mars.xml"/> + <!-- <index id='index'> <title>Index</title> </index> diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-using.xml b/import-layers/yocto-poky/documentation/sdk-manual/sdk-using.xml index 1ea47d3bb..7281e83ef 100644 --- a/import-layers/yocto-poky/documentation/sdk-manual/sdk-using.xml +++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-using.xml @@ -3,74 +3,82 @@ [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > <chapter id='sdk-using-the-standard-sdk'> - -<title>Using the Standard SDK</title> - -<para> - This chapter describes the standard SDK and how to use it. - Information covers the pieces of the SDK, how to install it, and presents - several task-based procedures common for developing with a standard SDK. - <note> - The tasks you can perform using a standard SDK are also applicable - when you are using an extensible SDK. - For information on the differences when using an extensible SDK as - compared to an extensible SDK, see the - "<link linkend='sdk-extensible'>Using the Extensible SDK</link>" - chapter. - </note> -</para> - -<section id='sdk-standard-sdk-intro'> - <title>Why use the Standard SDK and What is in It?</title> + <title>Using the Standard SDK</title> <para> - The Standard SDK provides a cross-development toolchain and libraries - tailored to the contents of a specific image. - You would use the Standard SDK if you want a more traditional toolchain - experience. + This chapter describes the standard SDK and how to install it. + Information includes unique installation and setup aspects for the + standard SDK. + <note> + For a side-by-side comparison of main features supported for a + standard SDK as compared to an extensible SDK, see the + "<link linkend='sdk-manual-intro'>Introduction</link>" + section. + </note> </para> <para> - The installed Standard SDK consists of several files and directories. - Basically, it contains an SDK environment setup script, some - configuration files, and host and target root filesystems to support - usage. - You can see the directory structure in the - "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>" - section. + You can use a standard SDK to work on Makefile, Autotools, and + Eclipse-based projects. + See the + "<link linkend='sdk-working-projects'>Working with Different Types of Projects</link>" + chapter for more information. </para> -</section> -<section id='sdk-installing-the-sdk'> - <title>Installing the SDK</title> + <section id='sdk-standard-sdk-intro'> + <title>Why use the Standard SDK and What is in It?</title> - <para> - The first thing you need to do is install the SDK on your host - development machine by running the <filename>.sh</filename> - installation script. - </para> + <para> + The Standard SDK provides a cross-development toolchain and + libraries tailored to the contents of a specific image. + You would use the Standard SDK if you want a more traditional + toolchain experience as compared to the extensible SDK, which + provides an internal build system and the + <filename>devtool</filename> functionality. + </para> - <para> - You can download a tarball installer, which includes the - pre-built toolchain, the <filename>runqemu</filename> - script, and support files from the appropriate directory under - <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>. - Toolchains are available for 32-bit and 64-bit x86 development - systems from the <filename>i686</filename> and - <filename>x86_64</filename> directories, respectively. - The toolchains the Yocto Project provides are based off the - <filename>core-image-sato</filename> image and contain - libraries appropriate for developing against that image. - Each type of development system supports five or more target - architectures. - </para> + <para> + The installed Standard SDK consists of several files and + directories. + Basically, it contains an SDK environment setup script, some + configuration files, and host and target root filesystems to + support usage. + You can see the directory structure in the + "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>" + section. + </para> + </section> - <para> - The names of the tarball installer scripts are such that a - string representing the host system appears first in the - filename and then is immediately followed by a string - representing the target architecture. - <literallayout class='monospaced'> + <section id='sdk-installing-the-sdk'> + <title>Installing the SDK</title> + + <para> + The first thing you need to do is install the SDK on your host + development machine by running the <filename>*.sh</filename> + installation script. + </para> + + <para> + You can download a tarball installer, which includes the + pre-built toolchain, the <filename>runqemu</filename> + script, and support files from the appropriate directory under + <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>. + Toolchains are available for 32-bit and 64-bit x86 development + systems from the <filename>i686</filename> and + <filename>x86_64</filename> directories, respectively. + The toolchains the Yocto Project provides are based off the + <filename>core-image-sato</filename> image and contain + libraries appropriate for developing against that image. + Each type of development system supports five or more target + architectures. + </para> + + <para> + The names of the tarball installer scripts are such that a + string representing the host system appears first in the + filename and then is immediately followed by a string + representing the target architecture. + <literallayout class='monospaced'> poky-glibc-<replaceable>host_system</replaceable>-<replaceable>image_type</replaceable>-<replaceable>arch</replaceable>-toolchain-<replaceable>release_version</replaceable>.sh Where: @@ -88,1378 +96,109 @@ Yocto Project: &DISTRO;, &DISTRO;+snapshot - </literallayout> - For example, the following toolchain installer is for a 64-bit - development host system and a i586-tuned target architecture - based off the SDK for <filename>core-image-sato</filename> and - using the current &DISTRO; snapshot: - <literallayout class='monospaced'> - poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh - </literallayout> - </para> - - <para> - The SDK and toolchains are self-contained and by default are installed - into <filename>/opt/poky</filename>. - However, when you run the SDK installer, you can choose an - installation directory. - <note> - You must change the permissions on the toolchain - installer script so that it is executable: - <literallayout class='monospaced'> - $ chmod +x poky-glibc-x86_64-core-image-sato-i586-toolchain-2.1.sh </literallayout> - </note> - </para> - - <para> - The following command shows how to run the installer given a - toolchain tarball for a 64-bit x86 development host system and - a 32-bit x86 target architecture. - The example assumes the toolchain installer is located in - <filename>~/Downloads/</filename>. - <note> - If you do not have write permissions for the directory - into which you are installing the SDK, the installer - notifies you and exits. - Be sure you have write permissions in the directory and - run the installer again. - </note> - <literallayout class='monospaced'> - $ ./poky-glibc-x86_64-core-image-sato-i586-toolchain-2.1.sh - Poky (Yocto Project Reference Distro) SDK installer version 2.0 - =============================================================== - Enter target directory for SDK (default: /opt/poky/2.1): - You are about to install the SDK to "/opt/poky/2.1". Proceed[Y/n]? Y - Extracting SDK.......................................................................done - Setting it up...done - SDK has been successfully set up and is ready to be used. - Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g. - $ . /opt/poky/2.1/environment-setup-i586-poky-linux - </literallayout> - </para> - - <para> - Again, reference the - "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>" - section for more details on the resulting directory structure of - the installed SDK. - </para> -</section> - -<section id='sdk-running-the-sdk-environment-setup-script'> - <title>Running the SDK Environment Setup Script</title> - - <para> - Once you have the SDK installed, you must run the SDK environment - setup script before you can actually use it. - This setup script resides in the directory you chose when you installed - the SDK. - For information on where this setup script can reside, see the - "<link linkend='sdk-appendix-obtain'>Obtaining the SDK</link>" - Appendix. - </para> - - <para> - Before running the script, be sure it is the one that matches the - architecture for which you are developing. - Environment setup scripts begin with the string - "<filename>environment-setup</filename>" and include as part of their - name the tuned target architecture. - For example, the command to source a setup script for an IA-based - target machine using i586 tuning and located in the default SDK - installation directory is as follows: - <literallayout class='monospaced'> - $ source /opt/poky/&DISTRO;/environment-setup-i586-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> - -<section id='autotools-based-projects'> - <title>Autotools-Based Projects</title> - - <para> - Once you have a suitable cross-toolchain installed, it is very easy to - develop a project outside of the OpenEmbedded build system. - This section presents a simple "Helloworld" example that shows how - to set up, compile, and run the project. - </para> - - <section id='creating-and-running-a-project-based-on-gnu-autotools'> - <title>Creating and Running a Project Based on GNU Autotools</title> - - <para> - Follow these steps to create a simple Autotools-based project: - <orderedlist> - <listitem><para><emphasis>Create your directory:</emphasis> - Create a clean directory for your project and then make - that directory your working location: - <literallayout class='monospaced'> - $ mkdir $HOME/helloworld - $ cd $HOME/helloworld - </literallayout></para></listitem> - <listitem><para><emphasis>Populate the directory:</emphasis> - Create <filename>hello.c</filename>, <filename>Makefile.am</filename>, - and <filename>configure.in</filename> files as follows: - <itemizedlist> - <listitem><para>For <filename>hello.c</filename>, include - these lines: - <literallayout class='monospaced'> - #include <stdio.h> - - main() - { - printf("Hello World!\n"); - } - </literallayout></para></listitem> - <listitem><para>For <filename>Makefile.am</filename>, - include these lines: - <literallayout class='monospaced'> - bin_PROGRAMS = hello - hello_SOURCES = hello.c - </literallayout></para></listitem> - <listitem><para>For <filename>configure.in</filename>, - include these lines: - <literallayout class='monospaced'> - AC_INIT(hello.c) - AM_INIT_AUTOMAKE(hello,0.1) - AC_PROG_CC - AC_PROG_INSTALL - AC_OUTPUT(Makefile) - </literallayout></para></listitem> - </itemizedlist></para></listitem> - <listitem><para><emphasis>Source the cross-toolchain - environment setup file:</emphasis> - Installation of the cross-toolchain creates a cross-toolchain - environment setup script in the directory that the SDK - was installed. - Before you can use the tools to develop your project, you must - source this setup script. - The script begins with the string "environment-setup" and contains - the machine architecture, which is followed by the string - "poky-linux". - Here is an example that sources a script from the - default SDK installation directory that uses 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 - </literallayout></para></listitem> - <listitem><para><emphasis>Generate the local aclocal.m4 - files and create the configure script:</emphasis> - The following GNU Autotools generate the local - <filename>aclocal.m4</filename> files and create the - configure script: - <literallayout class='monospaced'> - $ aclocal - $ autoconf - </literallayout></para></listitem> - <listitem><para><emphasis>Generate files needed by GNU - coding standards:</emphasis> - GNU coding standards require certain files in order for the - project to be compliant. - This command creates those files: - <literallayout class='monospaced'> - $ touch NEWS README AUTHORS ChangeLog - </literallayout></para></listitem> - <listitem><para><emphasis>Generate the configure - file:</emphasis> - This command generates the <filename>configure</filename>: - <literallayout class='monospaced'> - $ automake -a - </literallayout></para></listitem> - <listitem><para><emphasis>Cross-compile the project:</emphasis> - 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> - <listitem><para><emphasis>Make and install the project:</emphasis> - These two commands generate and install the project into the - destination directory: - <literallayout class='monospaced'> - $ make - $ make install DESTDIR=./tmp - </literallayout></para></listitem> - <listitem><para><emphasis>Verify the installation:</emphasis> - This command is a simple way to verify the installation - of your project. - Running the command prints the architecture on which - the binary file can run. - This architecture should be the same architecture that - the installed cross-toolchain supports. - <literallayout class='monospaced'> - $ file ./tmp/usr/local/bin/hello - </literallayout></para></listitem> - <listitem><para><emphasis>Execute your project:</emphasis> - To execute the project in the shell, simply enter the name. - You could also copy the binary to the actual target hardware - and run the project there as well: - <literallayout class='monospaced'> - $ ./hello - </literallayout> - As expected, the project displays the "Hello World!" message. - </para></listitem> - </orderedlist> - </para> - </section> - - <section id='passing-host-options'> - <title>Passing Host Options</title> - - <para> - For an Autotools-based project, you can use the cross-toolchain by just - passing the appropriate host option to <filename>configure.sh</filename>. - The host option you use is derived from the name of the environment setup - script found in the directory in which you installed the cross-toolchain. - For example, the host option for an ARM-based target that uses the GNU EABI - 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 to update your project and - rebuild it using the appropriate cross-toolchain tools: + For example, the following SDK installer is for a 64-bit + development host system and a i586-tuned target architecture + based off the SDK for <filename>core-image-sato</filename> and + using the current &DISTRO; snapshot: <literallayout class='monospaced'> - $ ./configure --host=armv5te-poky-linux-gnueabi \ - --with-libtool-sysroot=<replaceable>sysroot_dir</replaceable> + poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh </literallayout> <note> - If the <filename>configure</filename> script results in problems recognizing the - <filename>--with-libtool-sysroot=</filename><replaceable>sysroot-dir</replaceable> option, - regenerate the script to enable the support by doing the following and then - run the script again: - <literallayout class='monospaced'> - $ libtoolize --automake - $ aclocal -I ${OECORE_NATIVE_SYSROOT}/usr/share/aclocal \ - [-I <replaceable>dir_containing_your_project-specific_m4_macros</replaceable>] - $ autoconf - $ autoheader - $ automake -a - </literallayout> + As an alternative to downloading an SDK, you can build the + SDK installer. + For information on building the installer, see the + "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>" + section. + Another helpful resource for building an installer is the + <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>Cookbook guide to Making an Eclipse Debug Capable Image</ulink> + wiki page. + This wiki page focuses on development when using the Eclipse + IDE. </note> </para> - </section> -</section> - -<section id='makefile-based-projects'> - <title>Makefile-Based Projects</title> - - <para> - For Makefile-based projects, the cross-toolchain environment variables - established by running the cross-toolchain environment setup script - are subject to general <filename>make</filename> rules. - </para> - <para> - To illustrate this, consider the following four cross-toolchain - environment variables: - <literallayout class='monospaced'> - <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'>CC</ulink>=i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/1.8/sysroots/i586-poky-linux - <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'>LD</ulink>=i586-poky-linux-ld --sysroot=/opt/poky/1.8/sysroots/i586-poky-linux - <ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'>CFLAGS</ulink>=-O2 -pipe -g -feliminate-unused-debug-types - <ulink url='&YOCTO_DOCS_REF_URL;#var-CXXFLAGS'>CXXFLAGS</ulink>=-O2 -pipe -g -feliminate-unused-debug-types - </literallayout> - Now, consider the following three cases: - <itemizedlist> - <listitem><para><emphasis>Case 1 - No Variables Set in the <filename>Makefile</filename>:</emphasis> - Because these variables are not specifically set in the - <filename>Makefile</filename>, the variables retain their - values based on the environment. - </para></listitem> - <listitem><para><emphasis>Case 2 - Variables Set in the <filename>Makefile</filename>:</emphasis> - Specifically setting variables in the - <filename>Makefile</filename> during the build results in the - environment settings of the variables being overwritten. - </para></listitem> - <listitem><para><emphasis>Case 3 - Variables Set when the <filename>Makefile</filename> is Executed from the Command Line:</emphasis> - Executing the <filename>Makefile</filename> from the command - line results in the variables being overwritten with - command-line content regardless of what is being set in the - <filename>Makefile</filename>. - In this case, environment variables are not considered unless - you use the "-e" flag during the build: + <para> + The SDK and toolchains are self-contained and by default are + installed into <filename>/opt/poky</filename>. + However, when you run the SDK installer, you can choose an + installation directory. + <note> + You must change the permissions on the SDK + installer script so that it is executable: <literallayout class='monospaced'> - $ make -e <replaceable>file</replaceable> + $ chmod +x poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh </literallayout> - If you use this flag, then the environment values of the - variables override any variables specifically set in the - <filename>Makefile</filename>. - </para></listitem> - </itemizedlist> - <note> - For the list of variables set up by the cross-toolchain environment - setup script, see the - "<link linkend='sdk-running-the-sdk-environment-setup-script'>Running the SDK Environment Setup Script</link>" - section. - </note> - </para> -</section> - -<section id='sdk-developing-applications-using-eclipse'> - <title>Developing Applications Using <trademark class='trade'>Eclipse</trademark></title> - - <para> - If you are familiar with the popular Eclipse IDE, you can use an - Eclipse Yocto Plug-in to allow you to develop, deploy, and test your - application all from within Eclipse. - This section describes general workflow using the SDK and Eclipse - and how to configure and set up Eclipse. - </para> - - <section id='workflow-using-eclipse'> - - <title>Workflow Using <trademark class='trade'>Eclipse</trademark></title> - - <para> - The following figure and supporting list summarize the application - development general workflow that employs both the SDK Eclipse. + </note> </para> <para> - <imagedata fileref="figures/sdk-eclipse-dev-flow.png" - width="7in" depth="7in" align="center" scale="100" /> + The following command shows how to run the installer given a + toolchain tarball for a 64-bit x86 development host system and + a 32-bit x86 target architecture. + The example assumes the SDK installer is located in + <filename>~/Downloads/</filename>. + <note> + If you do not have write permissions for the directory + into which you are installing the SDK, the installer + notifies you and exits. + Be sure you have write permissions in the directory and + run the installer again. + </note> + <literallayout class='monospaced'> + $ ./poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh + Poky (Yocto Project Reference Distro) SDK installer version &DISTRO; + =============================================================== + Enter target directory for SDK (default: /opt/poky/&DISTRO;): + You are about to install the SDK to "/opt/poky/&DISTRO;". Proceed[Y/n]? Y + Extracting SDK.......................................................................done + Setting it up...done + SDK has been successfully set up and is ready to be used. + Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g. + $ . /opt/poky/&DISTRO;/environment-setup-i586-poky-linux + </literallayout> </para> <para> - <orderedlist> - <listitem><para><emphasis>Prepare the host system for the Yocto Project</emphasis>: - See - "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>" - and - "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>" sections both - in the Yocto Project Reference Manual for requirements. - In particular, be sure your host system has the - <filename>xterm</filename> package installed. - </para></listitem> - <listitem><para><emphasis>Secure the Yocto Project kernel target image</emphasis>: - You must have a target kernel image that has been built using the OpenEmbedded - build system.</para> - <para>Depending on whether the Yocto Project has a pre-built image that matches your target - architecture and where you are going to run the image while you develop your application - (QEMU or real hardware), the area from which you get the image differs. - <itemizedlist> - <listitem><para>Download the image from - <ulink url='&YOCTO_MACHINES_DL_URL;'><filename>machines</filename></ulink> - if your target architecture is supported and you are going to develop - and test your application on actual hardware.</para></listitem> - <listitem><para>Download the image from - <ulink url='&YOCTO_QEMU_DL_URL;'> - <filename>machines/qemu</filename></ulink> if your target architecture is supported - and you are going to develop and test your application using the QEMU - emulator.</para></listitem> - <listitem><para>Build your image if you cannot find a pre-built image that matches - your target architecture. - If your target architecture is similar to a supported architecture, you can - modify the kernel image before you build it. - See the - "<ulink url='&YOCTO_DOCS_DEV_URL;#patching-the-kernel'>Patching the Kernel</ulink>" - section in the Yocto Project Development - manual for an example.</para></listitem> - </itemizedlist></para> - <para>For information on pre-built kernel image naming schemes for images - that can run on the QEMU emulator, see the - <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-manual'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>. - </para></listitem> - <listitem><para><emphasis>Install the SDK</emphasis>: - The SDK provides a target-specific cross-development toolchain, the root filesystem, - the QEMU emulator, and other tools that can help you develop your application. - For information on how to install the SDK, see the - "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>" - section. - </para></listitem> - <listitem><para><emphasis>Secure the target root filesystem - and the Cross-development toolchain</emphasis>: - You need to find and download the appropriate root filesystem and - the cross-development toolchain.</para> - <para>You can find the tarballs for the root filesystem in the same area used - for the kernel image. - Depending on the type of image you are running, the root filesystem you need differs. - For example, if you are developing an application that runs on an image that - supports Sato, you need to get a root filesystem that supports Sato.</para> - <para>You can find the cross-development toolchains at - <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'><filename>toolchains</filename></ulink>. - Be sure to get the correct toolchain for your development host and your - target architecture. - See the "<link linkend='sdk-locating-pre-built-sdk-installers'>Locating Pre-Built SDK Installers</link>" - section for information and the - "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>" - section for installation information. - </para></listitem> - <listitem><para><emphasis>Create and build your application</emphasis>: - At this point, you need to have source files for your application. - Once you have the files, you can use the Eclipse IDE to import them and build the - project. - If you are not using Eclipse, you need to use the cross-development tools you have - installed to create the image.</para></listitem> - <listitem><para><emphasis>Deploy the image with the application</emphasis>: - If you are using the Eclipse IDE, you can deploy your image to the hardware or to - QEMU through the project's preferences. - If you are not using the Eclipse IDE, then you need to deploy the application - to the hardware using other methods. - Or, if you are using QEMU, you need to use that tool and - load your image in for testing. - See the - "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>" - chapter in the Yocto Project Development Manual - for information on using QEMU. - </para></listitem> - <listitem><para><emphasis>Test and debug the application</emphasis>: - Once your application is deployed, you need to test it. - Within the Eclipse IDE, you can use the debugging environment along with the - set of installed user-space tools to debug your application. - Of course, the same user-space tools are available separately if you choose - not to use the Eclipse IDE.</para></listitem> - </orderedlist> + Again, reference the + "<link linkend='sdk-installed-standard-sdk-directory-structure'>Installed Standard SDK Directory Structure</link>" + section for more details on the resulting directory structure of + the installed SDK. </para> </section> - <section id='adt-eclipse'> - <title>Working Within Eclipse</title> + <section id='sdk-running-the-sdk-environment-setup-script'> + <title>Running the SDK Environment Setup Script</title> <para> - 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 Luna - and Kepler versions of the Eclipse IDE. - Thus, the following information provides setup information for - both versions. - </note> + Once you have the SDK installed, you must run the SDK environment + setup script before you can actually use it. + This setup script resides in the directory you chose when you + installed the SDK. + For information on where this setup script can reside, see the + "<link linkend='sdk-appendix-obtain'>Obtaining the SDK</link>" + Appendix. </para> <para> - When you install and configure the Eclipse Yocto Project Plug-in - into the Eclipse IDE, you maximize your Yocto Project experience. - Installing and configuring the Plug-in results in an environment - that has extensions specifically designed to let you more easily - develop software. - These extensions allow for cross-compilation, deployment, and - execution of your output into a QEMU emulation session as well as - actual target hardware. - You can also perform cross-debugging and profiling. - The environment also supports a suite of tools that allows you - to perform remote profiling, tracing, collection of power data, - collection of latency data, and collection of performance data. - </para> - - <para> - This section describes how to install and configure the Eclipse IDE - Yocto Plug-in and how to use it to develop your application. + Before running the script, be sure it is the one that matches the + architecture for which you are developing. + Environment setup scripts begin with the string + "<filename>environment-setup</filename>" and include as part of + their name the tuned target architecture. + For example, the command to source a setup script for an IA-based + target machine using i586 tuning and located in the default SDK + installation directory is as follows: + <literallayout class='monospaced'> + $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux + </literallayout> + When you run the setup script, the same environment variables are + defined as are when you run the setup script for an extensible SDK. + See the + "<link linkend='sdk-running-the-extensible-sdk-environment-setup-script'>Running the Extensible SDK Environment Setup Script</link>" + section for more information. </para> - - <section id='setting-up-the-eclipse-ide'> - <title>Setting Up the Eclipse IDE</title> - - <para> - To develop within the Eclipse IDE, you need to do the following: - <orderedlist> - <listitem><para>Install the optimal version of the Eclipse - IDE.</para></listitem> - <listitem><para>Configure the Eclipse IDE. - </para></listitem> - <listitem><para>Install the Eclipse Yocto Plug-in. - </para></listitem> - <listitem><para>Configure the Eclipse Yocto Plug-in. - </para></listitem> - </orderedlist> - <note> - Do not install Eclipse from your distribution's package - repository. - Be sure to install Eclipse from the official Eclipse - download site as directed in the next section. - </note> - </para> - - <section id='installing-eclipse-ide'> - <title>Installing the Eclipse IDE</title> - - <para> - 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 Kepler to work with the Yocto Project. - </para> - - <para> - 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 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. - </para> - - <para> - Once you have downloaded the tarball, extract it into a - clean directory. - For example, the following commands unpack and install the - downloaded Eclipse IDE tarball into a clean directory - using the default name <filename>eclipse</filename>: - <literallayout class='monospaced'> - $ cd ~ - $ tar -xzvf ~/Downloads/eclipse-cpp-luna-SR2-linux-gtk-x86_64.tar.gz - </literallayout> - </para> - </section> - - <section id='configuring-the-eclipse-ide'> - <title>Configuring the Eclipse IDE</title> - - <para> - This section presents the steps needed to configure the - Eclipse IDE. - </para> - - <para> - Before installing and configuring the Eclipse Yocto Plug-in, - you need to configure the Eclipse IDE. - Follow these general steps: - <orderedlist> - <listitem><para>Start the Eclipse IDE.</para></listitem> - <listitem><para>Make sure you are in your Workbench and - select "Install New Software" from the "Help" - pull-down menu.</para></listitem> - <listitem><para>Select - <filename>Luna - &ECLIPSE_LUNA_URL;</filename> - from the "Work with:" pull-down menu. - <note> - 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>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. - 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 (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> - <listitem><para>Expand the box next to "Programming - Languages" and select the - <filename>C/C++ Autotools Support</filename> - and <filename>C/C++ Development Tools</filename> - 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> - </para> - </section> - - <section id='installing-the-eclipse-yocto-plug-in'> - <title>Installing or Accessing the Eclipse Yocto Plug-in</title> - - <para> - You can install the Eclipse Yocto Plug-in into the Eclipse - IDE one of two ways: use the Yocto Project's Eclipse - Update site to install the pre-built plug-in or build and - install the plug-in from the latest source code. - </para> - - <section id='new-software'> - <title>Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site</title> - - <para> - To install the Eclipse Yocto Plug-in from the update - site, follow these steps: - <orderedlist> - <listitem><para>Start up the Eclipse IDE. - </para></listitem> - <listitem><para>In Eclipse, select "Install New - Software" from the "Help" menu. - </para></listitem> - <listitem><para>Click "Add..." in the "Work with:" - area.</para></listitem> - <listitem><para>Enter - <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 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 - to the "Work with:" drop-down list. - </para></listitem> - <listitem><para>Select the entry for the plug-in - from the "Work with:" drop-down list. - </para></listitem> - <listitem><para>Check the boxes next to - <filename>Yocto Project ADT Plug-in</filename>, - <filename>Yocto Project Bitbake Commander Plug-in</filename>, - and - <filename>Yocto Project Documentation plug-in</filename>. - </para></listitem> - <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> - </section> - - <section id='zip-file-method'> - <title>Installing the Plug-in Using the Latest Source Code</title> - - <para> - To install the Eclipse Yocto Plug-in from the latest - source code, follow these steps: - <orderedlist> - <listitem><para>Be sure your development system - is not using OpenJDK to build the plug-in - by doing the following: - <orderedlist> - <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 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. - 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=~/<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 - </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-&DISTRO; - </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 building kepler, checkout the - <filename>kepler/yocto-&DISTRO;</filename> - branch. - </note> - </para></listitem> - <listitem><para>Change to the - <filename>scripts</filename> - directory within the Git repository: - <literallayout class='monospaced'> - $ cd scripts - </literallayout> - </para></listitem> - <listitem><para>Set up the local build environment - by running the setup script: - <literallayout class='monospaced'> - $ ./setup.sh - </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. - </para></listitem> - <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>luna/yocto-&DISTRO;</filename> tag, the - <filename>master</filename> documentation - branch, and - <filename>&DISTRO_NAME_NO_CAP;</filename> for the - release name: - <literallayout class='monospaced'> - $ ECLIPSE_HOME=/home/scottrif/eclipse-poky/scripts/eclipse ./build.sh luna/yocto-&DISTRO; master &DISTRO_NAME_NO_CAP; 2>&1 | tee -a build.log - </literallayout> - After running the script, the file - <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. - </para></listitem> - <listitem><para>Click "Add".</para></listitem> - <listitem><para>Provide anything you want in the - "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 - be the <filename>*archive.zip</filename> file - created by running the - <filename>build.sh</filename> script. - </para></listitem> - <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>Restart the Eclipse IDE if - necessary. - </para></listitem> - </orderedlist> - </para> - - <para> - At this point you should be able to configure the - Eclipse Yocto Plug-in as described in the - "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse Yocto Plug-in</link>" - section.</para> - </section> - </section> - - <section id='configuring-the-eclipse-yocto-plug-in'> - <title>Configuring the Eclipse Yocto Plug-in</title> - - <para> - Configuring the Eclipse Yocto Plug-in involves setting the - Cross Compiler options and the Target options. - The configurations you choose become the default settings - for all projects. - You do have opportunities to change them later when - you configure the project (see the following section). - </para> - - <para> - To start, you need to do the following from within the - Eclipse IDE: - <itemizedlist> - <listitem><para>Choose "Preferences" from the - "Window" menu to display the Preferences Dialog. - </para></listitem> - <listitem><para>Click "Yocto Project ADT" to display - the configuration screen. - </para></listitem> - </itemizedlist> - </para> - - <section id='configuring-the-cross-compiler-options'> - <title>Configuring the Cross-Compiler Options</title> - - <para> - To configure the Cross Compiler Options, you must select - the type of toolchain, point to the toolchain, specify - the sysroot location, and select the target - architecture. - <itemizedlist> - <listitem><para><emphasis>Selecting the Toolchain Type:</emphasis> - Choose between - <filename>Standalone pre-built toolchain</filename> - and - <filename>Build system derived toolchain</filename> - for Cross Compiler Options. - <itemizedlist> - <listitem><para><emphasis> - <filename>Standalone Pre-built Toolchain:</filename></emphasis> - Select this mode when you are using - a stand-alone cross-toolchain. - For example, suppose you are an - application developer and do not - need to build a target image. - Instead, you just want to use an - architecture-specific toolchain on - an existing kernel and target root - filesystem.</para></listitem> - <listitem><para><emphasis> - <filename>Build System Derived Toolchain:</filename></emphasis> - Select this mode if the - cross-toolchain has been installed - and built as part of the - <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. - When you select - <filename>Build system derived toolchain</filename>, - you are using the toolchain bundled - inside the Build Directory. - </para></listitem> - </itemizedlist> - </para></listitem> - <listitem><para><emphasis>Point to the Toolchain:</emphasis> - If you are using a stand-alone pre-built - toolchain, you should be pointing to where it is - installed. - See the - "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>" - section for information about how the SDK is - installed.</para> - <para>If you are using a system-derived - toolchain, the path you provide for the - <filename>Toolchain Root Location</filename> - field is the - <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. - See the - "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>" - section.</para></listitem> - <listitem><para><emphasis>Specify the Sysroot Location:</emphasis> - This location is where the root filesystem for - the target hardware resides. - </para> - <para>The location of - the sysroot filesystem depends on where you - separately extracted and installed the - filesystem.</para> - <para>For information on how to install the - toolchain and on how to extract and install the - sysroot filesystem, see the - "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>" - section. - </para></listitem> - <listitem><para><emphasis>Select the Target Architecture:</emphasis> - The target architecture is the type of hardware - you are going to use or emulate. - Use the pull-down - <filename>Target Architecture</filename> menu - to make your selection. - The pull-down menu should have the supported - architectures. - If the architecture you need is not listed in - the menu, you will need to build the image. - See the - "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>" - section of the Yocto Project Quick Start for - more information.</para></listitem> - </itemizedlist> - </para> - </section> - - <section id='configuring-the-target-options'> - <title>Configuring the Target Options</title> - - <para> - You can choose to emulate hardware using the QEMU - emulator, or you can choose to run your image on actual - hardware. - <itemizedlist> - <listitem><para><emphasis>QEMU:</emphasis> - Select this option if you will be using the - QEMU emulator. - If you are using the emulator, you also need to - locate the kernel and specify any custom - options.</para> - <para>If you selected - <filename>Build system derived toolchain</filename>, - the target kernel you built will be located in - the Build Directory in - <filename>tmp/deploy/images/<replaceable>machine</replaceable></filename> - directory. - If you selected - <filename>Standalone pre-built toolchain</filename>, - the pre-built image you downloaded is located - in the directory you specified when you - downloaded the image.</para> - <para>Most custom options are for advanced QEMU - users to further customize their QEMU instance. - These options are specified between paired - angled brackets. - Some options must be specified outside the - brackets. - In particular, the options - <filename>serial</filename>, - <filename>nographic</filename>, and - <filename>kvm</filename> must all be outside the - brackets. - Use the <filename>man qemu</filename> command - to get help on all the options and their use. - The following is an example: - <literallayout class='monospaced'> - serial ‘<-m 256 -full-screen>’ - </literallayout></para> - <para> - Regardless of the mode, Sysroot is already - defined as part of the Cross-Compiler Options - configuration in the - <filename>Sysroot Location:</filename> field. - </para></listitem> - <listitem><para><emphasis>External HW:</emphasis> - Select this option if you will be using actual - hardware.</para></listitem> - </itemizedlist> - </para> - - <para> - Click the "OK" to save your plug-in configurations. - </para> - </section> - </section> - </section> - - <section id='creating-the-project'> - <title>Creating the Project</title> - - <para> - You can create two types of projects: Autotools-based, or - Makefile-based. - This section describes how to create Autotools-based projects - from within the Eclipse IDE. - For information on creating Makefile-based projects in a - terminal window, see the - "<link linkend='makefile-based-projects'>Makefile-Based Projects</link>" - section. - <note> - Do not use special characters in project names - (e.g. spaces, underscores, etc.). Doing so can - cause configuration to fail. - </note> - </para> - - <para> - To create a project based on a Yocto template and then display - the source code, follow these steps: - <orderedlist> - <listitem><para>Select "Project" from the "File -> New" menu. - </para></listitem> - <listitem><para>Double click <filename>CC++</filename>. - </para></listitem> - <listitem><para>Double click <filename>C Project</filename> - to create the project.</para></listitem> - <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 - template.</para></listitem> - <listitem><para>Put a name in the <filename>Project name:</filename> - field. - Do not use hyphens as part of the name. - </para></listitem> - <listitem><para>Click "Next".</para></listitem> - <listitem><para>Add information in the - <filename>Author</filename> and - <filename>Copyright notice</filename> fields. - </para></listitem> - <listitem><para>Be sure the <filename>License</filename> - field is correct.</para></listitem> - <listitem><para>Click "Finish".</para></listitem> - <listitem><para>If the "open perspective" prompt appears, - click "Yes" so that you in the C/C++ perspective. - </para></listitem> - <listitem><para>The left-hand navigation pane shows your - project. - You can display your source by double clicking the - project's source file.</para></listitem> - </orderedlist> - </para> - </section> - - <section id='configuring-the-cross-toolchains'> - <title>Configuring the Cross-Toolchains</title> - - <para> - The earlier section, - "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse Yocto Plug-in</link>", - sets up the default project configurations. - You can override these settings for a given project by following - these steps: - <orderedlist> - <listitem><para>Select "Change Yocto Project Settings" from - the "Project" menu. - This selection brings up the Yocto Project Settings - Dialog and allows you to make changes specific to an - individual project.</para> - <para>By default, the Cross Compiler Options and Target - Options for a project are inherited from settings you - provided using the Preferences Dialog as described - earlier in the - "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse Yocto Plug-in</link>" section. - The Yocto Project Settings Dialog allows you to override - those default settings for a given project. - </para></listitem> - <listitem><para>Make your configurations for the project - and click "OK". - </para></listitem> - <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. - The script also runs <filename>libtoolize</filename>, - <filename>aclocal</filename>, - <filename>autoconf</filename>, - <filename>autoheader</filename>, - <filename>automake --a</filename>, and - <filename>./configure</filename>. - Click on the "Console" tab beneath your source code to - see the results of reconfiguring your project. - </para></listitem> - </orderedlist> - </para> - </section> - - <section id='building-the-project'> - <title>Building the Project</title> - - <para> - 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. - <note> - When building "Yocto Project ADT Autotools" projects, the Eclipse - IDE might display error messages for Functions/Symbols/Types - that cannot be "resolved", even when the related include file - is listed at the project navigator and when the project is - able to build. - For these cases only, it is recommended to add a new linked - folder to the appropriate sysroot. - Use these steps to add the linked folder: - <orderedlist> - <listitem><para> - Select the project. - </para></listitem> - <listitem><para> - Select "Folder" from the - <filename>File > New</filename> menu. - </para></listitem> - <listitem><para> - In the "New Folder" Dialog, select "Link to alternate - location (linked folder)". - </para></listitem> - <listitem><para> - Click "Browse" to navigate to the include folder inside - the same sysroot location selected in the Yocto Project - configuration preferences. - </para></listitem> - <listitem><para> - Click "OK". - </para></listitem> - <listitem><para> - Click "Finish" to save the linked folder. - </para></listitem> - </orderedlist> - </note> - </para> - </section> - - <section id='starting-qemu-in-user-space-nfs-mode'> - <title>Starting QEMU in User-Space NFS Mode</title> - - <para> - To start the QEMU emulator from within Eclipse, follow these - steps: - <note> - See the - "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>" - chapter in the Yocto Project Development Manual - for more information on using QEMU. - </note> - <orderedlist> - <listitem><para>Expose and select "External Tools" from - the "Run" menu. - 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> - <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 - needed for running in user-space NFS mode. - </para></listitem> - <listitem><para>Wait for QEMU to launch.</para></listitem> - <listitem><para>Once QEMU launches, you can begin operating - within that environment. - 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> - - <section id='deploying-and-debugging-the-application'> - <title>Deploying and Debugging the Application</title> - - <para> - Once the QEMU emulator is running the image, you can deploy - your application using the Eclipse IDE and then use - the emulator to perform debugging. - Follow these steps to deploy the application. - <note> - Currently, Eclipse does not support SSH port forwarding. - Consequently, if you need to run or debug a remote - application using the host display, you must create a - tunneling connection from outside Eclipse and keep - that connection alive during your work. - For example, in a new terminal, run the following: - <literallayout class='monospaced'> - ssh -XY user_name@remote_host_ip - </literallayout> - After running the command, add the command to be executed - in Eclipse's run configuration before the application - as follows: - <literallayout class='monospaced'> - export DISPLAY=:10.0 - </literallayout> - </note> - <orderedlist> - <listitem><para>Select "Debug Configurations..." from the - "Run" menu.</para></listitem> - <listitem><para>In the left area, expand - <filename>C/C++Remote Application</filename>. - </para></listitem> - <listitem><para>Locate your project and select it to bring - up a new tabbed view in the Debug Configurations Dialog. - </para></listitem> - <listitem><para>Enter the absolute path into which you want - to deploy the application. - Use the "Remote Absolute File Path for - C/C++Application:" field. - For example, enter - <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> - <listitem><para>Click on the "Main" tab.</para></listitem> - <listitem><para>Create a new connection to the QEMU instance - by clicking on "new".</para></listitem> - <listitem><para>Select <filename>TCF</filename>, which means - Target Communication Framework.</para></listitem> - <listitem><para>Click "Next".</para></listitem> - <listitem><para>Clear out the "host name" field and enter - the IP Address determined earlier.</para></listitem> - <listitem><para>Click "Finish" to close the - New Connections Dialog.</para></listitem> - <listitem><para>Use the drop-down menu now in the - "Connection" field and pick the IP Address you entered. - </para></listitem> - <listitem><para>Click "Debug" to bring up a login screen - and login.</para></listitem> - <listitem><para>Accept the debug perspective. - </para></listitem> - </orderedlist> - </para> - </section> - - <section id='running-user-space-tools'> - <title>Running User-Space Tools</title> - - <para> - As mentioned earlier in the manual, several tools exist that - enhance your development experience. - 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 "YoctoProjectTools" menu. - </para> - - <para> - Once you pick a tool, you need to configure it for the remote - target. - Every tool needs to have the connection configured. - You must select an existing TCF-based RSE connection to the - remote target. - If one does not exist, click "New" to create one. - </para> - - <para> - Here are some specifics about the remote tools: - <itemizedlist> - <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 - to graphically display the output. - For information on how to use Lttng to trace an - application, - see <ulink url='http://lttng.org/documentation'></ulink> - and the - "<ulink url='&YOCTO_DOCS_PROF_URL;#lttng-linux-trace-toolkit-next-generation'>LTTng (Linux Trace Toolkit, next generation)</ulink>" - section, which is in the Yocto Project Profiling and - Tracing Manual. - <note>Do not use - <filename>Lttng-user space (legacy)</filename> tool. - This tool no longer has any upstream support.</note> - </para> - <para>Before you use the - <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 "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. - </para></listitem> - <listitem><para>Create a new Tracing project by - selecting "Project" from the "File -> New" menu. - </para></listitem> - <listitem><para>Choose "Tracing Project" from the - "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 trace import" - from the "Yocto Project Tools" menu to - start the data import process.</para></listitem> - <listitem><para>Specify your remote connection name. - </para></listitem> - <listitem><para>For the Ust directory path, specify - the location of your remote tracing data. - Make sure the location ends with - <filename>ust</filename> (e.g. - <filename>/usr/mysession/ust</filename>). - </para></listitem> - <listitem><para>Click "OK" to complete the import - process. - The data is now in the local tracing project - you created.</para></listitem> - <listitem><para>Right click on the data and then use - the menu to Select "Generic CTF Trace" from the - "Trace Type... -> Common Trace Format" menu to - map the tracing type.</para></listitem> - <listitem><para>Right click the mouse and select - "Open" to bring up the Eclipse Lttng Trace - Viewer so you view the tracing data. - </para></listitem> - </orderedlist></para></listitem> - <listitem><para><emphasis><filename>PowerTOP</filename>:</emphasis> - Selecting this tool runs PowerTOP on the remote target - machine and displays the results in a new view called - PowerTOP.</para> - <para>The "Time to gather data(sec):" field is the time - passed in seconds before data is gathered from the - remote target for analysis.</para> - <para>The "show pids in wakeups list:" field corresponds - to the <filename>-p</filename> argument passed to - <filename>PowerTOP</filename>.</para></listitem> - <listitem><para><emphasis><filename>LatencyTOP and Perf</filename>:</emphasis> - LatencyTOP identifies system latency, while - Perf monitors the system's performance counter - registers. - Selecting either of these tools causes an RSE terminal - view to appear from which you can run the tools. - Both tools refresh the entire screen to display results - while they run. - For more information on setting up and using - <filename>perf</filename>, see the - "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-perf'>perf</ulink>" - 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> -</section> - </chapter> <!-- vim: expandtab tw=80 ts=4 diff --git a/import-layers/yocto-poky/documentation/sdk-manual/sdk-working-projects.xml b/import-layers/yocto-poky/documentation/sdk-manual/sdk-working-projects.xml new file mode 100644 index 000000000..df24aef0f --- /dev/null +++ b/import-layers/yocto-poky/documentation/sdk-manual/sdk-working-projects.xml @@ -0,0 +1,1460 @@ +<!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='sdk-working-projects'> + + <title>Using the SDK Toolchain Directly</title> + + <para> + You can use the SDK toolchain directly with Makefile, + Autotools, and <trademark class='trade'>Eclipse</trademark> based + projects. + This chapter covers information specific to each of these types of + projects. + </para> + + <section id='autotools-based-projects'> + <title>Autotools-Based Projects</title> + + <para> + Once you have a suitable cross-toolchain installed, it is very easy + to develop a project outside of the OpenEmbedded build system. + This section presents a simple "Helloworld" example that shows how + to set up, compile, and run the project. + </para> + + <section id='creating-and-running-a-project-based-on-gnu-autotools'> + <title>Creating and Running a Project Based on GNU Autotools</title> + + <para> + Follow these steps to create a simple Autotools-based project: + <orderedlist> + <listitem><para> + <emphasis>Create your directory:</emphasis> + Create a clean directory for your project and then make + that directory your working location: + <literallayout class='monospaced'> + $ mkdir $HOME/helloworld + $ cd $HOME/helloworld + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Populate the directory:</emphasis> + Create <filename>hello.c</filename>, + <filename>Makefile.am</filename>, + and <filename>configure.ac</filename> files as follows: + <itemizedlist> + <listitem><para> + For <filename>hello.c</filename>, include + these lines: + <literallayout class='monospaced'> + #include <stdio.h> + + main() + { + printf("Hello World!\n"); + } + </literallayout> + </para></listitem> + <listitem><para> + For <filename>Makefile.am</filename>, + include these lines: + <literallayout class='monospaced'> + bin_PROGRAMS = hello + hello_SOURCES = hello.c + </literallayout> + </para></listitem> + <listitem><para> + For <filename>configure.in</filename>, + include these lines: + <literallayout class='monospaced'> + AC_INIT(hello,0.1) + AM_INIT_AUTOMAKE([foreign]) + AC_PROG_CC + AC_PROG_INSTALL + AC_OUTPUT(Makefile) + </literallayout> + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para> + <emphasis>Source the cross-toolchain + environment setup file:</emphasis> + As described earlier in the manual, installing the + cross-toolchain creates a cross-toolchain + environment setup script in the directory that the SDK + was installed. + Before you can use the tools to develop your project, + you must source this setup script. + The script begins with the string "environment-setup" + and contains the machine architecture, which is + followed by the string "poky-linux". + Here is an example that sources a script from the + default SDK installation directory that uses 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 + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Generate the local aclocal.m4 + files and create the configure script:</emphasis> + The following GNU Autotools generate the local + <filename>aclocal.m4</filename> files and create the + configure script: + <literallayout class='monospaced'> + $ aclocal + $ autoconf + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Generate files needed by GNU coding + standards:</emphasis> + GNU coding standards require certain files in order + for the project to be compliant. + This command creates those files: + <literallayout class='monospaced'> + $ touch NEWS README AUTHORS ChangeLog + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Generate the configure file:</emphasis> + This command generates the + <filename>configure</filename>: + <literallayout class='monospaced'> + $ automake -a + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Cross-compile the project:</emphasis> + 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> + <listitem><para> + <emphasis>Make and install the project:</emphasis> + These two commands generate and install the project + into the destination directory: + <literallayout class='monospaced'> + $ make + $ make install DESTDIR=./tmp + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Verify the installation:</emphasis> + This command is a simple way to verify the installation + of your project. + Running the command prints the architecture on which + the binary file can run. + This architecture should be the same architecture that + the installed cross-toolchain supports. + <literallayout class='monospaced'> + $ file ./tmp/usr/local/bin/hello + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Execute your project:</emphasis> + To execute the project in the shell, simply enter + the name. + You could also copy the binary to the actual target + hardware and run the project there as well: + <literallayout class='monospaced'> + $ ./hello + </literallayout> + As expected, the project displays the "Hello World!" + message. + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='passing-host-options'> + <title>Passing Host Options</title> + + <para> + For an Autotools-based project, you can use the cross-toolchain + by just passing the appropriate host option to + <filename>configure.sh</filename>. + The host option you use is derived from the name of the + environment setup script found in the directory in which you + installed the cross-toolchain. + For example, the host option for an ARM-based target that uses + the GNU EABI 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 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> + </literallayout> + <note> + If the <filename>configure</filename> script results in + problems recognizing the + <filename>--with-libtool-sysroot=</filename><replaceable>sysroot-dir</replaceable> + option, regenerate the script to enable the support by + doing the following and then run the script again: + <literallayout class='monospaced'> + $ libtoolize --automake + $ aclocal -I ${OECORE_TARGET_SYSROOT}/usr/share/aclocal [-I <replaceable>dir_containing_your_project-specific_m4_macros</replaceable>] + $ autoconf + $ autoheader + $ automake -a + </literallayout> + </note> + </para> + </section> + </section> + + <section id='makefile-based-projects'> + <title>Makefile-Based Projects</title> + + <para> + For Makefile-based projects, the cross-toolchain environment + variables established by running the cross-toolchain environment + setup script are subject to general <filename>make</filename> + rules. + </para> + + <para> + To illustrate this, consider the following four cross-toolchain + environment variables: + <literallayout class='monospaced'> + <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'>CC</ulink>=i586-poky-linux-gcc -m32 -march=i586 --sysroot=/opt/poky/&DISTRO;/sysroots/i586-poky-linux + <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'>LD</ulink>=i586-poky-linux-ld --sysroot=/opt/poky/&DISTRO;/sysroots/i586-poky-linux + <ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'>CFLAGS</ulink>=-O2 -pipe -g -feliminate-unused-debug-types + <ulink url='&YOCTO_DOCS_REF_URL;#var-CXXFLAGS'>CXXFLAGS</ulink>=-O2 -pipe -g -feliminate-unused-debug-types + </literallayout> + Now, consider the following three cases: + <itemizedlist> + <listitem><para> + <emphasis>Case 1 - No Variables Set in the + <filename>Makefile</filename>:</emphasis> + Because these variables are not specifically set in the + <filename>Makefile</filename>, the variables retain their + values based on the environment. + </para></listitem> + <listitem><para> + <emphasis>Case 2 - Variables Set in the + <filename>Makefile</filename>:</emphasis> + Specifically setting variables in the + <filename>Makefile</filename> during the build results in + the environment settings of the variables being + overwritten. + </para></listitem> + <listitem><para> + <emphasis>Case 3 - Variables Set when the + <filename>Makefile</filename> is Executed from the + Command Line:</emphasis> + Executing the <filename>Makefile</filename> from the + command-line results in the variables being overwritten + with command-line content regardless of what is being set + in the <filename>Makefile</filename>. + In this case, environment variables are not considered + unless you use the "-e" flag during the build: + <literallayout class='monospaced'> + $ make -e <replaceable>file</replaceable> + </literallayout> + If you use this flag, then the environment values of the + variables override any variables specifically set in the + <filename>Makefile</filename>. + </para></listitem> + </itemizedlist> + <note> + For the list of variables set up by the cross-toolchain + environment setup script, see the + "<link linkend='sdk-running-the-sdk-environment-setup-script'>Running the SDK Environment Setup Script</link>" + section. + </note> + </para> + </section> + + <section id='sdk-developing-applications-using-eclipse'> + <title>Developing Applications Using <trademark class='trade'>Eclipse</trademark></title> + + <para> + If you are familiar with the popular Eclipse IDE, you can use an + Eclipse Yocto Plug-in to allow you to develop, deploy, and test your + application all from within Eclipse. + This section describes general workflow using the SDK and Eclipse + and how to configure and set up Eclipse. + </para> + + <section id='workflow-using-eclipse'> + <title>Workflow Using <trademark class='trade'>Eclipse</trademark></title> + + <para> + The following figure and supporting list summarize the + application development general workflow that employs both the + SDK Eclipse. + </para> + + <para> + <imagedata fileref="figures/sdk-eclipse-dev-flow.png" + width="7in" depth="7in" align="center" scale="100" /> + </para> + + <para> + <orderedlist> + <listitem><para> + <emphasis>Prepare the host system for the Yocto + Project</emphasis>: + See + "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>" + and + "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>" + sections both in the Yocto Project Reference Manual for + requirements. + In particular, be sure your host system has the + <filename>xterm</filename> package installed. + </para></listitem> + <listitem><para> + <emphasis>Secure the Yocto Project kernel target + image</emphasis>: + You must have a target kernel image that has been built + using the OpenEmbedded build system.</para> + <para>Depending on whether the Yocto Project has a + pre-built image that matches your target architecture + and where you are going to run the image while you + develop your application (QEMU or real hardware), the + area from which you get the image differs. + <itemizedlist> + <listitem><para> + Download the image from + <ulink url='&YOCTO_MACHINES_DL_URL;'><filename>machines</filename></ulink> + if your target architecture is supported and + you are going to develop and test your + application on actual hardware. + </para></listitem> + <listitem><para> + Download the image from + <ulink url='&YOCTO_QEMU_DL_URL;'> + <filename>machines/qemu</filename></ulink> if + your target architecture is supported and you + are going to develop and test your application + using the QEMU emulator. + </para></listitem> + <listitem><para> + Build your image if you cannot find a pre-built + image that matches your target architecture. + If your target architecture is similar to a + supported architecture, you can modify the + kernel image before you build it. + See the + "<ulink url='&YOCTO_DOCS_DEV_URL;#patching-the-kernel'>Patching the Kernel</ulink>" + section in the Yocto Project Development + manual for an example. + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem> + <para><emphasis>Install the SDK</emphasis>: + The SDK provides a target-specific cross-development + toolchain, the root filesystem, the QEMU emulator, and + other tools that can help you develop your application. + For information on how to install the SDK, see the + "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>" + section. + </para></listitem> + <listitem><para> + <emphasis>Secure the target root filesystem + and the Cross-development toolchain</emphasis>: + You need to find and download the appropriate root + filesystem and the cross-development toolchain.</para> + <para>You can find the tarballs for the root filesystem + in the same area used for the kernel image. + Depending on the type of image you are running, the + root filesystem you need differs. + For example, if you are developing an application that + runs on an image that supports Sato, you need to get a + root filesystem that supports Sato.</para> + <para>You can find the cross-development toolchains at + <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'><filename>toolchains</filename></ulink>. + Be sure to get the correct toolchain for your + development host and your target architecture. + See the "<link linkend='sdk-locating-pre-built-sdk-installers'>Locating Pre-Built SDK Installers</link>" + section for information and the + "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>" + section for installation information. + <note> + As an alternative to downloading an SDK, you can + build the SDK installer. + For information on building the installer, see the + "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>" + section. + Another helpful resource for building an installer + is the + <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>Cookbook guide to Making an Eclipse Debug Capable Image</ulink> + wiki page. + </note> + </para></listitem> + <listitem><para> + <emphasis>Create and build your application</emphasis>: + At this point, you need to have source files for your + application. + Once you have the files, you can use the Eclipse IDE + to import them and build the project. + If you are not using Eclipse, you need to use the + cross-development tools you have installed to create + the image.</para></listitem> + <listitem><para> + <emphasis>Deploy the image with the + application</emphasis>: + Using the Eclipse IDE, you can deploy your image to the + hardware or to QEMU through the project's preferences. + You can also use Eclipse to load and test your image + under 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 + for information on using QEMU. + </para></listitem> + <listitem><para> + <emphasis>Test and debug the application</emphasis>: + Once your application is deployed, you need to test it. + Within the Eclipse IDE, you can use the debugging + environment along with supported performance enhancing + <ulink url='http://www.eclipse.org/linuxtools/'>Linux Tools</ulink>. + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='adt-eclipse'> + <title>Working Within Eclipse</title> + + <para> + The Eclipse IDE is a popular development environment and it + fully supports development using the Yocto Project. + </para> + + <para> + When you install and configure the Eclipse Yocto Project + Plug-in into the Eclipse IDE, you maximize your Yocto + Project experience. + Installing and configuring the Plug-in results in an + environment that has extensions specifically designed to let + you more easily develop software. + These extensions allow for cross-compilation, deployment, and + execution of your output into a QEMU emulation session as well + as actual target hardware. + You can also perform cross-debugging and profiling. + The environment also supports performance enhancing + <ulink url='http://www.eclipse.org/linuxtools/'>tools</ulink> + that allow you to perform remote profiling, tracing, + collection of power data, collection of latency data, and + collection of performance data. + <note> + This release of the Yocto Project supports both the Neon + and Mars versions of the Eclipse IDE. + This section provides information on how to use the Neon + release with the Yocto Project. + For information on how to use the Mars version of Eclipse + with the Yocto Project, see + "<link linkend='sdk-appendix-mars'>Appendix C</link>. + </note> + </para> + + <section id='neon-setting-up-the-eclipse-ide'> + <title>Setting Up the Neon Version of the Eclipse IDE</title> + + <para> + To develop within the Eclipse IDE, you need to do the + following: + <orderedlist> + <listitem><para> + Install the Neon version of the Eclipse IDE. + </para></listitem> + <listitem><para> + Configure the Eclipse IDE. + </para></listitem> + <listitem><para> + Install the Eclipse Yocto Plug-in. + </para></listitem> + <listitem><para> + Configure the Eclipse Yocto Plug-in. + </para></listitem> + </orderedlist> + <note> + Do not install Eclipse from your distribution's package + repository. + Be sure to install Eclipse from the official Eclipse + download site as directed in the next section. + </note> + </para> + + <section id='neon-installing-eclipse-ide'> + <title>Installing the Neon Eclipse IDE</title> + + <para> + Follow these steps to locate, install, and configure + Neon Eclipse: + <orderedlist> + <listitem><para> + <emphasis>Locate the Neon Download:</emphasis> + Open a browser and go to + <ulink url='http://www.eclipse.org/mars/'>http://www.eclipse.org/neon/</ulink>. + </para></listitem> + <listitem><para> + <emphasis>Download the Tarball:</emphasis> + Click through the "Download" buttons to + download the file. + </para></listitem> + <listitem><para> + <emphasis>Unpack the Tarball:</emphasis> + Move to a clean directory and unpack the + tarball. + Here is an example: + <literallayout class='monospaced'> + $ cd ~ + $ tar -xzvf ~/Downloads/eclipse-inst-linux64.tar.gz + </literallayout> + Everything unpacks into a folder named + "eclipse-installer". + </para></listitem> + <listitem><para> + <emphasis>Launch the Installer:</emphasis> + Use the following commands to launch the + installer: + <literallayout class='monospaced'> + $ cd ~/eclipse-installer + $ ./eclipse-inst + </literallayout> + </para></listitem> + <listitem><para> + <emphasis>Select Your IDE:</emphasis> + From the list, select the "Eclipse IDE for + C/C++ Developers". + </para></listitem> + <listitem><para> + <emphasis>Install the Software:</emphasis> + Accept the default "cpp-neon" directory and + click "Install". + Accept any license agreements and approve any + certificates. + </para></listitem> + <listitem><para> + <emphasis>Launch Neon:</emphasis> + Click the "Launch" button and accept the + default "workspace". + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='neon-configuring-the-mars-eclipse-ide'> + <title>Configuring the Neon Eclipse IDE</title> + + <para> + Follow these steps to configure the Neon Eclipse IDE. + <note> + Depending on how you installed Eclipse and what + you have already done, some of the options will + not appear. + If you cannot find an option as directed by the + manual, it has already been installed. + </note> + <orderedlist> + <listitem><para> + Be sure Eclipse is running and you are in your + workbench. + </para></listitem> + <listitem><para> + Select "Install New Software" from the "Help" + pull-down menu. + </para></listitem> + <listitem><para> + Select + "Neon - http://download.eclipse.org/releases/neon" + from the "Work with:" pull-down menu. + </para></listitem> + <listitem><para> + Expand the box next to "Linux Tools" and select + the following: + <literallayout class='monospaced'> + C/C++ Remote (Over TCF/TE) Run/Debug Launcher + TM Terminal + </literallayout> + </para></listitem> + <listitem><para> + Expand the box next to "Mobile and Device + Development" and select the following + boxes: + <literallayout class='monospaced'> + C/C++ Remote (Over TCF/TE) Run/Debug Launcher + Remote System Explorer User Actions + TM Terminal + TCF Remote System Explorer add-in + TCF Target Explorer + </literallayout> + </para></listitem> + <listitem><para> + Expand the box next to "Programming Languages" + and select the following box: + <literallayout class='monospaced'> + C/C++ Development Tools SDK + </literallayout> + </para></listitem> + <listitem><para> + Complete the installation by clicking through + appropriate "Next" and "Finish" buttons. + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='neon-installing-the-eclipse-yocto-plug-in'> + <title>Installing or Accessing the Neon Eclipse Yocto Plug-in</title> + + <para> + You can install the Eclipse Yocto Plug-in into the + Eclipse IDE one of two ways: use the Yocto Project's + Eclipse Update site to install the pre-built plug-in + or build and install the plug-in from the latest + source code. + </para> + + <section id='neon-new-software'> + <title>Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site</title> + + <para> + To install the Neon Eclipse Yocto Plug-in from the + update site, follow these steps: + <orderedlist> + <listitem><para> + Start up the Eclipse IDE. + </para></listitem> + <listitem><para> + In Eclipse, select "Install New + Software" from the "Help" menu. + </para></listitem> + <listitem><para> + Click "Add..." in the "Work with:" area. + </para></listitem> + <listitem><para> + Enter + <filename>&ECLIPSE_DL_PLUGIN_URL;/neon</filename> + in the URL field and provide a meaningful + name in the "Name" field. + </para></listitem> + <listitem><para> + Click "OK" to have the entry added + to the "Work with:" drop-down list. + </para></listitem> + <listitem><para> + Select the entry for the plug-in + from the "Work with:" drop-down list. + </para></listitem> + <listitem><para> + Check the boxes next to the following: + <literallayout class='monospaced'> + Yocto Project SDK Plug-in + Yocto Project Documentation plug-in + </literallayout> + </para></listitem> + <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> + </section> + + <section id='neon-zip-file-method'> + <title>Installing the Plug-in Using the Latest Source Code</title> + + <para> + To install the Neon Eclipse Yocto Plug-in from the + latest source code, follow these steps: + <orderedlist> + <listitem><para> + Be sure your development system + has JDK 1.8+ + </para></listitem> + <listitem><para> + Install X11-related packages: + <literallayout class='monospaced'> + $ sudo apt-get install xauth + </literallayout> + </para></listitem> + <listitem><para> + In a new terminal shell, create a + Git repository with: + <literallayout class='monospaced'> + $ cd ~ + $ git clone git://git.yoctoproject.org/eclipse-poky + </literallayout> + </para></listitem> + <listitem><para> + Use Git to create the correct tag: + <literallayout class='monospaced'> + $ cd ~/eclipse-poky + $ git checkout neon/yocto-&DISTRO; + </literallayout> + This creates a local tag named + <filename>neon/yocto-&DISTRO;</filename> + based on the branch + <filename>origin/neon-master</filename>. + You are put into a detached HEAD state, + which is fine since you are only going to + be building and not developing. + </para></listitem> + <listitem><para> + Change to the <filename>scripts</filename> + directory within the Git repository: + <literallayout class='monospaced'> + $ cd scripts + </literallayout> + </para></listitem> + <listitem><para> + Set up the local build environment + by running the setup script: + <literallayout class='monospaced'> + $ ./setup.sh + </literallayout> + 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. + </para></listitem> + <listitem><para> + Run the <filename>build.sh</filename> + script as directed. + Be sure to provide the tag name, + documentation branch, and a release name. + </para> + <para> + Following is an example: + <literallayout class='monospaced'> + $ ECLIPSE_HOME=/home/scottrif/eclipse-poky/scripts/eclipse ./build.sh -l neon/yocto-&DISTRO; master yocto-&DISTRO; 2>&1 | tee build.log + </literallayout> + The previous example command adds the tag + you need for + <filename>mars/yocto-&DISTRO;</filename> + to <filename>HEAD</filename>, then tells + the build script to use the local (-l) Git + checkout for the build. + After running the script, the file + <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. + </para></listitem> + <listitem><para> + Click "Add". + </para></listitem> + <listitem><para> + Provide anything you want in the + "Name" field. + </para></listitem> + <listitem><para> + Click "Archive" and browse to the + ZIP file you built earlier. + This ZIP file should not be "unzipped", and + must be the + <filename>*archive.zip</filename> file + created by running the + <filename>build.sh</filename> script. + </para></listitem> + <listitem><para> + Click the "OK" button. + </para></listitem> + <listitem><para> + Check the boxes that appear in + the installation window to install the + following: + <literallayout class='monospaced'> + Yocto Project SDK Plug-in + Yocto Project Documentation plug-in + </literallayout> + </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> + Restart the Eclipse IDE if necessary. + </para></listitem> + </orderedlist> + </para> + + <para> + At this point you should be able to configure the + Eclipse Yocto Plug-in as described in the + "<link linkend='mars-configuring-the-eclipse-yocto-plug-in'>Configuring the Neon Eclipse Yocto Plug-in</link>" + section. + </para> + </section> + </section> + + <section id='neon-configuring-the-eclipse-yocto-plug-in'> + <title>Configuring the Neon Eclipse Yocto Plug-in</title> + + <para> + Configuring the Neon Eclipse Yocto Plug-in involves + setting the Cross Compiler options and the Target + options. + The configurations you choose become the default + settings for all projects. + You do have opportunities to change them later when + you configure the project (see the following section). + </para> + + <para> + To start, you need to do the following from within the + Eclipse IDE: + <itemizedlist> + <listitem><para> + Choose "Preferences" from the "Window" menu to + display the Preferences Dialog. + </para></listitem> + <listitem><para> + Click "Yocto Project SDK" to display + the configuration screen. + </para></listitem> + </itemizedlist> + The following sub-sections describe how to configure + the plug-in. + <note> + Throughout the descriptions, a start-to-finish + example for preparing a QEMU image for use with + Eclipse is referenced as the "wiki" and is linked + to the example on the + <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'> Cookbook guide to Making an Eclipse Debug Capable Image</ulink> + wiki page. + </note> + </para> + + <section id='neon-configuring-the-cross-compiler-options'> + <title>Configuring the Cross-Compiler Options</title> + + <para> + Cross Compiler options enable Eclipse to use your + specific cross compiler toolchain. + To configure these options, you must select + the type of toolchain, point to the toolchain, + specify the sysroot location, and select the target + architecture. + <itemizedlist> + <listitem><para> + <emphasis>Selecting the Toolchain + Type:</emphasis> + Choose between + <filename>Standalone pre-built toolchain</filename> + and + <filename>Build system derived toolchain</filename> + for Cross Compiler Options. + <itemizedlist> + <listitem><para> + <emphasis> + <filename>Standalone Pre-built Toolchain:</filename> + </emphasis> + Select this type when you are using + a stand-alone cross-toolchain. + For example, suppose you are an + application developer and do not + need to build a target image. + Instead, you just want to use an + architecture-specific toolchain on + an existing kernel and target root + filesystem. + In other words, you have downloaded + and installed a pre-built toolchain + for an existing image. + </para></listitem> + <listitem><para> + <emphasis> + <filename>Build System Derived Toolchain:</filename> + </emphasis> + Select this type if you built the + toolchain as part of the + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. + When you select + <filename>Build system derived toolchain</filename>, + you are using the toolchain built + and bundled inside the Build + Directory. + For example, suppose you created a + suitable image using the steps in the + <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>. + In this situation, you would select + the + <filename>Build system derived toolchain</filename>. + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para> + <emphasis>Specify the Toolchain Root + Location:</emphasis> + If you are using a stand-alone pre-built + toolchain, you should be pointing to where + it is installed (e.g. + <filename>/opt/poky/&DISTRO;</filename>). + See the + "<link linkend='sdk-installing-the-sdk'>Installing the SDK</link>" + section for information about how the SDK is + installed.</para> + <para>If you are using a build system + derived toolchain, the path you provide for + the + <filename>Toolchain Root Location</filename> + field is the + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> + from which you run the + <filename>bitbake</filename> command (e.g + <filename>/home/scottrif/poky/build</filename>). + </para> + <para>For more information, see the + "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>" + section. + </para></listitem> + <listitem><para> + <emphasis>Specify Sysroot Location: + </emphasis> + This location is where the root filesystem + for the target hardware resides. + </para> + <para>This location depends on where you + separately extracted and installed the + target filesystem. + As an example, suppose you prepared an + image using the steps in the + <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>. + If so, the + <filename>MY_QEMU_ROOTFS</filename> + directory is found in the + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> + and you would browse to and select that + directory (e.g. + <filename>/home/scottrif/poky/build/MY_QEMU_ROOTFS</filename>). + </para> + <para>For more information on how to + install the toolchain and on how to extract + and install the sysroot filesystem, see the + "<link linkend='sdk-building-an-sdk-installer'>Building an SDK Installer</link>" + section. + </para></listitem> + <listitem><para> + <emphasis>Select the Target Architecture: + </emphasis> + The target architecture is the type of + hardware you are going to use or emulate. + Use the pull-down + <filename>Target Architecture</filename> + menu to make your selection. + The pull-down menu should have the + supported architectures. + If the architecture you need is not listed + in the menu, you will need to build the + image. + See the + "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>" + section of the Yocto Project Quick Start + for more information. + You can also see the + <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='neon-configuring-the-target-options'> + <title>Configuring the Target Options</title> + + <para> + You can choose to emulate hardware using the QEMU + emulator, or you can choose to run your image on + actual hardware. + <itemizedlist> + <listitem><para> + <emphasis>QEMU:</emphasis> + Select this option if you will be using the + QEMU emulator. + If you are using the emulator, you also + need to locate the kernel and specify any + custom options.</para> + <para>If you selected the + <filename>Build system derived toolchain</filename>, + the target kernel you built will be located + in the + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> + in + <filename>tmp/deploy/images/<replaceable>machine</replaceable></filename> + directory. + As an example, suppose you performed the + steps in the + <ulink url='https://wiki.yoctoproject.org/wiki/TipsAndTricks/RunningEclipseAgainstBuiltImage'>wiki</ulink>. + In this case, you specify your Build + Directory path followed by the image (e.g. + <filename>/home/scottrif/poky/build/tmp/deploy/images/qemux86/bzImage-qemux86.bin</filename>). + </para> + <para>If you selected the standalone + pre-built toolchain, the pre-built image + you downloaded is located in the directory + you specified when you downloaded the + image.</para> + <para>Most custom options are for advanced + QEMU users to further customize their QEMU + instance. + These options are specified between paired + angled brackets. + Some options must be specified outside the + brackets. + In particular, the options + <filename>serial</filename>, + <filename>nographic</filename>, and + <filename>kvm</filename> must all be + outside the brackets. + Use the <filename>man qemu</filename> + command to get help on all the options and + their use. + The following is an example: + <literallayout class='monospaced'> + serial ‘<-m 256 -full-screen>’ + </literallayout></para> + <para> + Regardless of the mode, Sysroot is already + defined as part of the Cross-Compiler + Options configuration in the + <filename>Sysroot Location:</filename> + field. + </para></listitem> + <listitem><para> + <emphasis>External HW:</emphasis> + Select this option if you will be using + actual hardware.</para></listitem> + </itemizedlist> + </para> + + <para> + Click the "Apply" and "OK" to save your plug-in + configurations. + </para> + </section> + </section> + </section> + + <section id='neon-creating-the-project'> + <title>Creating the Project</title> + + <para> + You can create two types of projects: Autotools-based, or + Makefile-based. + This section describes how to create Autotools-based + projects from within the Eclipse IDE. + For information on creating Makefile-based projects in a + terminal window, see the + "<link linkend='makefile-based-projects'>Makefile-Based Projects</link>" + section. + <note> + Do not use special characters in project names + (e.g. spaces, underscores, etc.). Doing so can + cause configuration to fail. + </note> + </para> + + <para> + To create a project based on a Yocto template and then + display the source code, follow these steps: + <orderedlist> + <listitem><para> + Select "C Project" from the "File -> New" menu. + </para></listitem> + <listitem><para> + Expand + <filename>Yocto Project SDK Autotools Project</filename>. + </para></listitem> + <listitem><para> + Select <filename>Hello World ANSI C Autotools Projects</filename>. + This is an Autotools-based project based on a Yocto + template. + </para></listitem> + <listitem><para> + Put a name in the + <filename>Project name:</filename> field. + Do not use hyphens as part of the name + (e.g. <filename>hello</filename>). + </para></listitem> + <listitem><para> + Click "Next". + </para></listitem> + <listitem><para> + Add appropriate information in the various fields. + </para></listitem> + <listitem><para> + Click "Finish". + </para></listitem> + <listitem><para> + If the "open perspective" prompt appears, + click "Yes" so that you in the C/C++ perspective. + </para></listitem> + <listitem><para>The left-hand navigation pane shows + your project. + You can display your source by double clicking the + project's source file. + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='neon-configuring-the-cross-toolchains'> + <title>Configuring the Cross-Toolchains</title> + + <para> + The earlier section, + "<link linkend='neon-configuring-the-eclipse-yocto-plug-in'>Configuring the Neon Eclipse Yocto Plug-in</link>", + sets up the default project configurations. + You can override these settings for a given project by + following these steps: + <orderedlist> + <listitem><para> + Select "Yocto Project Settings" from + the "Project -> Properties" menu. + This selection brings up the Yocto Project Settings + Dialog and allows you to make changes specific to + an individual project.</para> + <para>By default, the Cross Compiler Options and + Target Options for a project are inherited from + settings you provided using the Preferences Dialog + as described earlier in the + "<link linkend='neon-configuring-the-eclipse-yocto-plug-in'>Configuring the Neon Eclipse Yocto Plug-in</link>" + section. + The Yocto Project Settings Dialog allows you to + override those default settings for a given + project. + </para></listitem> + <listitem><para> + Make or verify your configurations for the + project and click "OK". + </para></listitem> + <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. + The script also runs + <filename>libtoolize</filename>, + <filename>aclocal</filename>, + <filename>autoconf</filename>, + <filename>autoheader</filename>, + <filename>automake --a</filename>, and + <filename>./configure</filename>. + Click on the "Console" tab beneath your source code + to see the results of reconfiguring your project. + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='neon-building-the-project'> + <title>Building the Project</title> + + <para> + To build the project select "Build All" from the + "Project" menu. + The console should update and you can note the + cross-compiler you are using. + <note> + When building "Yocto Project SDK Autotools" projects, + the Eclipse IDE might display error messages for + Functions/Symbols/Types that cannot be "resolved", + even when the related include file is listed at the + project navigator and when the project is able to + build. + For these cases only, it is recommended to add a new + linked folder to the appropriate sysroot. + Use these steps to add the linked folder: + <orderedlist> + <listitem><para> + Select the project. + </para></listitem> + <listitem><para> + Select "Folder" from the + <filename>File > New</filename> menu. + </para></listitem> + <listitem><para> + In the "New Folder" Dialog, select "Link to + alternate location (linked folder)". + </para></listitem> + <listitem><para> + Click "Browse" to navigate to the include + folder inside the same sysroot location + selected in the Yocto Project + configuration preferences. + </para></listitem> + <listitem><para> + Click "OK". + </para></listitem> + <listitem><para> + Click "Finish" to save the linked folder. + </para></listitem> + </orderedlist> + </note> + </para> + </section> + + <section id='neon-starting-qemu-in-user-space-nfs-mode'> + <title>Starting QEMU in User-Space NFS Mode</title> + + <para> + To start the QEMU emulator from within Eclipse, follow + these steps: + <note> + See the + "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-qemu'>Using the Quick EMUlator (QEMU)</ulink>" + chapter in the Yocto Project Development Manual + for more information on using QEMU. + </note> + <orderedlist> + <listitem><para>Expose and select "External Tools + Configurations ..." from the "Run -> External + Tools" menu. + </para></listitem> + <listitem><para> + Locate and select your image in the navigation + panel to the left + (e.g. <filename>qemu_i586-poky-linux</filename>). + </para></listitem> + <listitem><para> + Click "Run" to launch QEMU. + <note> + The host on which you are running QEMU must + have the <filename>rpcbind</filename> utility + running to be able to make RPC calls on a + server on that machine. + If QEMU does not invoke and you receive error + messages involving + <filename>rpcbind</filename>, follow the + suggestions to get the service running. + As an example, on a new Ubuntu 16.04 LTS + installation, you must do the following in + order to get QEMU to launch: + <literallayout class='monospaced'> + $ sudo apt-get install rpcbind + </literallayout> + After installing <filename>rpcbind</filename>, + you need to edit the + <filename>/etc/init.d/rpcbind</filename> file + to include the following line: + <literallayout class='monospaced'> + OPTIONS="-i -w" + </literallayout> + After modifying the file, you need to start the + service: + <literallayout class='monospaced'> + $ sudo service portmap restart + </literallayout> + </note> + </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 needed for running in user-space NFS + mode. + </para></listitem> + <listitem><para> + Wait for QEMU to launch. + </para></listitem> + <listitem><para> + Once QEMU launches, you can begin operating + within that environment. + 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. + The IP address of the QEMU machine appears in the + xterm window. + You can use this address to help you see which + particular + IP address the instance of QEMU is using. + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='neon-deploying-and-debugging-the-application'> + <title>Deploying and Debugging the Application</title> + + <para> + Once the QEMU emulator is running the image, you can deploy + your application using the Eclipse IDE and then use + the emulator to perform debugging. + Follow these steps to deploy the application. + <note> + Currently, Eclipse does not support SSH port + forwarding. + Consequently, if you need to run or debug a remote + application using the host display, you must create a + tunneling connection from outside Eclipse and keep + that connection alive during your work. + For example, in a new terminal, run the following: + <literallayout class='monospaced'> + $ ssh -XY <replaceable>user_name</replaceable>@<replaceable>remote_host_ip</replaceable> + </literallayout> + Using the above form, here is an example: + <literallayout class='monospaced'> + $ ssh -XY root@192.168.7.2 + </literallayout> + After running the command, add the command to be + executed in Eclipse's run configuration before the + application as follows: + <literallayout class='monospaced'> + export DISPLAY=:10.0 + </literallayout> + Be sure to not destroy the connection during your QEMU + session (i.e. do not + exit out of or close that shell). + </note> + <orderedlist> + <listitem><para> + Select "Debug Configurations..." from the + "Run" menu. + </para></listitem> + <listitem><para> + In the left area, expand + <filename>C/C++Remote Application</filename>. + </para></listitem> + <listitem><para> + Locate your project and select it to bring + up a new tabbed view in the Debug Configurations + Dialog. + </para></listitem> + <listitem><para> + Click on the "Debugger" tab to see the + cross-tool debugger you are using. + Be sure to change to the debugger perspective in + Eclipse. + </para></listitem> + <listitem><para> + Click on the "Main" tab. + </para></listitem> + <listitem><para> + Create a new connection to the QEMU instance + by clicking on "new".</para></listitem> + <listitem><para>Select <filename>SSH</filename>, which + means Secure Socket Shell and then click "OK". + Optionally, you can select an TCF connection + instead. + </para></listitem> + <listitem><para> + Clear out the "Connection name" field and + enter any name you want for the connection. + </para></listitem> + <listitem><para> + Put the IP address for the connection in + the "Host" field. + For QEMU, the default is + <filename>192.168.7.2</filename>. + However, if a previous QEMU session did not exit + cleanly, the IP address increments (e.g. + <filename>192.168.7.3</filename>). + <note> + You can find the IP address for the current + QEMU session by looking in the xterm that + opens when you launch QEMU. + </note> + </para></listitem> + <listitem><para> + Enter <filename>root</filename>, which + is the default for QEMU, for the "User" field. + Be sure to leave the password field empty. + </para></listitem> + <listitem><para> + Click "Finish" to close the New Connections Dialog. + </para></listitem> + <listitem><para> + If necessary, use the drop-down menu now in the + "Connection" field and pick the IP Address you + entered. + </para></listitem> + <listitem><para> + Assuming you are connecting as the root + user, which is the default for QEMU x86-64 SDK + images provided by the Yocto Project, in the + "Remote Absolute File Path for C/C++ Application" + field, browse to + <filename>/home/root/</filename><replaceable>ProjectName</replaceable> + (e.g. <filename>/home/root/hello</filename>). + You could also browse to any other path you have + write access to on the target such as + <filename>/usr/bin</filename>. + This location is where your application will be + located on the QEMU system. + If you fail to browse to and specify an appropriate + location, QEMU will not understand what to remotely + launch. + Eclipse is helpful in that it auto fills your + application name for you assuming you browsed to a + directory. + <note> + If you are prompted to provide a username and + to optionally set a password, be sure you + provide "root" as the username and you leave + the password field blank. + </note> + </para></listitem> + <listitem><para> + Be sure you change to the "Debug" perspective in + Eclipse. + </para></listitem> + <listitem><para> + Click "Debug" + </para></listitem> + <listitem><para> + Accept the debug perspective. + </para></listitem> + </orderedlist> + </para> + </section> + + <section id='neon-using-Linuxtools'> + <title>Using Linuxtools</title> + + <para> + As mentioned earlier in the manual, performance tools exist + (Linuxtools) that enhance your development experience. + These tools are aids in developing and debugging + applications and images. + You can run these tools from within the Eclipse IDE through + the "Linuxtools" menu. + </para> + + <para> + For information on how to configure and use these tools, + see + <ulink url='http://www.eclipse.org/linuxtools/'>http://www.eclipse.org/linuxtools/</ulink>. + </para> + </section> + </section> + </section> +</chapter> +<!-- +vim: expandtab tw=80 ts=4 +--> diff --git a/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-intro.xml b/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-intro.xml index ee1dcbaba..a408024d8 100644 --- a/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-intro.xml +++ b/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-intro.xml @@ -111,6 +111,13 @@ </para></listitem> </itemizedlist> </para> + + <para> + For an overview of Toaster shipped with the Yocto Project &DISTRO; + Release, see the + "<ulink url='https://youtu.be/BlXdOYLgPxA'>Toaster - Yocto Project 2.2</ulink>" + video. + </para> </section> <section id='toaster-installation-options'> diff --git a/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-setup-and-use.xml b/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-setup-and-use.xml index 963b21122..966c35d4d 100644 --- a/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-setup-and-use.xml +++ b/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-setup-and-use.xml @@ -31,7 +31,7 @@ <filename>poky/build</filename>), start Toaster using this command: <literallayout class='monospaced'> - $ source ../bitbake/bin/toaster + $ source toaster start </literallayout> You can now run your builds from the command line, or with Toaster as explained in section @@ -56,7 +56,23 @@ set a different port. For example, the following command sets the port to "8400": <literallayout class='monospaced'> - $ source ../bitbake/bin/toaster webport=8400 + $ source toaster start webport=8400 + </literallayout> + </para> + </section> + + <section id='setting-a-different-address'> + <title>Setting a Different Address</title> + + <para> + By default, Toaster binds to the loop back address + (i.e. localhost). + You can use the <filename>WEBPORT</filename> parameter to + set a different host. + For example, the following command sets the host and port + to "0.0.0.0:8400": + <literallayout class='monospaced'> + $ source toaster start webport=0.0.0.0:8400 </literallayout> </para> </section> @@ -116,12 +132,14 @@ create a superuser by following these steps: <orderedlist> <listitem><para> - If you used <filename>virtualenv</filename>, which is + If you used <filename>pip3</filename>, which is recommended, to set up the Toaster system dependencies, - you need be sure the virtual environment is activated. - To activate this environment, use the following command: + you need be sure the local user path is in your + <filename>PATH</filename> list. + To append the pip3 local user path, use the following + command: <literallayout class='monospaced'> - $ source venv/bin/activate + $ export PATH=$PATH:$HOME/.local/bin </literallayout> </para></listitem> <listitem><para> @@ -211,16 +229,23 @@ Use the Mysql database server. </para></listitem> <listitem><para> - If you are using Ubuntu 14.04.3, run the following: + If you are using Ubuntu 16.04, run the following: <literallayout class='monospaced'> - $ sudo apt-get install apache2 libapache2-mod-wsgi mysql-server virtualenv libmysqlclient-dev + $ sudo apt-get install apache2 libapache2-mod-wsgi-py3 mysql-server python3-pip libmysqlclient-dev </literallayout> </para></listitem> <listitem><para> - If you are using Fedora 22 or a RedHat distribution, run + If you are using Fedora 24 or a RedHat distribution, run the following: <literallayout class='monospaced'> - $ sudo dnf install httpd mod_wsgi python-virtualenv gcc mysql-devel + $ sudo dnf install httpd python3-mod_wsgi python3-pip mariadb-server mariadb-devel python3-devel + </literallayout> + </para></listitem> + <listitem><para> + If you are using openSUSE Leap 42.1, run + the following: + <literallayout class='monospaced'> + $ sudo zypper install apache2 apache2-mod_wsgi-python3 python3-pip mariadb mariadb-client python3-devel </literallayout> </para></listitem> </itemizedlist> @@ -234,28 +259,31 @@ Perform the following steps to install Toaster: <orderedlist> <listitem><para> + Create toaster user and set its home directory to + <filename>/var/www/toaster</filename>: + <literallayout class='monospaced'> + $ sudo /usr/sbin/useradd toaster -md /var/www/toaster -s /bin/false + $ sudo su - toaster -s /bin/bash + </literallayout> + </para></listitem> + <listitem><para> Checkout a copy of <filename>poky</filename> into the web server directory. You will be using <filename>/var/www/toaster</filename>: <literallayout class='monospaced'> - $ mkdir -p /var/www/toaster - $ cd /var/www/toaster/ $ git clone git://git.yoctoproject.org/poky $ git checkout &DISTRO_NAME_NO_CAP; </literallayout> </para></listitem> <listitem><para> - Initialize a virtual environment and install Toaster - dependencies. - Using a virtual environment keeps the Python packages + Install Toaster + dependencies using the --user flag which + keeps the Python packages isolated from your system-provided packages: <literallayout class='monospaced'> $ cd /var/www/toaster/ - $ virtualenv venv - $ source ./venv/bin/activate - $ pip install -r ./poky/bitbake/toaster-requirements.txt - $ pip install mysql - $ pip install MySQL-python + $ pip3 install --user -r ./poky/bitbake/toaster-requirements.txt + $ pip3 install --user mysqlclient </literallayout> <note> Isolating these packages is not required but is @@ -270,7 +298,9 @@ as follows: <itemizedlist> <listitem><para> - Edit the <filename>DATABASE</filename> settings: + Edit the + <ulink url='http://docs.djangoproject.com/en/1.8/ref/settings/#std:setting-SECRET_KEY'>DATABASE</ulink> + settings: <literallayout class='monospaced'> DATABASES = { 'default': { @@ -285,13 +315,15 @@ </literallayout> </para></listitem> <listitem><para> - Edit the <filename>SECRET_KEY</filename>: + Edit the + <ulink url='http://docs.djangoproject.com/en/1.8/ref/settings/#std:setting-SECRET_KEY'>SECRET_KEY</ulink>: <literallayout class='monospaced'> SECRET_KEY = '<replaceable>your_secret_key</replaceable>' </literallayout> </para></listitem> <listitem><para> - Edit the <filename>STATIC_ROOT</filename>: + Edit the + <ulink url='http://docs.djangoproject.com/en/1.8/ref/settings/#std:setting-SECRET_KEY'>STATIC_ROOT</ulink>: <literallayout class='monospaced'> STATIC_ROOT = '/var/www/toaster/static_files/' </literallayout> @@ -314,9 +346,9 @@ default data, and gather the statically-served files: <literallayout class='monospaced'> $ cd /var/www/toaster/poky/ - $ ./bitbake/lib/toaster/manage.py syncdb $ ./bitbake/lib/toaster/manage.py migrate - $ TOASTER_DIR=`pwd` TOASTER_CONF=./meta-poky/conf/toasterconf.json ./bitbake/lib/toaster/manage.py checksettings + $ TOASTER_DIR=`pwd` TOASTER_CONF=./meta-poky/conf/toasterconf.json \ + ./bitbake/lib/toaster/manage.py checksettings $ ./bitbake/lib/toaster/manage.py collectstatic </literallayout> </para> @@ -324,8 +356,8 @@ <para> For the above set of commands, after moving to the <filename>poky</filename> directory, - the <filename>syncdb</filename> and <filename>migrate</filename> - commands ensure the database + the <filename>migrate</filename> + command ensures the database schema has had changes propagated correctly (i.e. migrations). </para> @@ -365,7 +397,8 @@ Finally, the <filename>collectstatic</filename> command is a Django framework command that collects all the statically served files into a designated directory to - be served up by the Apache web server. + be served up by the Apache web server as defined by + <filename>STATIC_ROOT</filename>. </para></listitem> <listitem><para> Add an Apache configuration file for Toaster to your Apache web @@ -378,21 +411,35 @@ <literallayout class='monospaced'> /etc/httpd/conf.d/toaster.conf </literallayout> + If you are using OpenSUSE, put it here: + <literallayout class='monospaced'> + /etc/apache2/conf.d/toaster.conf + </literallayout> Following is a sample Apache configuration for Toaster you can follow: <literallayout class='monospaced'> Alias /static /var/www/toaster/static_files <Directory /var/www/toaster/static_files> - Order allow,deny - Allow from all - Require all granted + <IfModule mod_access_compat.c> + Order allow,deny + Allow from all + </IfModule> + <IfModule !mod_access_compat.c> + Require all granted + </IfModule> + </Directory> + + <Directory /var/www/toaster/poky/bitbake/lib/toaster/toastermain> + <Files "wsgi.py"> + Require all granted + </Files> </Directory> - WSGIDaemonProcess toaster_wsgi python-path=/var/www/toaster/poky/bitbake/lib/toaster:/var/www/toaster/venv/lib/python2.7/site-packages + WSGIDaemonProcess toaster_wsgi python-path=/var/www/toaster/poky/bitbake/lib/toaster:/var/www/toaster/.local/lib/python3.4/site-packages WSGIScriptAlias / "/var/www/toaster/poky/bitbake/lib/toaster/toastermain/wsgi.py" <Location /> - WSGIProcessGroup toastern_wsgi + WSGIProcessGroup toaster_wsgi </Location> </literallayout> If you are using Ubuntu or Debian, @@ -404,7 +451,7 @@ </literallayout> Finally, restart Apache to make sure all new configuration is loaded. - For Ubuntu and Debian use: + For Ubuntu, Debian, and OpenSUSE use: <literallayout class='monospaced'> $ sudo service apache2 restart </literallayout> @@ -414,21 +461,52 @@ </literallayout> </para></listitem> <listitem><para> - Install the build runner service. - This service needs to be running in order to dispatch - builds. - Use this command: + Prepare the systemd service to run Toaster builds. + Here is a sample configuration file for the service: + <literallayout class='monospaced'> + [Unit] + Description=Toaster runbuilds + + [Service] + Type=forking + User=toaster + ExecStart=/usr/bin/screen -d -m -S runbuilds /var/www/toaster/poky/bitbake/lib/toaster/runbuilds-service.sh start + ExecStop=/usr/bin/screen -S runbuilds -X quit + WorkingDirectory=/var/www/toaster/poky + + [Install] + WantedBy=multi-user.target + </literallayout> + Prepare the <filename>runbuilds-service.sh</filename> + script that you need to place in the + <filename>/var/www/toaster/poky/bitbake/lib/toaster/</filename> + directory by setting up executable permissions: + <literallayout class='monospaced'> + #!/bin/bash + + #export http_proxy=http://proxy.host.com:8080 + #export https_proxy=http://proxy.host.com:8080 + #export GIT_PROXY_COMMAND=$HOME/bin/gitproxy + + cd ~/poky/ + source ./oe-init-build-env build + source ../bitbake/bin/toaster $1 noweb + [ "$1" == 'start' ] && /bin/bash + </literallayout> + </para></listitem> + <listitem><para> + Run the service: <literallayout class='monospaced'> - /var/www/toaster/poky/bitbake/lib/toaster/manage.py runbuilds + # service runbuilds start </literallayout> - Here is an example: + Since the service is running in a detached screen + session, you can attach to it using this command: <literallayout class='monospaced'> - #!/bin/sh - # toaster run builds dispatcher - cd /var/www/toaster/ - source ./venv/bin/activate - ./bitbake/lib/toaster/manage.py runbuilds + $ sudo su - toaster + $ screen -rS runbuilds </literallayout> + You can detach from the service again using "Ctrl-a" + followed by "d" key combination. </para></listitem> </orderedlist> You can now open up a browser and start using Toaster. diff --git a/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-start.xml b/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-start.xml index daefa7909..c5c6795f6 100644 --- a/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-start.xml +++ b/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual-start.xml @@ -22,6 +22,11 @@ and "<ulink url='&YOCTO_DOCS_QS_URL;#releases'>Yocto Project Release</ulink>" sections in the Yocto Project Quick Start. + For Ubuntu/Debian, you might also need to do an additional install + of pip3. + <literallayout class='monospaced'> + $ sudo apt-get install python3-pip + </literallayout> </para> </section> @@ -42,56 +47,6 @@ install-compatible format. </para> - <section id='toaster-virtual-environment'> - <title>Set Up a Python Virtual Environment</title> - - <para> - Set up 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 Python and the - modules provided by the operating system. - This separation avoids any version conflicts. - <note> - Creating a virtual environment is not absolutely - necessary. - However, doing so is highly recommended. - </note> - </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> - After setting 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> @@ -99,7 +54,21 @@ You need to install the packages that Toaster requires. Use this command: <literallayout class='monospaced'> - $ pip install -r bitbake/toaster-requirements.txt + $ $ pip3 install --user -r bitbake/toaster-requirements.txt + </literallayout> + The previous command installs the necessary Toaster modules + into a local python 3 cache in your + <filename>$HOME</filename> directory. + The caches is actually located in + <filename>$HOME/.local</filename>. + To see what packages have been installed into your + <filename>$HOME</filename> directory, do the following: + <literallayout class='monospaced'> + $ pip3 list installed --local + </literallayout> + If you need to remove something, the following works: + <literallayout class='monospaced'> + $ pip3 uninstall PackageNameToUninstall </literallayout> </para> </section> diff --git a/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual.xml b/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual.xml index 7a8912a6e..386c51b32 100644 --- a/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual.xml +++ b/import-layers/yocto-poky/documentation/toaster-manual/toaster-manual.xml @@ -46,6 +46,11 @@ <date>April 2016</date> <revremark>Released with the Yocto Project 2.1 Release.</revremark> </revision> + <revision> + <revnumber>2.2</revnumber> + <date>October 2016</date> + <revremark>Released with the Yocto Project 2.2 Release.</revremark> + </revision> </revhistory> <copyright> diff --git a/import-layers/yocto-poky/documentation/tools/mega-manual.sed b/import-layers/yocto-poky/documentation/tools/mega-manual.sed index 5a3bdf9fb..b6d265f44 100644 --- a/import-layers/yocto-poky/documentation/tools/mega-manual.sed +++ b/import-layers/yocto-poky/documentation/tools/mega-manual.sed @@ -2,32 +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\/2.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\/2.1\/yocto-project-qs\/yocto-project-qs.html#/\"link\" href=\"#/g -s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.1\/poky-ref-manual\/poky-ref-manual.html#/\"link\" href=\"#/g +# s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.2\/[a-z]*-[a-z]*-[a-z]*\/[a-z]*-[a-z]*-[a-z]*.html#/\"link\" href=\"#/g +s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.2\/yocto-project-qs\/yocto-project-qs.html#/\"link\" href=\"#/g +s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.2\/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\/2.1\/[a-z]*-[a-z]*\/[a-z]*-[a-z]*.html#/\"link\" href=\"#/g +# s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.2\/[a-z]*-[a-z]*\/[a-z]*-[a-z]*.html#/\"link\" href=\"#/g -s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.1\/sdk-manual\/sdk-manual.html#/\"link\" href=\"#/g -s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.1\/bsp-guide\/bsp-guide.html#/\"link\" href=\"#/g -s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.1\/dev-manual\/dev-manual.html#/\"link\" href=\"#/g -s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.1\/kernel-dev\/kernel-dev.html#/\"link\" href=\"#/g -s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.1\/profile-manual\/profile-manual.html#/\"link\" href=\"#/g -s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.1\/ref-manual\/ref-manual.html#/\"link\" href=\"#/g -s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.1\/toaster-manual\/toaster-manual.html#/\"link\" href=\"#/g -s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.1\/yocto-project-qs\/yocto-project-qs.html#/\"link\" href=\"#/g +s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.2\/sdk-manual\/sdk-manual.html#/\"link\" href=\"#/g +s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.2\/bsp-guide\/bsp-guide.html#/\"link\" href=\"#/g +s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.2\/dev-manual\/dev-manual.html#/\"link\" href=\"#/g +s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.2\/kernel-dev\/kernel-dev.html#/\"link\" href=\"#/g +s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.2\/profile-manual\/profile-manual.html#/\"link\" href=\"#/g +s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.2\/ref-manual\/ref-manual.html#/\"link\" href=\"#/g +s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.2\/toaster-manual\/toaster-manual.html#/\"link\" href=\"#/g +s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.2\/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\/2.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\/2.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\/2.1\/sdk-manual\/sdk-manual.html\" target=\"_top\">Yocto Project Software Development Kit (SDK) Developer's Guide<\/a>/Yocto Project Software Development Kit (SDK) Developer's Guide/g -s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.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\/2.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\/2.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\/2.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\/2.1\/toaster-manual\/toaster-manual.html\" target=\"_top\">Toaster User Manual<\/a>/Toaster User Manual/g +s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.2\/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\/2.2\/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\/2.2\/sdk-manual\/sdk-manual.html\" target=\"_top\">Yocto Project Software Development Kit (SDK) Developer's Guide<\/a>/Yocto Project Software Development Kit (SDK) Developer's Guide/g +s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.2\/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\/2.2\/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\/2.2\/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\/2.2\/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\/2.2\/toaster-manual\/toaster-manual.html\" target=\"_top\">Toaster User Manual<\/a>/Toaster User Manual/g diff --git a/import-layers/yocto-poky/documentation/yocto-project-qs/yocto-project-qs.xml b/import-layers/yocto-poky/documentation/yocto-project-qs/yocto-project-qs.xml index c09e971d6..d18f0aecd 100644 --- a/import-layers/yocto-poky/documentation/yocto-project-qs/yocto-project-qs.xml +++ b/import-layers/yocto-poky/documentation/yocto-project-qs/yocto-project-qs.xml @@ -255,8 +255,7 @@ tar 1.24 or greater </para></listitem> <listitem><para> - Python 2.7.3 or greater excluding Python - 3.x, which is not supported. + Python 3.4.0 or greater. </para></listitem> </itemizedlist> If your build host does not meet any of these three listed @@ -391,8 +390,8 @@ </para> <para> - You can try out the Yocto Project using the command-line interface - by finishing this quick start, which presents steps that let you + To use the Yocto Project through the command-line interface, + finish this quick start, which presents steps that let you do the following: <itemizedlist> <listitem><para> @@ -401,230 +400,239 @@ </para></listitem> <listitem><para> Easily change configurations so that you can quickly - create a second image, which would be for MinnowBoard + create a second image that you can load onto bootable + media and actually boot target hardware. + This example uses the MinnowBoard MAX-compatible boards. </para></listitem> </itemizedlist> <note> - The steps in this section do not provide detail, but rather - provide minimal, working commands and examples designed to - just get you started. + The steps in the following two sections do not provide detail, + but rather provide 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> - <para> - Use the following commands to build your image. - The OpenEmbedded build system creates an entire Linux - distribution, including the toolchain, from source. - <note><title>Note about Network Proxies</title> - <para> - By default, the build process searches for source code - using a pre-determined order through a set of - locations. - If you are working behind a firewall and your build - host is not set up for proxies, you could encounter - problems with the build process when fetching source - code (e.g. fetcher failures or Git failures). - </para> - - <para> - If you do not know your proxy settings, consult your - local network infrastructure resources and get that - information. - A good starting point could also be to check your web - browser settings. - Finally, you can find more information on using the - Yocto Project behind a firewall in the Yocto Project - Reference Manual - <ulink url='&YOCTO_DOCS_REF_URL;#how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>FAQ</ulink> - and on the - "<ulink url='https://wiki.yoctoproject.org/wiki/Working_Behind_a_Network_Proxy'>Working Behind a Network Proxy</ulink>" - wiki page. - </para> - </note> - </para> + <section id='building-an-image-for-emulation'> + <title>Building an Image for Emulation</title> - <para> - <orderedlist> - <listitem><para><emphasis>Be Sure Your Build Host is Set Up:</emphasis> - The steps to build an image in this section depend on - your build host being properly set up. - Be sure you have worked through the requirements - described in the - "<link linkend='yp-resources'>Setting Up to Use the Yocto Project</link>" - section. - </para></listitem> - <listitem><para><emphasis>Check Out Your Branch:</emphasis> - Be sure you are in the - <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> - (e.g. <filename>poky</filename>) and then check out - the branch associated with the latest Yocto Project - Release: - <literallayout class='monospaced'> + <para> + Use the following commands to build your image. + The OpenEmbedded build system creates an entire Linux + distribution, including the toolchain, from source. + <note><title>Note about Network Proxies</title> + <para> + By default, the build process searches for source code + using a pre-determined order through a set of + locations. + If you are working behind a firewall and your build + host is not set up for proxies, you could encounter + problems with the build process when fetching source + code (e.g. fetcher failures or Git failures). + </para> + + <para> + If you do not know your proxy settings, consult your + local network infrastructure resources and get that + information. + A good starting point could also be to check your web + browser settings. + Finally, you can find more information on using the + Yocto Project behind a firewall in the Yocto Project + Reference Manual + <ulink url='&YOCTO_DOCS_REF_URL;#how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>FAQ</ulink> + and on the + "<ulink url='https://wiki.yoctoproject.org/wiki/Working_Behind_a_Network_Proxy'>Working Behind a Network Proxy</ulink>" + wiki page. + </para> + </note> + </para> + + <para> + <orderedlist> + <listitem><para><emphasis>Be Sure Your Build Host is Set Up:</emphasis> + The steps to build an image in this section depend on + your build host being properly set up. + Be sure you have worked through the requirements + described in the + "<link linkend='yp-resources'>Setting Up to Use the Yocto Project</link>" + section. + </para></listitem> + <listitem><para><emphasis>Check Out Your Branch:</emphasis> + Be sure you are in the + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> + (e.g. <filename>poky</filename>) and then check out + the branch associated with the latest Yocto Project + Release: + <literallayout class='monospaced'> $ cd ~/poky $ git checkout -b &DISTRO_NAME_NO_CAP; origin/&DISTRO_NAME_NO_CAP; - </literallayout> - Git's <filename>checkout</filename> command checks out - the current Yocto Project release into a local branch - whose name matches the release (i.e. - <filename>&DISTRO_NAME_NO_CAP;</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. - </para></listitem> - <listitem><para><emphasis>Initialize the Build Environment:</emphasis> - Run the - <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> - environment setup script to define the OpenEmbedded - build environment on your build host. - <literallayout class='monospaced'> + </literallayout> + Git's <filename>checkout</filename> command checks out + the current Yocto Project release into a local branch + whose name matches the release (i.e. + <filename>&DISTRO_NAME_NO_CAP;</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. + </para></listitem> + <listitem><para><emphasis>Initialize the Build Environment:</emphasis> + Run the + <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> + environment setup script to define the OpenEmbedded + build environment on your build host. + <literallayout class='monospaced'> $ source &OE_INIT_FILE; - </literallayout> - Among other things, the script creates the - <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>, - which is <filename>build</filename> in this case - and is located in the - <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. - After the script runs, your current working directory - is set to the Build Directory. - Later, when the build completes, the Build Directory - contains all the files created during the build. - <note> - For information on running a memory-resident - <ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-components-bitbake'>BitBake</ulink>, - see the - <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink> - setup script. - </note> - </para></listitem> - <listitem><para><emphasis>Examine Your Local Configuration File:</emphasis> - When you set up the build environment, a local - configuration file named - <filename>local.conf</filename> becomes available in - a <filename>conf</filename> subdirectory of the - Build Directory. - Before using BitBake to start the build, you can - look at this file and be sure your general - configurations are how you want them: - <itemizedlist> - <listitem><para> - To help conserve disk space during builds, - you can add the following statement to your - project's configuration file, which for this - example is - <filename>poky/build/conf/local.conf</filename>. - Adding this statement deletes the work - directory used for building a recipe once the - recipe is built. - <literallayout class='monospaced'> + </literallayout> + Among other things, the script creates the + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>, + which is <filename>build</filename> in this case + and is located in the + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. + After the script runs, your current working directory + is set to the Build Directory. + Later, when the build completes, the Build Directory + contains all the files created during the build. + <note> + For information on running a memory-resident + <ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-components-bitbake'>BitBake</ulink>, + see the + <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink> + setup script. + </note> + </para></listitem> + <listitem><para><emphasis>Examine Your Local Configuration File:</emphasis> + When you set up the build environment, a local + configuration file named + <filename>local.conf</filename> becomes available in + a <filename>conf</filename> subdirectory of the + Build Directory. + Before using BitBake to start the build, you can + look at this file and be sure your general + configurations are how you want them: + <itemizedlist> + <listitem><para> + To help conserve disk space during builds, + you can add the following statement to your + project's configuration file, which for this + example is + <filename>poky/build/conf/local.conf</filename>. + Adding this statement deletes the work + directory used for building a recipe once the + recipe is built. + <literallayout class='monospaced'> INHERIT += "rm_work" - </literallayout> - </para></listitem> - <listitem><para> - By default, the target machine for the build is - <filename>qemux86</filename>, - which produces an image that can be used in - the QEMU emulator and is targeted at an - <trademark class='registered'>Intel</trademark> - 32-bit based architecture. - Further on in this example, this default is - easily changed through the - <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> - variable so that you can quickly - build an image for a different machine. - </para></listitem> - <listitem><para> - Another consideration before you build is the - package manager used when creating the image. - The default <filename>local.conf</filename> - file selects the RPM package manager. - You can control this configuration by using the - <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink></filename> - variable.</para> - <para>Selection of the package manager is separate - from whether package management is used at runtime - in the target image.</para> - <para>For additional package manager selection - information, see the - "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-package'><filename>package.bbclass</filename></ulink>" - section in the Yocto Project Reference Manual. - </para></listitem> - </itemizedlist> - </para></listitem> - <listitem><para><emphasis>Start the Build:</emphasis> - Continue with the following command to build an OS image - for the target, which is - <filename>core-image-sato</filename> in this example: - <note> - 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. - </note> - <literallayout class='monospaced'> + </literallayout> + </para></listitem> + <listitem><para> + By default, the target machine for the build is + <filename>qemux86</filename>, + which produces an image that can be used in + the QEMU emulator and is targeted at an + <trademark class='registered'>Intel</trademark> + 32-bit based architecture. + Further on in this example, this default is + easily changed through the + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> + variable so that you can quickly + build an image for a different machine. + </para></listitem> + <listitem><para> + Another consideration before you build is the + package manager used when creating the image. + The default <filename>local.conf</filename> + file selects the RPM package manager. + You can control this configuration by using the + <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink></filename> + variable.</para> + <para>Selection of the package manager is separate + from whether package management is used at runtime + in the target image.</para> + <para>For additional package manager selection + information, see the + "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-package'><filename>package.bbclass</filename></ulink>" + section in the Yocto Project Reference Manual. + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para><emphasis>Start the Build:</emphasis> + Continue with the following command to build an OS image + for the target, which is + <filename>core-image-sato</filename> in this example: + <note> + 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. + </note> + <literallayout class='monospaced'> $ bitbake core-image-sato - </literallayout> - For information on using the - <filename>bitbake</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. - </para></listitem> - <listitem><para><emphasis>Simulate Your Image Using QEMU:</emphasis> - Once this particular image is built, you can start QEMU - and run the image: - <literallayout class='monospaced'> + </literallayout> + For information on using the + <filename>bitbake</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. + </para></listitem> + <listitem><para><emphasis>Simulate Your Image Using QEMU:</emphasis> + Once this particular image is built, you can start QEMU + and run the image: + <literallayout class='monospaced'> $ runqemu qemux86 - </literallayout> - 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></listitem> - <listitem><para><emphasis>Exit QEMU:</emphasis> - Exit QEMU by either clicking on the shutdown icon or by - opening a terminal, typing - <filename>poweroff</filename>, and then pressing "Enter". - </para></listitem> - </orderedlist> - </para> + </literallayout> + 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></listitem> + <listitem><para><emphasis>Exit QEMU:</emphasis> + Exit QEMU by either clicking on the shutdown icon or by + opening a terminal, typing + <filename>poweroff</filename>, and then pressing "Enter". + </para></listitem> + </orderedlist> + </para> + </section> - <para id='qs-minnowboard-example'> - The following steps show how easy it is to set up to build an - image for a new machine. - These steps build an image for the MinnowBoard MAX, which is - supported by the Yocto Project and the - <filename>meta-intel</filename> <filename>intel-corei7-64</filename> - and <filename>intel-core2-32</filename> Board Support Packages - (BSPs). - <note> - The MinnowBoard MAX ships with 64-bit firmware. - If you want to use the board in 32-bit mode, you must - download the - <ulink url='http://firmware.intel.com/projects/minnowboard-max'>32-bit firmware</ulink>. - </note> - </para> + <section id='building-an-image-for-hardware'> + <title>Building an Image for Hardware</title> + + <para id='qs-minnowboard-example'> + The following steps show how easy it is to set up to build an + image for a new machine. + These steps build an image for the MinnowBoard MAX, which is + supported by the Yocto Project and the + <filename>meta-intel</filename> <filename>intel-corei7-64</filename> + and <filename>intel-core2-32</filename> Board Support Packages + (BSPs). + <note> + The MinnowBoard MAX ships with 64-bit firmware. + If you want to use the board in 32-bit mode, you must + download the + <ulink url='http://firmware.intel.com/projects/minnowboard-max'>32-bit firmware</ulink>. + </note> + </para> - <para> - <orderedlist> - <listitem><para><emphasis>Create a Local Copy of the - <filename>meta-intel</filename> Repository:</emphasis> - Building an image for the MinnowBoard MAX requires the - <filename>meta-intel</filename> layer. - Use the <filename>git clone</filename> command to create - a local copy of the repository inside your - <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>, - which is <filename>poky</filename> in this example: - <literallayout class='monospaced'> + <para> + <orderedlist> + <listitem><para><emphasis>Create a Local Copy of the + <filename>meta-intel</filename> Repository:</emphasis> + Building an image for the MinnowBoard MAX requires the + <filename>meta-intel</filename> layer. + Use the <filename>git clone</filename> command to create + a local copy of the repository inside your + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>, + which is <filename>poky</filename> in this example: + <literallayout class='monospaced'> $ cd $HOME/poky $ git clone git://git.yoctoproject.org/meta-intel Cloning into 'meta-intel'... @@ -634,121 +642,133 @@ remote: Total 11988 (delta 6881), reused 11752 (delta 6645) Resolving deltas: 100% (6881/6881), done. Checking connectivity... done. - </literallayout> - By default when you clone a Git repository, the - "master" branch is checked out. - Before you build your image that uses the - <filename>meta-intel</filename> layer, you must be - sure that both repositories - (<filename>meta-intel</filename> and - <filename>poky</filename>) are using the same releases. - Consequently, you need to checkout out the - "<filename>&DISTRO_NAME_NO_CAP;</filename>" release after - cloning <filename>meta-intel</filename>: - <literallayout class='monospaced'> + </literallayout> + By default when you clone a Git repository, the + "master" branch is checked out. + Before you build your image that uses the + <filename>meta-intel</filename> layer, you must be + sure that both repositories + (<filename>meta-intel</filename> and + <filename>poky</filename>) are using the same releases. + Consequently, you need to checkout out the + "<filename>&DISTRO_NAME_NO_CAP;</filename>" release after + cloning <filename>meta-intel</filename>: + <literallayout class='monospaced'> $ cd $HOME/poky/meta-intel $ git checkout &DISTRO_NAME_NO_CAP; Branch &DISTRO_NAME_NO_CAP; set up to track remote branch &DISTRO_NAME_NO_CAP; from origin. Switched to a new branch '&DISTRO_NAME_NO_CAP;' - </literallayout> - </para></listitem> - <listitem><para><emphasis>Configure the Build:</emphasis> - To configure the build, you edit the - <filename>bblayers.conf</filename> and - <filename>local.conf</filename> files, both of which are - located in the <filename>build/conf</filename> directory. - </para> - - <para>Here is a quick way to make the edits. - The first command uses the - <filename>bitbake-layers add-layer</filename> command - to add the <filename>meta-intel</filename> - layer, which contains the <filename>intel-core*</filename> - BSPs to the build. - The second command selects the BSP by setting the - <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> - variable. - <literallayout class='monospaced'> + </literallayout> + </para></listitem> + <listitem><para><emphasis>Configure the Build:</emphasis> + To configure the build, you edit the + <filename>bblayers.conf</filename> and + <filename>local.conf</filename> files, both of which are + located in the <filename>build/conf</filename> directory. + </para> + + <para>Here is a quick way to make the edits. + The first command uses the + <filename>bitbake-layers add-layer</filename> command + to add the <filename>meta-intel</filename> + layer, which contains the <filename>intel-core*</filename> + BSPs to the build. + The second command selects the BSP by setting the + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> + variable. + <literallayout class='monospaced'> $ cd $HOME/poky/build $ bitbake-layers add-layer "$HOME/poky/meta-intel" $ echo 'MACHINE = "intel-corei7-64"' >> conf/local.conf - </literallayout> - <note><title>Notes</title> - <para> - If you want a 64-bit build, use the following: - <literallayout class='monospaced'> - $ echo 'MACHINE = "intel-corei7-64"' >> conf/local.conf </literallayout> - </para> + <note><title>Notes</title> + <para> + If you want a 64-bit build, use the following: + <literallayout class='monospaced'> + $ echo 'MACHINE = "intel-corei7-64"' >> conf/local.conf + </literallayout> + </para> - <para> - If you want 32-bit images, use the following: - <literallayout class='monospaced'> + <para> + If you want 32-bit images, use the following: + <literallayout class='monospaced'> $ echo 'MACHINE = "intel-core2-32"' >> conf/local.conf + </literallayout> + </para> + </note> + </para></listitem> + <listitem><para><emphasis>Build an Image for MinnowBoard MAX:</emphasis> + The type of image you build depends on your goals. + For example, the previous build created a + <filename>core-image-sato</filename> image, which is an + image with Sato support. + It is possible to build many image types for the + MinnowBoard MAX. + Some possibilities are <filename>core-image-base</filename>, + which is a console-only image. + Another choice could be a + <filename>core-image-full-cmdline</filename>, which is + another console-only image but has more full-features + Linux system functionality installed. + For types of images you can build using the Yocto + Project, see the + "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" + chapter in the Yocto Project Reference Manual.</para> + <para>Because configuration changes are minimal to set up + for this second build, the OpenEmbedded build system can + re-use files from previous builds as much as possible. + Re-using files means this second build will be much faster + than an initial build. + For this example, the <filename>core-image-base</filename> + image is built: + <literallayout class='monospaced'> + $ bitbake core-image-base </literallayout> - </para> - </note> - </para></listitem> - <listitem><para><emphasis>Build a Minimal Image for MinnowBoard MAX:</emphasis> - Use the following command to build the minimal image for - MinnowBoard MAX. - Because configuration changes are minimal to set up for - this second build, the OpenEmbedded build system can - re-use files from previous builds as much as possible. - Re-using files means this second build will be much faster - than an initial build. - <literallayout class='monospaced'> - $ bitbake core-image-minimal - </literallayout> - Once the build completes, the resulting basic console image - is located in the Build Directory here: - <literallayout class='monospaced'> - tmp/deploy/images/intel-corei7-64/core-image-minimal-intel-corei7-64.hddimg - </literallayout> - </para></listitem> - <listitem><para><emphasis>Write the Image:</emphasis> - You can write the image to a USB key, SATA drive, or SD - card by using the <filename>mkefidisk.sh</filename> script, - which is included in the <filename>poky</filename> - repository at - <filename>scripts/contrib/mkefidisk.sh</filename>: - <literallayout class='monospaced'> - $ sudo $HOME/source/poky/scripts/contrib/mkefidisk.sh <replaceable>HOST_DEVICE</replaceable> \ - tmp/deploy/images/intel-corei7-64/core-image-minimal-intel-corei7-64.hddimg <replaceable>TARGET_DEVICE</replaceable> - </literallayout> - In the previous command, - <replaceable>HOST_DEVICE</replaceable> is the device node - on the build host (e.g. <filename>/dev/sdc</filename> or - <filename>/dev/mmcblk0</filename>). - <replaceable>TARGET_DEVICE</replaceable> is the name of the - device as the MinnowBoard MAX sees it (e.g. - <filename>/dev/sda</filename> or - <filename>/dev/mmcblk0</filename>). - </para></listitem> - <listitem><para><emphasis>Boot the Hardware:</emphasis> - With the boot device provisioned, you can insert the - media into the MinnowBoard MAX and boot the hardware. - The board should automatically detect the media and boot to - the bootloader and subsequently the operating system. - </para> - - <para>If the board does not boot automatically, you can - boot it manually from the EFI shell as follows: - <literallayout class='monospaced'> + Once the build completes, the resulting console-only image + is located in the Build Directory here: + <literallayout class='monospaced'> + tmp/deploy/images/intel-corei7-64/core-image-base-intel-corei7-64.hddimg + </literallayout> + </para></listitem> + <listitem><para><emphasis>Write the Image:</emphasis> + You can write the image just built to a bootable media + (e.g. a USB key, SATA drive, SD card, etc.) using the + <filename>dd</filename> utility: + <literallayout class='monospaced'> + $ sudo dd if=tmp/deploy/images/intel-corei7-64/core-image-minimal-intel-corei7-64.wic of=TARGET_DEVICE + </literallayout> + In the previous command, the + <filename>TARGET_DEVICE</filename> is the device node in + the host machine (e.g. <filename>/dev/sdc</filename>, which + is most likely a USB stick, or + <filename>/dev/mmcblk0</filename>, which is most likely an + SD card. + </para></listitem> + <listitem><para><emphasis>Boot the Hardware:</emphasis> + With the boot device provisioned, you can insert the + media into the MinnowBoard MAX and boot the hardware. + The board should automatically detect the media and boot to + the bootloader and subsequently the operating system. + </para> + + <para>If the board does not boot automatically, you can + boot it manually from the EFI shell as follows: + <literallayout class='monospaced'> Shell> connect -r Shell> map -r Shell> fs0: Shell> bootx64 - </literallayout> - <note> - For a 32-bit image use the following: - <literallayout class='monospaced'> - Shell> bootia32 </literallayout> - </note> - </para></listitem> - </orderedlist> - </para> + <note> + For a 32-bit image use the following: + <literallayout class='monospaced'> + Shell> bootia32 + </literallayout> + </note> + </para></listitem> + </orderedlist> + </para> + </section> </section> <section id='qs-next-steps'> |
