diff options
Diffstat (limited to 'yocto-poky/documentation')
89 files changed, 9325 insertions, 4704 deletions
diff --git a/yocto-poky/documentation/Makefile b/yocto-poky/documentation/Makefile index 99adea2fe..418d3ca8c 100644 --- a/yocto-poky/documentation/Makefile +++ b/yocto-poky/documentation/Makefile @@ -128,12 +128,14 @@ TARFILES = dev-style.css dev-manual.html \ figures/wip.png else TARFILES = dev-style.css dev-manual.html \ - figures/app-dev-flow.png figures/bsp-dev-flow.png \ + figures/bsp-dev-flow.png \ figures/dev-title.png figures/git-workflow.png \ figures/index-downloads.png figures/kernel-dev-flow.png \ figures/kernel-overview-1.png figures/kernel-overview-2-generic.png \ figures/source-repos.png figures/yp-download.png \ figures/recipe-workflow.png figures/build-workspace-directory.png \ + figures/devtool-add-flow.png figures/devtool-modify-flow.png \ + figures/devtool-upgrade-flow.png \ eclipse endif @@ -198,9 +200,9 @@ TARFILES = mega-manual.html mega-style.css figures/yocto-environment.png \ figures/using-a-pre-built-image.png \ figures/poky-title.png figures/buildhistory.png \ figures/buildhistory-web.png \ - figures/adt-title.png figures/bsp-title.png \ + figures/sdk-title.png figures/bsp-title.png \ figures/kernel-dev-title.png figures/kernel-architecture-overview.png \ - figures/app-dev-flow.png figures/bsp-dev-flow.png \ + figures/bsp-dev-flow.png \ figures/dev-title.png \ figures/git-workflow.png figures/index-downloads.png \ figures/kernel-dev-flow.png \ @@ -242,7 +244,12 @@ TARFILES = mega-manual.html mega-style.css figures/yocto-environment.png \ figures/sdk-generation.png figures/recipe-workflow.png \ figures/build-workspace-directory.png figures/mega-title.png \ figures/toaster-title.png figures/hosted-service.png \ - figures/simple-configuration.png + figures/simple-configuration.png figures/devtool-add-flow.png \ + figures/devtool-modify-flow.png figures/devtool-upgrade-flow.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 endif MANUALS = $(DOC)/$(DOC).html @@ -268,12 +275,13 @@ FIGURES = figures STYLESHEET = $(DOC)/*.css endif - -ifeq ($(DOC),adt-manual) +ifeq ($(DOC),sdk-manual) XSLTOPTS = --xinclude ALLPREQ = html eclipse tarball -TARFILES = adt-manual.html adt-style.css figures/adt-title.png \ - figures/using-a-pre-built-image.png \ +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 \ eclipse MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse FIGURES = figures @@ -332,7 +340,8 @@ XSLTOPTS = --xinclude ALLPREQ = html tarball TARFILES = toaster-manual.html toaster-manual-style.css \ figures/toaster-title.png figures/simple-configuration.png \ - figures/hosted-service.png + figures/hosted-service.png \ + figures/compatible-layers.png figures/import-layer.png figures/new-project.png MANUALS = $(DOC)/$(DOC).html FIGURES = figures STYLESHEET = $(DOC)/*.css @@ -394,11 +403,11 @@ eclipse: eclipse-generate eclipse-resolve-links .PHONY : eclipse-generate eclipse-resolve-links eclipse-generate: -ifeq ($(filter $(DOC), adt-manual bsp-guide dev-manual kernel-dev profile-manual ref-manual yocto-project-qs),) +ifeq ($(filter $(DOC), sdk-manual bsp-guide dev-manual kernel-dev profile-manual ref-manual yocto-project-qs),) @echo " " @echo "ERROR: You can only create eclipse documentation" @echo " of the following documentation parts:" - @echo " - adt-manual" + @echo " - sdk-manual" @echo " - bsp-guide" @echo " - dev-manual" @echo " - kernel-dev" diff --git a/yocto-poky/documentation/README b/yocto-poky/documentation/README index d01678d4f..a4e70a872 100644 --- a/yocto-poky/documentation/README +++ b/yocto-poky/documentation/README @@ -34,14 +34,16 @@ Manual Organization Folders exist for individual manuals as follows: -* adt-manual - The Yocto Project Application Developer's Guide. +* sdk-manual - The Yocto Project Software Development Kit (SDK) Developer's Guide. * bsp-guide - The Yocto Project Board Support Package (BSP) Developer's Guide * dev-manual - The Yocto Project Development Manual * kernel-dev - The Yocto Project Linux Kernel Development Manual * ref-manual - The Yocto Project Reference Manual * yocto-project-qs - The Yocto Project Quick Start -* mega-manual - An aggregated manual comprised of all YP manuals and guides +* mega-manual - The Yocto Project Mega-Manual, which is an aggregated manual comprised + of all YP manuals and guides * profile-manual - The Yocto Project Profile and Tracing Manual +* toaster-manual - The Toaster Manual Each folder is self-contained regarding content and figures. Note that there is a sed file needed to process the links of the mega-manual. The sed file @@ -68,10 +70,10 @@ inside the Makefile. See that file for more information. To build a manual, you run the make command and pass it the name of the folder containing the manual's contents. For example, the following command run from the documentation directory -creates an HTML and a PDF version of the ADT manual. +creates an HTML version of the SDK manual. The DOC variable specifies the manual you are making: - $ make DOC=adt-manual + $ make DOC=sdk-manual poky.ent ======== diff --git a/yocto-poky/documentation/adt-manual/adt-manual.xml b/yocto-poky/documentation/adt-manual/adt-manual.xml index 67b330a53..972f8bf08 100644 --- a/yocto-poky/documentation/adt-manual/adt-manual.xml +++ b/yocto-poky/documentation/adt-manual/adt-manual.xml @@ -91,6 +91,11 @@ <date>October 2015</date> <revremark>Released with the Yocto Project 2.0 Release.</revremark> </revision> + <revision> + <revnumber>2.1</revnumber> + <date>Sometime in 2016</date> + <revremark>Released with the future Yocto Project 2.1 Release.</revremark> + </revision> </revhistory> <copyright> diff --git a/yocto-poky/documentation/bsp-guide/bsp-guide.xml b/yocto-poky/documentation/bsp-guide/bsp-guide.xml index d9bcc3f03..c00b3458c 100644 --- a/yocto-poky/documentation/bsp-guide/bsp-guide.xml +++ b/yocto-poky/documentation/bsp-guide/bsp-guide.xml @@ -22,11 +22,11 @@ <authorgroup> <author> - <firstname>Tom</firstname> <surname>Zanussi</surname> + <firstname>Saul</firstname> <surname>Wold</surname> <affiliation> <orgname>Intel Corporation</orgname> </affiliation> - <email>tom.zanussi@intel.com</email> + <email>saul.wold@intel.com</email> </author> <author> <firstname>Richard</firstname> <surname>Purdie</surname> @@ -103,6 +103,11 @@ <date>October 2015</date> <revremark>Released with the Yocto Project 2.0 Release.</revremark> </revision> + <revision> + <revnumber>2.1</revnumber> + <date>April 2016</date> + <revremark>Released with the Yocto Project 2.1 Release.</revremark> + </revision> </revhistory> <copyright> diff --git a/yocto-poky/documentation/bsp-guide/bsp.xml b/yocto-poky/documentation/bsp-guide/bsp.xml index ec39ec9b3..b0562c7d4 100644 --- a/yocto-poky/documentation/bsp-guide/bsp.xml +++ b/yocto-poky/documentation/bsp-guide/bsp.xml @@ -60,16 +60,28 @@ <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'></ulink>. If you go to that interface, you will find near the bottom of the list under "Yocto Metadata Layers" several BSP layers all of which are - supported by the Yocto Project (e.g. <filename>meta-minnow</filename>, - <filename>meta-raspberrypi</filename>, and + supported by the Yocto Project (e.g. <filename>meta-raspberrypi</filename> and <filename>meta-intel</filename>). Each of these layers is a repository unto itself and clicking on a layer reveals information that includes two links from which you can choose to set up a clone of the layer's repository on your local host system. - Here is an example that clones the MinnowBoard BSP layer: + Here is an example that clones the Raspberry Pi BSP layer: <literallayout class='monospaced'> - $ git clone git://git.yoctoproject.org/meta-minnow + $ git clone git://git.yoctoproject.org/meta-raspberrypi </literallayout> + </para> + + <para> + In addition to BSP layers near the bottom of that referenced + Yocto Project Source Repository, the + <filename>meta-yocto-bsp</filename> layer is part of the + shipped <filename>poky</filename> repository. + The <filename>meta-yocto-bsp</filename> layer maintains several + BSPs such as the Beaglebone, EdgeRouter, and generic versions of + both 32 and 64-bit IA machines. + </para> + + <para> For information on the BSP development workflow, see the "<ulink url='&YOCTO_DOCS_DEV_URL;#developing-a-board-support-package-bsp'>Developing a Board Support Package (BSP)</ulink>" section in the Yocto Project Development Manual. @@ -80,8 +92,9 @@ </para> <para> - The layer's base directory (<filename>meta-<replaceable>bsp_name</replaceable></filename>) is the root - of the BSP Layer. + The layer's base directory + (<filename>meta-<replaceable>bsp_name</replaceable></filename>) + is the root of the BSP Layer. This root is what you add to the <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink> variable in the <filename>conf/bblayers.conf</filename> file found in the @@ -97,7 +110,7 @@ <literallayout class='monospaced'> BBLAYERS ?= " \ /usr/local/src/yocto/meta \ - /usr/local/src/yocto/meta-yocto \ + /usr/local/src/yocto/meta-poky \ /usr/local/src/yocto/meta-yocto-bsp \ /usr/local/src/yocto/meta-mylayer \ " @@ -121,6 +134,8 @@ An example of this type of layer is the <filename>meta-intel</filename> layer, which contains a number of individual BSP sub-layers, as well as a directory named <filename>common/</filename> full of common content across those layers. + Another example is the <filename>meta-yocto-bsp</filename> layer mentioned + earlier. </para> <para> @@ -130,7 +145,6 @@ </para> </section> - <section id="bsp-filelayout"> <title>Example Filesystem Layout</title> @@ -194,33 +208,142 @@ </para> <para> - Below is an example of the eMenlow BSP: + Below is an example of the Raspberry Pi BSP: <literallayout class='monospaced'> - meta-emenlow/COPYING.MIT - meta-emenlow/README - meta-emenlow/README.sources - meta-emenlow/binary/ - meta-emenlow/conf/ - meta-emenlow/conf/layer.conf - meta-emenlow/conf/machine/ - meta-emenlow/conf/machine/emenlow-noemgd.conf - meta-emenlow/recipes-bsp/ - meta-emenlow/recipes-bsp/formfactor/ - meta-emenlow/recipes-bsp/formfactor/formfactor/ - meta-emenlow/recipes-bsp/formfactor/formfactor_0.0.bbappend - meta-emenlow/recipes-bsp/formfactor/formfactor/emenlow-noemgd/ - meta-emenlow/recipes-bsp/formfactor/formfactor/emenlow-noemgd/machconfig - meta-emenlow/recipes-graphics/ - meta-emenlow/recipes-graphics/xorg-xserver - meta-emenlow/recipes-graphics/xorg-xserver/xserver-xf86-config - meta-emenlow/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend - meta-emenlow/recipes-graphics/xorg-xserver/xserver-xf86-config/emenlow-noemgd - meta-emenlow/recipes-graphics/xorg-xserver/xserver-xf86-config/emenlow-noemgd/xorg.config - meta-emenlow/recipes-kernel/ - meta-emenlow/recipes-kernel/linux/ - meta-emenlow/recipes-kernel/linux/linux-yocto-dev.bbappend - meta-emenlow/recipes-kernel/linux/linux-yocto_3.14.bbappend + meta-raspberrypi/COPYING.MIT + meta-raspberrypi/README + meta-raspberrypi/classes + meta-raspberrypi/classes/linux-raspberrypi-base.bbclass + meta-raspberrypi/classes/sdcard_image-rpi.bbclass + meta-raspberrypi/conf/ + meta-raspberrypi/conf/layer.conf + meta-raspberrypi/conf/machine/ + meta-raspberrypi/conf/machine/raspberrypi.conf + meta-raspberrypi/conf/machine/raspberrypi0.conf + meta-raspberrypi/conf/machine/raspberrypi2.conf + meta-raspberrypi/conf/machine/raspberrypi3.conf + meta-raspberrypi/conf/machine/include + meta-raspberrypi/conf/machine/include/rpi-base.inc + meta-raspberrypi/conf/machine/include/rpi-default-providers.inc + meta-raspberrypi/conf/machine/include/rpi-default-settings.inc + meta-raspberrypi/conf/machine/include/rpi-default-versions.inc + meta-raspberrypi/conf/machine/include/rpi-tune-arm1176jzf-s.inc + meta-raspberrypi/files + meta-raspberrypi/files/custom-licenses + meta-raspberrypi/files/custom-licenses/Broadcom + meta-raspberrypi/recipes-bsp + meta-raspberrypi/recipes-bsp/bootfiles + meta-raspberrypi/recipes-bsp/bootfiles/bcm2835-bootfiles.bb + meta-raspberrypi/recipes-bsp/bootfiles/rpi-config_git.bb + meta-raspberrypi/recipes-bsp/common + meta-raspberrypi/recipes-bsp/common/firmware.inc + meta-raspberrypi/recipes-bsp/formfactor_00.bbappend + meta-raspberrypi/recipes-bsp/formfactor/raspberrypi/machconfig + meta-raspberrypi/recipes-bsp/rpi-mkimage_git.bb + meta-raspberrypi/recipes-bsp/rpi-mkimage/License + meta-raspberrypi/recipes-bsp/rpi-mkimage/open-files-relative-to-script.patch + meta-raspberrypi/recipes-bsp/u-boot/u-boot-rpi_git.bb + meta-raspberrypi/recipes-core + meta-raspberrypi/recipes-core/images + meta-raspberrypi/recipes-core/images/rpi-basic-image.bb + meta-raspberrypi/recipes-core/images/rpi-hwup-image.bb + meta-raspberrypi/recipes-core/images/rpi-test-image.bb + meta-raspberrypi/recipes-core/packagegroups + meta-raspberrypi/recipes-core/packagegroups/packagegroup-rpi-test.bb + meta-raspberrypi/recipes-core/psplash + meta-raspberrypi/recipes-core/psplash/files + meta-raspberrypi/recipes-core/psplash/psplash_git.bbappend + meta-raspberrypi/recipes-core/psplash/files/psplash-raspberrypi-img.h + meta-raspberrypi/recipes-devtools + meta-raspberrypi/recipes-devtools/bcm2835 + meta-raspberrypi/recipes-devtools/bcm2835/bcm2835_1.46.bb + meta-raspberrypi/recipes-devtools/pi-blaster + meta-raspberrypi/recipes-devtools/pi-blaster/files + meta-raspberrypi/recipes-devtools/pi-blaster/*.patch + meta-raspberrypi/recipes-devtools/pi-blaster/pi-blaster.inc + meta-raspberrypi/recipes-devtools/pi-blaster/pi-blaster_git.bb + meta-raspberrypi/recipes-devtools/python + meta-raspberrypi/recipes-devtools/python/python-rtimu + meta-raspberrypi/recipes-devtools/python/python-rtimu/*.patch + meta-raspberrypi/recipes-devtools/python/python-rtimu_git.bb + meta-raspberrypi/recipes-devtools/python/python-sense-hat_2.1.0.bb + meta-raspberrypi/recipes-devtools/python/rpi-gpio + meta-raspberrypi/recipes-devtools/python/rpi-gpio/*.patch + meta-raspberrypi/recipes-devtools/python/rpi-gpio_0.6.1.bb + meta-raspberrypi/recipes-devtools/python/rpio + meta-raspberrypi/recipes-devtools/python/rpio/*.patch + meta-raspberrypi/recipes-devtools/python/rpio_0.10.0.bb + meta-raspberrypi/recipes-devtools/wiringPi + meta-raspberrypi/recipes-devtools/wiringPi/files + meta-raspberrypi/recipes-devtools/wiringPi/files/*.patch + meta-raspberrypi/recipes-devtools/wiringPi/wiringpi + meta-raspberrypi/recipes-devtools/wiringPi/wiringpi/*.patch + meta-raspberrypi/recipes-devtools/wiringPi/wiringpi_git.bb + meta-raspberrypi/recipes-graphics + meta-raspberrypi/recipes-graphics/eglinfo + meta-raspberrypi/recipes-graphics/eglinfo/eglinfo-fb_%.bbappend + meta-raspberrypi/recipes-graphics/eglinfo/eglinfo-x11_%.bbappend + meta-raspberrypi/recipes-graphics/userland + meta-raspberrypi/recipes-graphics/userland/userland + meta-raspberrypi/recipes-graphics/userland/userland/*.patch + meta-raspberrypi/recipes-graphics/userland/userland_git.bb + meta-raspberrypi/recipes-graphics/vc-graphics + meta-raspberrypi/recipes-graphics/vc-graphics/files + meta-raspberrypi/recipes-graphics/vc-graphics/files/egl.pc + meta-raspberrypi/recipes-graphics/vc-graphics/files/vchiq.sh + meta-raspberrypi/recipes-graphics/vc-graphics/vc-graphics-hardfp.bb + meta-raspberrypi/recipes-graphics/vc-graphics/vc-graphics.bb + meta-raspberrypi/recipes-graphics/vc-graphics/vc-graphics.inc + meta-raspberrypi/recipes-graphics/wayland + meta-raspberrypi/recipes-graphics/wayland/weston_%.bbappend + meta-raspberrypi/recipes-graphics/weston + meta-raspberrypi/recipes-graphics/weston/weston_%.bbappend + meta-raspberrypi/recipes-graphics/xorg-xserver + meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config + meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi + meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf + meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d + meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d/10-evdev.conf + meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d/99-pitft.conf + meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend + meta-raspberrypi/recipes-kernel + meta-raspberrypi/recipes-kernel/linux-firmware + meta-raspberrypi/recipes-kernel/linux-firmware/linux-firmware + meta-raspberrypi/recipes-kernel/linux-firmware/linux-firmware/LICENSE.broadcom_brcm80211 + meta-raspberrypi/recipes-kernel/linux-firmware/linux-firmware/brcmfmac43430-sdio.bin + meta-raspberrypi/recipes-kernel/linux-firmware/linux-firmware/brcmfmac43430-sdio.txt + meta-raspberrypi/recipes-kernel/linux-firmware/linux-firmware_git.bbappend + meta-raspberrypi/recipes-kernel/linux + meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi-3.14 + meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi-3.14/*.patch + meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi-3.18 + meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi-3.18/*.patch + meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi-4.1 + meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi-4.1/*.patch + meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi.inc + meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi + meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi/defconfig + meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi_3.14.bb + meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi_3.18.bb + meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi_4.1.bb + meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi_4.4.bb + meta-raspberrypi/recipes-kernel/linux/linux.inc + meta-raspberrypi/recipes-multimedia + meta-raspberrypi/recipes-multimedia/gstreamer + meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx + meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx/*.patch + meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx_%.bbappend + meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-plugins-bad_%.bbappend + meta-raspberrypi/recipes-multimedia/omxplayer + meta-raspberrypi/recipes-multimedia/omxplayer/omxplayer + meta-raspberrypi/recipes-multimedia/omxplayer/omxplayer/*.patch + meta-raspberrypi/recipes-multimedia/omxplayer/omxplayer_git.bb + meta-raspberrypi/scripts + meta-raspberrypi/scripts/lib + meta-raspberrypi/scripts/lib/image + meta-raspberrypi/scripts/lib/image/canned-wks + meta-raspberrypi/scripts/lib/image/canned-wks/sdimage-raspberrypi.wks </literallayout> </para> @@ -241,7 +364,7 @@ <para> These optional files satisfy licensing requirements for the BSP. The type or types of files here can vary depending on the licensing requirements. - For example, in the eMenlow BSP all licensing requirements are handled with the + For example, in the Raspberry Pi BSP all licensing requirements are handled with the <filename>COPYING.MIT</filename> file. </para> @@ -363,7 +486,7 @@ # We have a recipes directory, add to BBFILES BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ - ${LAYERDIR}/recipes-*/*/*.bbappend" + ${LAYERDIR}/recipes-*/*/*.bbappend" BBFILE_COLLECTIONS += "<replaceable>bsp</replaceable>" BBFILE_PATTERN_<replaceable>bsp</replaceable> = "^${LAYERDIR}/" @@ -375,20 +498,21 @@ <para> To illustrate the string substitutions, here are the corresponding statements - from the eEmenlow <filename>conf/layer.conf</filename> file: + from the Raspberry Pi <filename>conf/layer.conf</filename> file: <literallayout class='monospaced'> - # We have a conf and classes directory, add to BBPATH + # We have a conf and classes directory, append to BBPATH BBPATH .= ":${LAYERDIR}" - # We have recipes-* directories, add to BBFILES - BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ - ${LAYERDIR}/recipes-*/*/*.bbappend" + # We have a recipes directory containing .bb and .bbappend files, add to BBFILES + BBFILES += "${LAYERDIR}/recipes*/*/*.bb \ + ${LAYERDIR}/recipes*/*/*.bbappend" - BBFILE_COLLECTIONS += "emenlow" - BBFILE_PATTERN_emenlow := "^${LAYERDIR}/" - BBFILE_PRIORITY_emenlow = "6" + BBFILE_COLLECTIONS += "raspberrypi" + BBFILE_PATTERN_raspberrypi := "^${LAYERDIR}/" + BBFILE_PRIORITY_raspberrypi = "9" - LAYERDEPENDS_emenlow = "intel" + # Additional license directories. + LICENSE_PATH += "${LAYERDIR}/files/custom-licenses" </literallayout> </para> @@ -450,13 +574,11 @@ <para> To use an include file, you simply include them in the machine configuration file. - For example, the eEmenlow BSP - <filename>emenlow-noemgd.conf</filename> contains the - following statements: + For example, the Raspberry Pi BSP + <filename>raspberrypi3.conf</filename> contains the + following statement: <literallayout class='monospaced'> - require conf/machine/include/intel-core2-32-common.inc - require conf/machine/include/intel-common-pkgarch.inc - require conf/machine/include/meta-intel.inc + include conf/machine/raspberrypi2.conf </literallayout> </para> </section> @@ -474,20 +596,22 @@ This optional directory contains miscellaneous recipe files for the BSP. Most notably would be the formfactor files. - For example, in the eMenlow BSP there is the + For example, in the Raspberry Pi BSP there is the <filename>formfactor_0.0.bbappend</filename> file, which is an append file used to augment the recipe that starts the build. Furthermore, there are machine-specific settings used during the build that are defined by the <filename>machconfig</filename> file further down in the directory. - In the eMenlow example, the <filename>machconfig</filename> - file supports the Video Electronics Standards Association - (VESA) graphics driver: + Here is the <filename>machconfig</filename> + file for the Raspberry Pi BSP: <literallayout class='monospaced'> - # Assume a USB mouse and keyboard are connected HAVE_TOUCHSCREEN=0 HAVE_KEYBOARD=1 + + DISPLAY_CAN_ROTATE=0 + DISPLAY_ORIENTATION=0 + DISPLAY_DPI=133 </literallayout> </para> @@ -515,18 +639,6 @@ special requirements for graphics support. All files that are needed for the BSP to support a display are kept here. - For example, the <filename>meta-emenlow</filename> layer, - which supports the eMenlow platform consisting of the - <trademark class='registered'>Intel</trademark> - <trademark class='trade'>Atom</trademark> - Z5xx processor with the - <trademark class='registered'>Intel</trademark> - System Controller Hub US15W, uses these files for supporting - the Video Electronics Standards Association (VESA) graphics: - <literallayout class='monospaced'> - meta-emenlow/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend - meta-emenlow/recipes-graphics/xorg-xserver/xserver-xf86-config/emenlow-noemgd/xorg.conf - </literallayout> </para> </section> @@ -551,47 +663,63 @@ the <filename>meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux</filename> directory). </para> <para> - Suppose you are using the <filename>linux-yocto_3.14.bb</filename> recipe to build + Suppose you are using the <filename>linux-yocto_4.4.bb</filename> recipe to build the kernel. In other words, you have selected the kernel in your <replaceable>bsp_name</replaceable><filename>.conf</filename> file by adding these types of statements: <literallayout class='monospaced'> PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" - PREFERRED_VERSION_linux-yocto ?= "3.14%" + PREFERRED_VERSION_linux-yocto ?= "4.4%" </literallayout> <note> When the preferred provider is assumed by default, the <filename>PREFERRED_PROVIDER</filename> statement does not appear in the <replaceable>bsp_name</replaceable><filename>.conf</filename> file. </note> - You would use the <filename>linux-yocto_3.14.bbappend</filename> file to append - specific BSP settings to the kernel, thus configuring the kernel for your particular BSP. + You would use the <filename>linux-yocto_4.4.bbappend</filename> + file to append specific BSP settings to the kernel, thus + configuring the kernel for your particular BSP. </para> + <para> - As an example, look at the existing eMenlow BSP. - The append file used is: + As an example, consider the following append file + used by the BSPs in <filename>meta-yocto-bsp</filename>: <literallayout class='monospaced'> - meta-emenlow/recipes-kernel/linux/linux-yocto_3.14.bbappend + meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.4.bbappend </literallayout> The following listing shows the file. - Be aware that the actual commit ID strings in this example listing might be different - than the actual strings in the file from the <filename>meta-intel</filename> - Git source repository. + Be aware that the actual commit ID strings in this + example listing might be different than the actual strings + in the file from the <filename>meta-yocto-bsp</filename> + layer upstream. <literallayout class='monospaced'> - FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" - - COMPATIBLE_MACHINE_emenlow-noemgd = "emenlow-noemgd" - KMACHINE_emenlow-noemgd = "emenlow" - KBRANCH_emenlow-noemgd = "standard/base" - KERNEL_FEATURES_append_emenlow-noemgd = " features/drm-gma500/drm-gma500.scc" - - LINUX_VERSION_emenlow-noemgd = "3.14.19" - SRCREV_machine_emenlow-noemgd = "902f34d36102a4b2008b776ecae686f80d307e12" - SRCREV_meta_emenlow-noemgd = "28e39741b8b3018334021d981369d3fd61f18f5b" + KBRANCH_genericx86 = "standard/base" + KBRANCH_genericx86-64 = "standard/base" + + KMACHINE_genericx86 ?= "common-pc" + KMACHINE_genericx86-64 ?= "common-pc-64" + KBRANCH_edgerouter = "standard/edgerouter" + KBRANCH_beaglebone = "standard/beaglebone" + KBRANCH_mpc8315e-rdb = "standard/fsl-mpc8315e-rdb" + + SRCREV_machine_genericx86 ?= "ff4c4ef15b51f45b9106d71bf1f62fe7c02e63c2" + SRCREV_machine_genericx86-64 ?= "ff4c4ef15b51f45b9106d71bf1f62fe7c02e63c2" + SRCREV_machine_edgerouter ?= "ff4c4ef15b51f45b9106d71bf1f62fe7c02e63c2" + SRCREV_machine_beaglebone ?= "ff4c4ef15b51f45b9106d71bf1f62fe7c02e63c2" + SRCREV_machine_mpc8315e-rdb ?= "df00877ef9387b38b9601c82db57de2a1b23ce53" + + COMPATIBLE_MACHINE_genericx86 = "genericx86" + COMPATIBLE_MACHINE_genericx86-64 = "genericx86-64" + COMPATIBLE_MACHINE_edgerouter = "edgerouter" + COMPATIBLE_MACHINE_beaglebone = "beaglebone" + COMPATIBLE_MACHINE_mpc8315e-rdb = "mpc8315e-rdb" + + LINUX_VERSION_genericx86 = "4.4.3" + LINUX_VERSION_genericx86-64 = "4.4.3" </literallayout> - This append file contains statements used to support the - eMenlow BSP. + This append file contains statements used to support + several BSPs that ship with the Yocto Project. The file defines machines using the <ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink> variable and uses the @@ -602,25 +730,31 @@ The file also uses the optional <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink> variable to ensure the build process uses the - <filename>standard/emenlow</filename> kernel branch. - The + appropriate kernel branch. + </para> + + <para> + Although this particular example does not use it, the <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink> - variable enables features specific to the kernel - (e.g. Intel GMA-500 DRM Driver in this case). + variable could be used to enable features specific to + the kernel. The append file points to specific commits in the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> Git repository and the <filename>meta</filename> Git repository branches to identify the exact kernel needed to build the - eMenlow BSP. + BSP. </para> <para> - One thing missing in this particular BSP, which you will typically need when - developing a BSP, is the kernel configuration file (<filename>.config</filename>) for your BSP. - When developing a BSP, you probably have a kernel configuration file or a set of kernel - configuration files that, when taken together, define the kernel configuration for your BSP. - You can accomplish this definition by putting the configurations in a file or a set of files - inside a directory located at the same level as your kernel's append file and having the same + One thing missing in this particular BSP, which you will + typically need when developing a BSP, is the kernel configuration + file (<filename>.config</filename>) for your BSP. + When developing a BSP, you probably have a kernel configuration + file or a set of kernel configuration files that, when taken + together, define the kernel configuration for your BSP. + You can accomplish this definition by putting the configurations + in a file or a set of files inside a directory located at the + same level as your kernel's append file and having the same name as the kernel's main recipe file. With all these conditions met, simply reference those files in the <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> @@ -628,37 +762,42 @@ </para> <para> - For example, suppose you had some configuration options in a file called - <filename>network_configs.cfg</filename>. - You can place that file inside a directory named <filename>linux-yocto</filename> and then add - a <filename>SRC_URI</filename> statement such as the following to the append file. - When the OpenEmbedded build system builds the kernel, the configuration options are - picked up and applied. + For example, suppose you had some configuration options + in a file called <filename>network_configs.cfg</filename>. + You can place that file inside a directory named + <filename>linux-yocto</filename> and then add + a <filename>SRC_URI</filename> statement such as the + following to the append file. + When the OpenEmbedded build system builds the kernel, the + configuration options are picked up and applied. <literallayout class='monospaced'> SRC_URI += "file://network_configs.cfg" </literallayout> </para> <para> - To group related configurations into multiple files, you perform a similar procedure. - Here is an example that groups separate configurations specifically for Ethernet and graphics - into their own files and adds the configurations - by using a <filename>SRC_URI</filename> statement like the following in your append file: + To group related configurations into multiple files, you + perform a similar procedure. + Here is an example that groups separate configurations + specifically for Ethernet and graphics into their own + files and adds the configurations by using a + <filename>SRC_URI</filename> statement like the following + in your append file: <literallayout class='monospaced'> SRC_URI += "file://myconfig.cfg \ - file://eth.cfg \ - file://gfx.cfg" + file://eth.cfg \ + file://gfx.cfg" </literallayout> </para> <para> - The <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> - variable is in boilerplate form in the - previous example in order to make it easy to do that. - This variable must be in your layer or BitBake will not find the patches or - configurations even if you have them in your <filename>SRC_URI</filename>. - The <filename>FILESEXTRAPATHS</filename> variable enables the build process to - find those configuration files. + Another variable you can use in your kernel recipe append + file is the + <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> + variable. + When you use this statement, you are extending the locations + used by the OpenEmbedded system to look for files and + patches as the recipe is processed. </para> <note> @@ -711,7 +850,7 @@ "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers"</ulink> in the Yocto Project Development Manual.</para></listitem> <listitem><para>The requirements in this section apply regardless of how you - ultimately package a BSP. + package a BSP. You should consult the packaging and distribution guidelines for your specific release process. For an example of packaging and distribution requirements, see the @@ -731,7 +870,7 @@ </para> <para> - Following are the requirements for a released BSP that conforms to the + Following are the requirements for a released BSP that conform to the Yocto Project: <itemizedlist> <listitem><para><emphasis>Layer Name:</emphasis> @@ -777,15 +916,16 @@ You must specify which license to use since there is no default license if one is not specified. See the - <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-intel/tree/meta-fri2/COPYING.MIT'><filename>COPYING.MIT</filename></ulink> - file for the Fish River Island 2 BSP in the <filename>meta-fri2</filename> BSP layer - as an example.</para></listitem> + <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-raspberrypi/tree/COPYING.MIT'><filename>COPYING.MIT</filename></ulink> + file for the Raspberry Pi BSP in the + <filename>meta-raspberrypi</filename> BSP layer as an example. + </para></listitem> <listitem><para><emphasis>README File:</emphasis> You must include a <filename>README</filename> file in the <filename>meta-<replaceable>bsp_name</replaceable></filename> directory. See the - <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-intel/tree/meta-fri2/README'><filename>README</filename></ulink> - file for the Fish River Island 2 BSP in the <filename>meta-fri2</filename> BSP layer + <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-raspberrypi/tree/README'><filename>README</filename></ulink> + file for the Raspberry Pi BSP in the <filename>meta-raspberrypi</filename> BSP layer as an example.</para> <para>At a minimum, the <filename>README</filename> file should contain the following: @@ -828,10 +968,7 @@ This file specifies exactly where you can find the sources used to generate the binary images contained in the <filename>binary</filename> directory, if present. - See the - <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-intel/tree/meta-fri2/README.sources'><filename>README.sources</filename></ulink> - file for the Fish River Island 2 BSP in the <filename>meta-fri2</filename> BSP layer - as an example.</para></listitem> + </para></listitem> <listitem><para><emphasis>Layer Configuration File:</emphasis> You must include a <filename>conf/layer.conf</filename> in the <filename>meta-<replaceable>bsp_name</replaceable></filename> directory. @@ -1175,13 +1312,14 @@ for that sub-command: <literallayout class='monospaced'> $ yocto-bsp create + ERROR:root:Wrong number of arguments, exiting Usage: Create a new Yocto BSP usage: yocto-bsp create <bsp-name> <karch> [-o <DIRNAME> | --outdir <DIRNAME>] - [-i <JSON PROPERTY FILE> | --infile <JSON PROPERTY_FILE>] + [-i <JSON PROPERTY FILE> | --infile <JSON PROPERTY_FILE>] This command creates a Yocto BSP based on the specified parameters. The new BSP will be a new Yocto BSP layer contained by default within @@ -1189,6 +1327,12 @@ can be used to place the BSP layer in a directory with a different name and location. + The value of the 'karch' parameter determines the set of files that + will be generated for the BSP, along with the specific set of + 'properties' that will be used to fill out the BSP-specific portions + of the BSP. The possible values for the 'karch' parameter can be + listed via 'yocto-bsp list karch'. + ... </literallayout> </para> @@ -1203,7 +1347,7 @@ yocto-bsp create - Create a new Yocto BSP SYNOPSIS - yocto-bsp create <bsp-name> <karch> [-o <DIRNAME> | --outdir <DIRNAME>] + yocto-bsp create <bsp-name> <karch> [-o <DIRNAME> | --outdir <DIRNAME>] [-i <JSON PROPERTY FILE> | --infile <JSON PROPERTY_FILE>] DESCRIPTION @@ -1213,12 +1357,6 @@ 'meta-bsp-name'. The -o option can be used to place the BSP layer in a directory with a different name and location. - The value of the 'karch' parameter determines the set of files - that will be generated for the BSP, along with the specific set of - 'properties' that will be used to fill out the BSP-specific - portions of the BSP. The possible values for the 'karch' parameter - can be listed via 'yocto-bsp list karch'. - ... </literallayout> </para> @@ -1280,13 +1418,13 @@ <literallayout class='monospaced'> $ yocto-bsp list karch Architectures available: - qemu - mips64 powerpc x86_64 + i386 arm + qemu mips - i386 + mips64 </literallayout> </para> @@ -1320,35 +1458,34 @@ $ yocto-bsp create myarm qemu Checking basic git connectivity... Done. + Which qemu architecture would you like to use? [default: i386] - 1) i386 (32-bit) - 2) x86_64 (64-bit) - 3) ARM (32-bit) - 4) PowerPC (32-bit) - 5) MIPS (32-bit) - 6) MIPS64 (64-bit) + 1) i386 (32-bit) + 2) x86_64 (64-bit) + 3) ARM (32-bit) + 4) PowerPC (32-bit) + 5) MIPS (32-bit) + 6) MIPS64 (64-bit) 3 - Would you like to use the default (3.19) kernel? (y/n) [default: y] y + Would you like to use the default (4.1) 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-3.19.git... + 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] - 1) standard/arm-versatile-926ejs - 2) standard/base - 3) standard/beagleboard - 4) standard/beaglebone - 5) standard/ck - 6) standard/common-pc - 7) standard/crownbay - 8) standard/edgerouter - 9) standard/fsl-mpc8315e-rdb - 10) standard/mti-malta32 - 11) standard/mti-malta64 - 12) standard/qemuarm64 - 13) standard/qemuppc + 1) 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 1 Would you like SMP support? (y/n) [default: y] Does your BSP have a touchscreen? (y/n) [default: n] Does your BSP have a keyboard? (y/n) [default: y] + New qemu BSP created in meta-myarm </literallayout> Take a closer look at the example now: @@ -1358,7 +1495,7 @@ In the example, we use the ARM architecture. </para></listitem> <listitem><para>The script then prompts you for the kernel. - The default 3.19 kernel is acceptable. + The default 4.4 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> @@ -1399,15 +1536,10 @@ <literallayout class='monospaced'> BBLAYERS = ? " \ /usr/local/src/yocto/meta \ - /usr/local/src/yocto/meta-yocto \ + /usr/local/src/yocto/meta-poky \ /usr/local/src/yocto/meta-yocto-bsp \ /usr/local/src/yocto/meta-myarm \ " - - BBLAYERS_NON_REMOVABLE ?= " \ - /usr/local/src/yocto/meta \ - /usr/local/src/yocto/meta-yocto \ - " </literallayout> Adding the layer to this file allows the build system to build the BSP and the <filename>yocto-kernel</filename> tool to be able to find the layer and @@ -1438,8 +1570,11 @@ <literallayout class='monospaced'> $ yocto-kernel --help Usage: + Modify and list Yocto BSP kernel config items and patches. + usage: yocto-kernel [--version] [--help] COMMAND [ARGS] + Current 'yocto-kernel' commands are: config list List the modifiable set of bare kernel config options for a BSP config add Add or modify bare kernel config options for a BSP @@ -1454,7 +1589,11 @@ feature describe Describe a particular feature feature create Create a new BSP-local feature feature destroy Remove a BSP-local feature + See 'yocto-kernel help COMMAND' for more information on a specific command. + + + Options: --version show program's version number and exit -h, --help show this help message and exit diff --git a/yocto-poky/documentation/dev-manual/dev-manual-common-tasks.xml b/yocto-poky/documentation/dev-manual/dev-manual-common-tasks.xml index f0836e8b1..f926f1d47 100644 --- a/yocto-poky/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/yocto-poky/documentation/dev-manual/dev-manual-common-tasks.xml @@ -72,7 +72,7 @@ <filename>meta</filename>, <filename>meta-skeleton</filename>, <filename>meta-selftest</filename>, - <filename>meta-yocto</filename>, and + <filename>meta-poky</filename>, and <filename>meta-yocto-bsp</filename>. Each of these folders represents a distinct layer. </para> @@ -165,12 +165,12 @@ directory to the <filename>BBPATH</filename>. On the other hand, distro layers, such as - <filename>meta-yocto</filename>, can choose + <filename>meta-poky</filename>, can choose to enforce their own precedence over <filename>BBPATH</filename>. For an example of that syntax, see the <filename>layer.conf</filename> file for - the <filename>meta-yocto</filename> layer. + the <filename>meta-poky</filename> layer. </note></para></listitem> <listitem><para>The recipes for the layers are appended to @@ -336,11 +336,12 @@ DEPENDS_append_one = " foo" DEPENDS_prepend_one = "foo " </literallayout> - As an actual example, here's a line from the recipe for - the OProfile profiler, which lists an extra build-time - dependency when building specifically for 64-bit PowerPC: + As an actual example, here's a line from the recipe + for gnutls, which adds dependencies on + "argp-standalone" when building with the musl C + library: <literallayout class='monospaced'> - DEPENDS_append_powerpc64 = " libpfm4" + DEPENDS_append_libc-musl = " argp-standalone" </literallayout> <note> Avoiding "+=" and "=+" and using @@ -444,7 +445,7 @@ BBLAYERS ?= " \ $HOME/poky/meta \ - $HOME/poky/meta-yocto \ + $HOME/poky/meta-poky \ $HOME/poky/meta-yocto-bsp \ $HOME/poky/meta-mylayer \ " @@ -550,8 +551,8 @@ <para> Following is the append file, which is named <filename>formfactor_0.0.bbappend</filename> and is from the - Emenlow BSP Layer named - <filename>meta-intel/meta-emenlow</filename>. + Raspberry Pi BSP Layer named + <filename>meta-raspberrypi</filename>. The file is in <filename>recipes-bsp/formfactor</filename>: <literallayout class='monospaced'> FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" @@ -577,7 +578,7 @@ which resolves to a directory named <filename>formfactor</filename> in the same directory in which the append file resides (i.e. - <filename>meta-intel/meta-emenlow/recipes-bsp/formfactor/formfactor</filename>. + <filename>meta-raspberrypi/recipes-bsp/formfactor/formfactor</filename>. This implies that you must have the supporting directory structure set up that will contain any files or patches you will be including from the layer. @@ -870,7 +871,7 @@ <literallayout class='monospaced'> BBLAYERS = ?" \ /usr/local/src/yocto/meta \ - /usr/local/src/yocto/meta-yocto \ + /usr/local/src/yocto/meta-poky \ /usr/local/src/yocto/meta-yocto-bsp \ /usr/local/src/yocto/meta-mylayer \ " @@ -3495,14 +3496,7 @@ </para> <para> - This section overviews the Multilib process only. - For more details on how to implement Multilib, see the - <ulink url='&YOCTO_WIKI_URL;/wiki/Multilib'>Multilib</ulink> wiki - page. - </para> - - <para> - Aside from this wiki page, several examples exist in the + Several examples exist in the <filename>meta-skeleton</filename> layer found in the <link linkend='source-directory'>Source Directory</link>: <itemizedlist> @@ -3603,8 +3597,39 @@ <title>Additional Implementation Details</title> <para> - Different packaging systems have different levels of native Multilib - support. + Generic implementation details as well as details that are + specific to package management systems exist. + Following are implementation details that exist regardless + of the package management system: + <itemizedlist> + <listitem><para>The typical convention used for the + class extension code as used by + Multilib assumes that all package names specified + in + <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink> + that contain <filename>${PN}</filename> have + <filename>${PN}</filename> at the start of the name. + When that convention is not followed and + <filename>${PN}</filename> appears at + the middle or the end of a name, problems occur. + </para></listitem> + <listitem><para>The + <ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_VENDOR'><filename>TARGET_VENDOR</filename></ulink> + value under Multilib will be extended to + "-<replaceable>vendor</replaceable>ml<replaceable>multilib</replaceable>" + (e.g. "-pokymllib32" for a "lib32" Multilib with + Poky). + The reason for this slightly unwieldy contraction + is that any "-" characters in the vendor + string presently break Autoconf's + <filename>config.sub</filename>, and + other separators are problematic for different + reasons. + </para></listitem> + </itemizedlist> + </para> +' + <para> For the RPM Package Management System, the following implementation details exist: <itemizedlist> @@ -3701,6 +3726,46 @@ </section> </section> + <section id='dev-optionally-using-an-external-toolchain'> + <title>Optionally Using an External Toolchain</title> + + <para> + You might want to use an external toolchain as part of your + development. + If this is the case, the fundamental steps you need to accomplish + are as follows: + <itemizedlist> + <listitem><para> + Understand where the installed toolchain resides. + For cases where you need to build the external toolchain, + you would need to take separate steps to build and install + the toolchain. + </para></listitem> + <listitem><para> + Make sure you add the layer that contains the toolchain to + your <filename>bblayers.conf</filename> file through the + <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink> + variable. + </para></listitem> + <listitem><para> + Set the + <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNAL_TOOLCHAIN'><filename>EXTERNAL_TOOLCHAIN</filename></ulink> + variable in your <filename>local.conf</filename> file + to the location in which you installed the toolchain. + </para></listitem> + </itemizedlist> + A good example of an external toolchain used with the Yocto Project + is <trademark class='registered'>Mentor Graphics</trademark> + Sourcery G++ Toolchain. + You can see information on how to use that particular layer in the + <filename>README</filename> file at + <ulink url='http://github.com/MentorEmbedded/meta-sourcery/'></ulink>. + You can find further information by reading about the + <ulink url='&YOCTO_DOCS_REF_URL;#var-TCMODE'><filename>TCMODE</filename></ulink> + variable in the Yocto Project Reference Manual's variable glossary. + </para> + </section> + <section id='creating-partitioned-images'> <title>Creating Partitioned Images</title> @@ -3779,8 +3844,8 @@ standalone utility that initially provides easier-to-use and more flexible replacements for a couple bits of existing functionality in OE Core's - <filename>boot-directdisk.bbclass</filename> and - <filename>mkefidisk.sh</filename> scripts. + <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-image-live'><filename>image-live</filename></ulink> + class and <filename>mkefidisk.sh</filename> script. The difference between <filename>wic</filename> and those examples is that with <filename>wic</filename> the @@ -3823,7 +3888,8 @@ in the form generated by the build system. </para></listitem> <listitem><para> - You must build several native tools: + You must build several native tools, which are tools + built to run on the build system: <literallayout class='monospaced'> $ bitbake parted-native dosfstools-native mtools-native </literallayout> @@ -4102,8 +4168,8 @@ </para> <para> - The output specifies the exact created as well as where - it was created. + The output specifies the exact image created as well as + where it was created. The output also names the artifacts used and the exact <filename>.wks</filename> script that was used to generate the image. @@ -4491,11 +4557,18 @@ <title>Command: part or partition</title> <para> - This command creates a partition on the system and uses the - following syntax: + Either of these commands create a partition on the system + and uses the following syntax: <literallayout class='monospaced'> - part <replaceable>mntpoint</replaceable> + part [<replaceable>mntpoint</replaceable>] + partition [<replaceable>mntpoint</replaceable>] </literallayout> + If you do not provide + <replaceable>mntpoint</replaceable>, wic creates a partition + but does not mount it. + </para> + + <para> The <filename><replaceable>mntpoint</replaceable></filename> is where the partition will be mounted and must be of one of the @@ -4503,16 +4576,36 @@ <itemizedlist> <listitem><para><filename>/<replaceable>path</replaceable></filename>: For example, <filename>/</filename>, - <filename>/usr</filename>, and + <filename>/usr</filename>, or <filename>/home</filename></para></listitem> <listitem><para><filename>swap</filename>: - The partition will be used as swap space. + The created partition is used as swap space. </para></listitem> </itemizedlist> </para> <para> - Following are the supported options: + Specifying a <replaceable>mntpoint</replaceable> causes + the partition to automatically be mounted. + Wic achieves this by adding entries to the filesystem + table (fstab) during image generation. + In order for wic to generate a valid fstab, you must + also provide one of the <filename>--ondrive</filename>, + <filename>--ondisk</filename>, or + <filename>--use-uuid</filename> partition options as part + of the command. + Here is an example using "/" as the mountpoint. + The command uses "--ondisk" to force the partition onto + the <filename>sdb</filename> disk: + <literallayout class='monospaced'> + part / --source rootfs --ondisk sdb --fstype=ext3 --label platform --align 1024 + </literallayout> + </para> + + <para> + Here is a list that describes other supported options you + can use with the <filename>part</filename> and + <filename>partition</filename> commands: <itemizedlist> <listitem><para><emphasis><filename>--size</filename>:</emphasis> The minimum partition size in MBytes. @@ -4684,6 +4777,14 @@ <filename>APPEND</filename> or <filename>grub</filename> kernel command line. </para></listitem> + <listitem><para><emphasis><filename>--configfile</filename>:</emphasis> + Specifies a user-defined configuration file for + the bootloader. + You can provide a full pathname for the file or + a file that exists in the + <filename>canned-wks</filename> folder. + This option overrides all other bootloader options. + </para></listitem> </itemizedlist> </para> </section> @@ -5013,7 +5114,7 @@ This configuration file will be your baseline. </para></listitem> <listitem><para>Separately run the - <filename>do_configme</filename> and + <filename>do_kernel_configme</filename> and <filename>do_kernel_configcheck</filename> tasks. </para></listitem> <listitem><para>Take the resulting list of files from the @@ -5041,7 +5142,7 @@ <listitem><para> After you have worked through the output of the kernel configuration audit, you can re-run the - <filename>do_configme</filename> and + <filename>do_kernel_configme</filename> and <filename>do_kernel_configcheck</filename> tasks to see the results of your changes. If you have more issues, you can deal with them as @@ -5057,6 +5158,112 @@ Yocto kernel. </para> </section> + + <section id='determining-hardware-and-non-hardware-features-for-the-kernel-configuration-audit-phase'> + <title>Determining Hardware and Non-Hardware Features for the Kernel Configuration Audit Phase</title> + + <para> + This section describes part of the kernel configuration audit + phase that most developers can ignore. + During this part of the audit phase, the contents of the final + <filename>.config</filename> file are compared against the + fragments specified by the system. + These fragments can be system fragments, distro fragments, + or user specified configuration elements. + Regardless of their origin, the OpenEmbedded build system + warns the user if a specific option is not included in the + final kernel configuration. + </para> + + <para> + In order to not overwhelm the user with configuration warnings, + by default the system only reports on missing "hardware" + options because a missing hardware option could mean a boot + failure or that important hardware is not available. + </para> + + <para> + To determine whether or not a given option is "hardware" or + "non-hardware", the kernel Metadata contains files that + classify individual or groups of options as either hardware + or non-hardware. + To better show this, consider a situation where the + Yocto Project kernel cache contains the following files: + <literallayout class='monospaced'> + kernel-cache/features/drm-psb/hardware.cfg + kernel-cache/features/kgdb/hardware.cfg + kernel-cache/ktypes/base/hardware.cfg + kernel-cache/bsp/mti-malta32/hardware.cfg + kernel-cache/bsp/fsl-mpc8315e-rdb/hardware.cfg + kernel-cache/bsp/qemu-ppc32/hardware.cfg + kernel-cache/bsp/qemuarma9/hardware.cfg + kernel-cache/bsp/mti-malta64/hardware.cfg + kernel-cache/bsp/arm-versatile-926ejs/hardware.cfg + kernel-cache/bsp/common-pc/hardware.cfg + kernel-cache/bsp/common-pc-64/hardware.cfg + kernel-cache/features/rfkill/non-hardware.cfg + kernel-cache/ktypes/base/non-hardware.cfg + kernel-cache/features/aufs/non-hardware.kcf + kernel-cache/features/ocf/non-hardware.kcf + kernel-cache/ktypes/base/non-hardware.kcf + kernel-cache/ktypes/base/hardware.kcf + kernel-cache/bsp/qemu-ppc32/hardware.kcf + </literallayout> + The following list provides explanations for the various + files: + <itemizedlist> + <listitem><para><filename>hardware.kcf</filename>: + Specifies a list of kernel Kconfig files that contain + hardware options only. + </para></listitem> + <listitem><para><filename>non-hardware.kcf</filename>: + Specifies a list of kernel Kconfig files that contain + non-hardware options only. + </para></listitem> + <listitem><para><filename>hardware.cfg</filename>: + Specifies a list of kernel + <filename>CONFIG_</filename> options that are hardware, + regardless of whether or not they are within a Kconfig + file specified by a hardware or non-hardware + Kconfig file (i.e. <filename>hardware.kcf</filename> or + <filename>non-hardware.kcf</filename>). + </para></listitem> + <listitem><para><filename>non-hardware.cfg</filename>: + Specifies a list of kernel + <filename>CONFIG_</filename> options that are + not hardware, regardless of whether or not they are + within a Kconfig file specified by a hardware or + non-hardware Kconfig file (i.e. + <filename>hardware.kcf</filename> or + <filename>non-hardware.kcf</filename>). + </para></listitem> + </itemizedlist> + Here is a specific example using the + <filename>kernel-cache/bsp/mti-malta32/hardware.cfg</filename>: + <literallayout class='monospaced'> + CONFIG_SERIAL_8250 + CONFIG_SERIAL_8250_CONSOLE + CONFIG_SERIAL_8250_NR_UARTS + CONFIG_SERIAL_8250_PCI + CONFIG_SERIAL_CORE + CONFIG_SERIAL_CORE_CONSOLE + CONFIG_VGA_ARB + </literallayout> + The kernel configuration audit automatically detects these + files (hence the names must be exactly the ones discussed here), + and uses them as inputs when generating warnings about the + final <filename>.config</filename> file. + </para> + + <para> + A user-specified kernel Metadata repository, or recipe space + feature, can use these same files to classify options that are + found within its <filename>.cfg</filename> files as hardware + or non-hardware, to prevent the OpenEmbedded build system from + producing an error or warning when an option is not in the + final <filename>.config</filename> file. + </para> + </section> </section> <section id="patching-the-kernel"> @@ -5305,14 +5512,14 @@ <filename>poky/build/conf</filename> directory needs to have the path to your local <filename>meta-mylayer</filename> layer. By default, the <filename>BBLAYERS</filename> variable contains paths to - <filename>meta</filename>, <filename>meta-yocto</filename>, and + <filename>meta</filename>, <filename>meta-poky</filename>, and <filename>meta-yocto-bsp</filename> in the <filename>poky</filename> Git repository. Add the path to your <filename>meta-mylayer</filename> location: <literallayout class='monospaced'> BBLAYERS ?= " \ $HOME/poky/meta \ - $HOME/poky/meta-yocto \ + $HOME/poky/meta-poky \ $HOME/poky/meta-yocto-bsp \ $HOME/poky/meta-mylayer \ " @@ -5416,10 +5623,6 @@ "<ulink url='http://elinux.org/images/6/6f/Security-issues.pdf'>Security Issues for Embedded Devices</ulink>"</emphasis> by Jake Edge </para></listitem> - <listitem><para><emphasis> - "<ulink url='https://www.nccgroup.com/media/18475/exploiting_security_gateways_via_their_web_interfaces.pdf'>They ought to know better: Exploiting Security Gateways via their Web Interfaces</ulink>"</emphasis> - by Ben Williams - </para></listitem> </itemizedlist> </para> @@ -5785,7 +5988,7 @@ By default, <filename>TEMPLATECONF</filename> is set as follows in the <filename>poky</filename> repository: <literallayout class='monospaced'> - TEMPLATECONF=${TEMPLATECONF:-meta-yocto/conf} + TEMPLATECONF=${TEMPLATECONF:-meta-poky/conf} </literallayout> This is the directory used by the build system to find templates from which to build some key configuration files. @@ -5837,7 +6040,7 @@ <para> Aside from the <filename>*.sample</filename> configuration files, the <filename>conf-notes.txt</filename> also resides in the - default <filename>meta-yocto/conf</filename> directory. + default <filename>meta-poky/conf</filename> directory. The scripts that set up the build environment (i.e. <ulink url="&YOCTO_DOCS_REF_URL;#structure-core-script"><filename>&OE_INIT_FILE;</filename></ulink> @@ -5860,7 +6063,6 @@ core-image-minimal core-image-sato meta-toolchain - adt-installer meta-ide-support </literallayout> </para> @@ -7544,13 +7746,16 @@ Consequently, you usually need to add a cross-compilation function to the package. </para> + <para>Many packages based on Automake compile and run the test suite by using a single command such as <filename>make check</filename>. - However, the native <filename>make check</filename> + However, the host <filename>make check</filename> builds and runs on the same computer, while cross-compiling requires that the package is built - on the host but executed on the target. + on the host but executed for the target + architecture (though often, as in the case for + ptest, the execution occurs on the host). The built version of Automake that ships with the Yocto Project includes a patch that separates building and execution. @@ -7999,21 +8204,22 @@ This line pulls in the listed include file that contains numerous lines of exactly that form: <literallayout class='monospaced'> + #SRCREV_pn-opkg-native ?= "${AUTOREV}" + #SRCREV_pn-opkg-sdk ?= "${AUTOREV}" + #SRCREV_pn-opkg ?= "${AUTOREV}" + #SRCREV_pn-opkg-utils-native ?= "${AUTOREV}" + #SRCREV_pn-opkg-utils ?= "${AUTOREV}" SRCREV_pn-gconf-dbus ?= "${AUTOREV}" SRCREV_pn-matchbox-common ?= "${AUTOREV}" SRCREV_pn-matchbox-config-gtk ?= "${AUTOREV}" SRCREV_pn-matchbox-desktop ?= "${AUTOREV}" SRCREV_pn-matchbox-keyboard ?= "${AUTOREV}" - SRCREV_pn-matchbox-panel ?= "${AUTOREV}" SRCREV_pn-matchbox-panel-2 ?= "${AUTOREV}" SRCREV_pn-matchbox-themes-extra ?= "${AUTOREV}" SRCREV_pn-matchbox-terminal ?= "${AUTOREV}" SRCREV_pn-matchbox-wm ?= "${AUTOREV}" - SRCREV_pn-matchbox-wm-2 ?= "${AUTOREV}" SRCREV_pn-settings-daemon ?= "${AUTOREV}" SRCREV_pn-screenshot ?= "${AUTOREV}" - SRCREV_pn-libfakekey ?= "${AUTOREV}" - SRCREV_pn-oprofileui ?= "${AUTOREV}" . . . @@ -8134,7 +8340,8 @@ specific to or dependent on the target architecture:</emphasis> You can work around these attempts by using native - tools to accomplish the same tasks, or + tools, which run on the host system, + to accomplish the same tasks, or by alternatively running the processes under QEMU, which has the <filename>qemu_run_binary</filename> function. @@ -9080,11 +9287,8 @@ Before you can initiate a remote debugging session, you need to be sure you have set up the cross-development environment, toolchain, and sysroot. - The "<ulink url='&YOCTO_DOCS_ADT_URL;#adt-prepare'>Preparing for Application Development</ulink>" - chapter of the Yocto Project Application Developer's Guide + The <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-intro'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink> describes this process. - Be sure you have read that chapter and have set up - your environment. </para> </section> @@ -9193,9 +9397,8 @@ location is at <filename>/opt/poky/&DISTRO;</filename> and begins with the string "environment-setup". For more information, see the - "<ulink url='&YOCTO_DOCS_ADT_URL;#setting-up-the-cross-development-environment'>Setting Up the Cross-Development Environment</ulink>" - section in the Yocto Project Application Developer's - Guide. + <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-manual'>Yocto Project Software Development Kit (SDK) Developer's + Guide</ulink>. </para> <para> @@ -9533,6 +9736,7 @@ </section> </section> +<!-- <section id="platdev-oprofile"> <title>Profiling with OProfile</title> @@ -9594,14 +9798,14 @@ <para> <literallayout class='monospaced'> - # opcontrol --reset - # opcontrol --start --separate=lib --no-vmlinux -c 5 + # opcontrol ‐‐reset + # opcontrol ‐‐start ‐‐separate=lib ‐‐no-vmlinux -c 5 . . [do whatever is being profiled] . . - # opcontrol --stop + # opcontrol ‐‐stop $ opreport -cl </literallayout> </para> @@ -9614,7 +9818,7 @@ five levels deep. <note> To profile the kernel, you would specify the - <filename>--vmlinux=/path/to/vmlinux</filename> option. + <filename>‐‐vmlinux=/path/to/vmlinux</filename> option. The <filename>vmlinux</filename> file is usually in the source directory in the <filename>/boot/</filename> directory and must match the running kernel. </note> @@ -9677,7 +9881,7 @@ With this connection, you just need to run "oprofile-server" on the device. By default, OProfile listens on port 4224. <note> - You can change the port using the <filename>--port</filename> command-line + You can change the port using the <filename>‐‐port</filename> command-line option. </note> </para> @@ -9767,14 +9971,14 @@ If network access to the target is unavailable, you can generate an archive for processing in <filename>oprofile-viewer</filename> as follows: <literallayout class='monospaced'> - # opcontrol --reset - # opcontrol --start --separate=lib --no-vmlinux -c 5 + # opcontrol ‐‐reset + # opcontrol ‐‐start ‐‐separate=lib ‐‐no-vmlinux -c 5 . . [do whatever is being profiled] . . - # opcontrol --stop + # opcontrol ‐‐stop # oparchive -o my_archive </literallayout> </para> @@ -9789,6 +9993,7 @@ </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> @@ -9937,10 +10142,33 @@ <literallayout class='monospaced'> COPY_LIC_MANIFEST = "1" COPY_LIC_DIRS = "1" + LICENSE_CREATE_PACKAGE = "1" </literallayout> Adding these statements to the configuration file ensures that the licenses collected during package generation are included on your image. + <note> + <para>Setting all three variables to "1" results in the + image having two copies of the same license file. + One copy resides in + <filename>/usr/share/common-licenses</filename> and + the other resides in + <filename>/usr/share/license</filename>.</para> + + <para>The reason for this behavior is because + <ulink url='&YOCTO_DOCS_REF_URL;#var-COPY_LIC_DIRS'><filename>COPY_LIC_DIRS</filename></ulink> + and + <ulink url='&YOCTO_DOCS_REF_URL;#var-COPY_LIC_MANIFEST'><filename>COPY_LIC_MANIFEST</filename></ulink> + add a copy of the license when the image is built but do not + offer a path for adding licenses for newly installed packages + to an image. + <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_CREATE_PACKAGE'><filename>LICENSE_CREATE_PACKAGE</filename></ulink> + adds a separate package and an upgrade path for adding + licenses to an image.</para> + </note> + </para> + + <para> As the source archiver has already archived the original unmodified source that contains the license files, you would have already met the requirements for inclusion @@ -9979,8 +10207,8 @@ during your build. Here is an example: <literallayout class='monospaced'> - # We built using the &DISTRO_NAME; branch of the poky repo - $ git clone -b &DISTRO_NAME; git://git.yoctoproject.org/poky + # We built using the &DISTRO_NAME_NO_CAP; branch of the poky repo + $ git clone -b &DISTRO_NAME_NO_CAP; git://git.yoctoproject.org/poky $ cd poky # We built using the release_branch for our layers $ git clone -b release_branch git://git.mycompany.com/meta-my-bsp-layer @@ -9990,7 +10218,7 @@ </literallayout> One thing a development organization might want to consider for end-user convenience is to modify - <filename>meta-yocto/conf/bblayers.conf.sample</filename> to + <filename>meta-poky/conf/bblayers.conf.sample</filename> to ensure that when the end user utilizes the released build system to build an image, the development organization's layers are included in the <filename>bblayers.conf</filename> @@ -10005,7 +10233,7 @@ BBLAYERS ?= " \ ##OEROOT##/meta \ - ##OEROOT##/meta-yocto \ + ##OEROOT##/meta-poky \ ##OEROOT##/meta-yocto-bsp \ ##OEROOT##/meta-mylayer \ " diff --git a/yocto-poky/documentation/dev-manual/dev-manual-intro.xml b/yocto-poky/documentation/dev-manual/dev-manual-intro.xml index e350882a3..caa066e82 100644 --- a/yocto-poky/documentation/dev-manual/dev-manual-intro.xml +++ b/yocto-poky/documentation/dev-manual/dev-manual-intro.xml @@ -29,8 +29,8 @@ <para> The Yocto Project Development Manual does, however, provide guidance and examples on how to change the kernel source code, - reconfigure the kernel, and develop an application using the - popular <trademark class='trade'>Eclipse</trademark> IDE. + reconfigure the kernel, and develop an application using + <filename>devtool</filename>. </para> <note> @@ -86,17 +86,21 @@ <itemizedlist> <listitem><para><emphasis>Step-by-step instructions when those instructions exist in other Yocto Project documentation:</emphasis> - For example, the Yocto Project Application Developer's Guide contains detailed - instructions on how to run the - <ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>ADT Installer</ulink>, - which is used to set up a cross-development environment.</para></listitem> + For example, the + <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink> + manual contains detailed instructions on how to install an + SDK, which is used to develop applications for target + hardware. + </para></listitem> <listitem><para><emphasis>Reference material:</emphasis> This type of material resides in an appropriate reference manual. For example, system variables are documented in the - <ulink url='&YOCTO_DOCS_REF_URL;'>Yocto Project Reference Manual</ulink>.</para></listitem> + <ulink url='&YOCTO_DOCS_REF_URL;'>Yocto Project Reference Manual</ulink>. + </para></listitem> <listitem><para><emphasis>Detailed public information that is not specific to the Yocto Project:</emphasis> For example, exhaustive information on how to use Git is covered better through the - Internet than in this manual.</para></listitem> + Internet than in this manual. + </para></listitem> </itemizedlist> </para> </section> @@ -126,10 +130,12 @@ The build system is sometimes referred to as "Poky". </para></listitem> <listitem><para><emphasis> - <ulink url='&YOCTO_DOCS_ADT_URL;'>Yocto Project Application Developer's Guide</ulink>:</emphasis> - This guide provides information that lets you get going with the Application - Development Toolkit (ADT) and stand-alone cross-development toolchains to - develop projects using the Yocto Project. + <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>:</emphasis> + This guide provides information that lets you get going + with the standard or extensible SDK. + An SDK, with its cross-development toolchains, allows you + to develop projects inside or outside of the Yocto Project + environment. </para></listitem> <listitem><para><emphasis> <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>:</emphasis> @@ -169,11 +175,6 @@ release of the Yocto Project. </para></listitem> <listitem><para><emphasis> - <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink>:</emphasis> - A graphical user interface for BitBake. - Hob's primary goal is to enable a user to perform common tasks more easily. - </para></listitem> - <listitem><para><emphasis> <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/toaster'>Toaster</ulink>:</emphasis> An Application Programming Interface (API) and web-based interface to the OpenEmbedded build system, which uses diff --git a/yocto-poky/documentation/dev-manual/dev-manual-model.xml b/yocto-poky/documentation/dev-manual/dev-manual-model.xml index 6e42c7b39..ff44a3f68 100644 --- a/yocto-poky/documentation/dev-manual/dev-manual-model.xml +++ b/yocto-poky/documentation/dev-manual/dev-manual-model.xml @@ -27,11 +27,10 @@ that you intend to run on target hardware. For information on how to set up your host development system for user-space application development, see the - <ulink url='&YOCTO_DOCS_ADT_URL;'>Yocto Project Application Developer's Guide</ulink>. + <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>. For a simple example of user-space application development using the <trademark class='trade'>Eclipse</trademark> IDE, see the - "<link linkend='application-development-workflow'>Application - Development Workflow</link>" section. + "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-developing-applications-using-eclipse'>Developing Applications Using <trademark class='trade'>Eclipse</trademark></ulink>" section. </para></listitem> <listitem><para><emphasis>Temporary Source Code Modification:</emphasis> Direct modification of temporary source code is a convenient @@ -48,14 +47,10 @@ Toaster provides an efficient interface to the OpenEmbedded build that allows you to start builds and examine build statistics. </para></listitem> - <listitem><para><emphasis>Image Development using Hob:</emphasis> - You can use the <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink> - to build custom operating system images within the build - environment. - Hob provides an efficient interface to the OpenEmbedded build system. - </para></listitem> <listitem><para><emphasis>Using a Development Shell:</emphasis> - You can use a <filename>devshell</filename> to efficiently debug + You can use a + <link linkend='platdev-appdev-devshell'><filename>devshell</filename></link> + to efficiently debug commands or simply edit packages. Working inside a development shell is a quick way to set up the OpenEmbedded build environment to work on parts of a project. @@ -154,38 +149,60 @@ "<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 (BSP) Developer's Guide. </para> + <para> - Another example that illustrates a layer is an application. - Suppose you are creating an application that has library or other dependencies in - order for it to compile and run. - The layer, in this case, would be where all the recipes that define those dependencies - are kept. - The key point for a layer is that it is an isolated area that contains - all the relevant information for the project that the OpenEmbedded build - system knows about. - For more information on layers, see the - "<link linkend='understanding-and-creating-layers'>Understanding and Creating Layers</link>" - section. - For more information on BSP layers, see the - "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>" section in the - Yocto Project Board Support Package (BSP) Developer's Guide.</para> - <note>Five BSPs exist that are part of the - Yocto Project release: <filename>genericx86</filename>, <filename>genericx86-64</filename>, - <filename>beaglebone</filename> (ARM), - <filename>mpc8315e</filename> (PowerPC), - and <filename>edgerouter</filename> (MIPS). - The recipes and configurations for these five BSPs are located and dispersed - within the <link linkend='source-directory'>Source Directory</link>. - On the other hand, the <filename>meta-intel</filename> layer - contains BSP layers for many supported BSPs (e.g. - Crystal Forest, Emenlow, Fish River Island 2, Haswell, - Jasper Forest, and so forth). - Aside from the BSPs in the <filename>meta-intel</filename> - layer, the - <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink> - contain additional BSP layers such as - <filename>meta-minnow</filename> and - <filename>meta-raspberrypi</filename>.</note> + Another example that illustrates a layer + is an application. + Suppose you are creating an application that has + library or other dependencies in order for it to + compile and run. + The layer, in this case, would be where all the + recipes that define those dependencies are kept. + The key point for a layer is that it is an isolated + area that contains all the relevant information for + the project that the OpenEmbedded build system knows + about. + For more information on layers, see the + "<link linkend='understanding-and-creating-layers'>Understanding and Creating Layers</link>" + section. + For more information on BSP layers, see the + "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>" + section in the Yocto Project Board Support Package (BSP) + Developer's Guide. + <note> + <para> + Five BSPs exist that are part of the Yocto Project release: + <filename>beaglebone</filename> (ARM), + <filename>mpc8315e</filename> (PowerPC), + and <filename>edgerouter</filename> (MIPS). + The recipes and configurations for these five BSPs + are located and dispersed within the + <link linkend='source-directory'>Source Directory</link>. + </para> + + <para> + Three core Intel BSPs exist as part of the Yocto + Project release in the + <filename>meta-intel</filename> layer: + <itemizedlist> + <listitem><para><filename>intel-core2-32</filename>, + which is a BSP optimized for the Core2 family of CPUs + as well as all CPUs prior to the Silvermont core. + </para></listitem> + <listitem><para><filename>intel-corei7-64</filename>, + which is a BSP optimized for Nehalem and later + Core and Xeon CPUs as well as Silvermont and later + Atom CPUs, such as the Baytrail SoCs. + </para></listitem> + <listitem><para><filename>intel-quark</filename>, + which is a BSP optimized for the Intel Galileo + gen1 & gen2 development boards. + </para></listitem> + </itemizedlist> + </para> + </note> + </para> + <para>When you set up a layer for a new BSP, you should follow a standard layout. This layout is described in the "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout'>Example Filesystem Layout</ulink>" @@ -296,18 +313,6 @@ the Yocto Project: <itemizedlist> <listitem><para><emphasis> - <filename>linux-yocto-3.8</filename></emphasis> - The - stable Yocto Project kernel to use with the Yocto - Project Release 1.4. This kernel is based on the - Linux 3.8 released kernel. - </para></listitem> - <listitem><para><emphasis> - <filename>linux-yocto-3.10</filename></emphasis> - An - additional, unsupported Yocto Project kernel used with - the Yocto Project Release 1.5. - This kernel is based on the Linux 3.10 released kernel. - </para></listitem> - <listitem><para><emphasis> <filename>linux-yocto-3.14</filename></emphasis> - The stable Yocto Project kernel to use with the Yocto Project Releases 1.6 and 1.7. @@ -326,11 +331,35 @@ This kernel is based on the Linux 3.19 released kernel. </para></listitem> <listitem><para><emphasis> + <filename>linux-yocto-4.1</filename></emphasis> - The + stable Yocto Project kernel to use with the Yocto + Project Release 2.0. + This kernel is based on the Linux 4.1 released kernel. + </para></listitem> + <listitem><para><emphasis> + <filename>linux-yocto-4.4</filename></emphasis> - The + stable Yocto Project kernel to use with the Yocto + Project Release 2.1. + This kernel is based on the Linux 4.4 released kernel. + </para></listitem> + <listitem><para><emphasis> <filename>linux-yocto-dev</filename></emphasis> - A development kernel based on the latest upstream release candidate available. </para></listitem> </itemizedlist> + <note> + Long Term Support Initiative (LTSI) for Yocto Project kernels + is as follows: + <itemizedlist> + <listitem><para>For Yocto Project releases 1.7, 1.8, and 2.0, + the LTSI kernel is <filename>linux-yocto-3.14</filename>. + </para></listitem> + <listitem><para>For Yocto Project release 2.1, the + LTSI kernel is <filename>linux-yocto-4.1</filename>. + </para></listitem> + </itemizedlist> + </note> </para> <para> @@ -535,1161 +564,18 @@ </section> </section> -<section id='application-development-workflow'> - <title>Application Development Workflow</title> - - <para> - Application development involves creating an application that you want - to run on your target hardware, which is running a kernel image created using the - OpenEmbedded build system. - The Yocto Project provides an - <ulink url='&YOCTO_DOCS_ADT_URL;#adt-intro'>Application Development Toolkit (ADT)</ulink> - and stand-alone - <ulink url='&YOCTO_DOCS_ADT_URL;#the-cross-development-toolchain'>cross-development toolchains</ulink> - that facilitate quick development and integration of your application into its runtime environment. - Using the ADT and toolchains, you can compile and link your application. - You can then deploy your application to the actual hardware or to the QEMU emulator for testing. - If you are familiar with the popular <trademark class='trade'>Eclipse</trademark> IDE, - you can use an Eclipse Yocto Plug-in to - allow you to develop, deploy, and test your application all from within Eclipse. - </para> +<section id='application-development-workflow-using-an-sdk'> + <title>Application Development Workflow Using an SDK</title> <para> - While we strongly suggest using the ADT to develop your application, this option might not - be best for you. - If this is the case, you can still use pieces of the Yocto Project for your development process. - However, because the process can vary greatly, this manual does not provide detail on the process. + Standard and extensible Software Development Kits (SDK) make it easy + to develop applications inside or outside of the Yocto Project + development environment. + Tools exist to help the application developer during any phase + of development. + For information on how to install and use an SDK, see the + <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-intro'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>. </para> - - <section id='workflow-using-the-adt-and-eclipse'> - <title>Workflow Using the ADT and <trademark class='trade'>Eclipse</trademark></title> - - <para> - To help you understand how application development works using the ADT, this section - provides an overview of the general development process and a detailed example of the process - as it is used from within the Eclipse IDE. - </para> - - <para> - The following illustration and list summarize the application development general workflow. - </para> - - <para> - <imagedata fileref="figures/app-dev-flow.png" - width="7in" depth="8in" 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 - "<link linkend='patching-the-kernel'>Patching the Kernel</link>" - section 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_QS_URL;#downloading-the-pre-built-linux-kernel'>Downloading the Pre-Built Linux Kernel</ulink>" - section in the Yocto Project Application Developer's Guide.</para></listitem> - <listitem><para><emphasis>Install the ADT</emphasis>: - The ADT provides a target-specific cross-development toolchain, the root filesystem, - the QEMU emulator, and other tools that can help you develop your application. - While it is possible to get these pieces separately, the ADT Installer provides an - easy, inclusive method. - You can get these pieces by running an ADT installer script, which is configurable. - For information on how to install the ADT, see the - "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Using the ADT Installer</ulink>" - section - in the Yocto Project Application Developer's Guide.</para></listitem> - <listitem><para><emphasis>If applicable, secure the target root filesystem - and the Cross-development toolchain</emphasis>: - If you choose not to install the ADT using the ADT Installer, - 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 "<ulink url='&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>" - section in the Yocto Project Application Developer's Guide for information - and the - "<ulink url='&YOCTO_DOCS_QS_URL;#installing-the-toolchain'>Installing the Toolchain</ulink>" - in the Yocto Project Application Developer's Guide for information on finding and installing - the correct toolchain based on your host development system and your target - architecture. - </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 - "<link linkend='dev-manual-qemu'>Using the Quick EMUlator (QEMU)</link>" - chapter for information on using QEMU. - </para></listitem> - <listitem><para><emphasis>Test and debug the application</emphasis>: - Once your application is deployed, you need to test it. - Within the Eclipse IDE, you can use the debugging environment along with the - set of user-space tools installed along with the ADT 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> - </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. - <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> - </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. - </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;</filename> for the - release name: - <literallayout class='monospaced'> - $ ECLIPSE_HOME=/home/scottrif/eclipse-poky/scripts/eclipse ./build.sh luna/yocto-&DISTRO; master &DISTRO_NAME; 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 - <link linkend='build-directory'>Build Directory</link>. - 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. - If you used the ADT Installer script and - accepted the default installation directory, the - toolchain will be installed in the - <filename>&YOCTO_ADTPATH_DIR;</filename> - directory. - Sections "<ulink url='&YOCTO_DOCS_ADT_URL;#configuring-and-running-the-adt-installer-script'>Configuring and Running the ADT Installer Script</ulink>" - and - "<ulink url='&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>" - in the Yocto Project Application Developer's - Guide describe how to install a stand-alone - cross-toolchain.</para> - <para>If you are using a system-derived - toolchain, the path you provide for the - <filename>Toolchain Root Location</filename> - field is the - <link linkend='build-directory'>Build Directory</link>. - See the - "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-toolchain-from-within-the-build-tree'>Using BitBake and the Build Directory</ulink>" - section in the Yocto Project Application - Developer's Guide for information on how to - install the toolchain into the Build - Directory.</para></listitem> - <listitem><para><emphasis>Specify the Sysroot Location:</emphasis> - This location is where the root filesystem for - the target hardware resides. - If you used the ADT Installer script and - accepted the default installation directory, - then the location in your home directory - in a folder named - <filename>test-yocto/</filename><replaceable>target_arch</replaceable>. - Additionally, when you use the ADT Installer - script, the - <filename>/opt/poky/&DISTRO;/sysroots</filename> - location is used for the QEMU - user-space tools and the NFS boot process. - </para> - <para>If you used either of the other two - methods to install the toolchain or did not - accept the ADT Installer script's default - installation directory, then 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 - "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>" - section in the Yocto Project Application - Developer's Guide. - </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 section - "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-command-line'>Using the Command Line</ulink>" - in the Yocto Project Application Developer's Guide. - <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 - "<link linkend='dev-manual-qemu'>Using the Quick EMUlator (QEMU)</link>" - chapter for more information on using QEMU. - </note> - <orderedlist> - <listitem><para>Expose and select "External Tools" from - the "Run" menu. - 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. - <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>OProfile</filename>:</emphasis> - Selecting this tool causes the - <filename>oprofile-server</filename> on the remote - target to launch on the local host machine. - The <filename>oprofile-viewer</filename> must be - installed on the local host machine and the - <filename>oprofile-server</filename> must be installed - on the remote target, respectively, in order to use. - You must compile and install the - <filename>oprofile-viewer</filename> from the source - code on your local host machine. - Furthermore, in order to convert the target's sample - format data into a form that the host can use, you must - have OProfile version 0.9.4 or greater installed on the - host.</para> - <para>You can locate both the viewer and server from - <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/oprofileui/'></ulink>. - You can also find more information on setting up and - using this tool in the - "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-oprofile'>oprofile</ulink>" - section of the Yocto Project Profiling and Tracing - Manual. - <note>The <filename>oprofile-server</filename> is - installed by default on the - <filename>core-image-sato-sdk</filename> image.</note> - </para></listitem> - <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 id='workflow-using-stand-alone-cross-development-toolchains'> - <title>Workflow Using Stand-Alone Cross-Development Toolchains</title> - - <para> - If you want to develop an application without prior installation - of the ADT, you still can employ the - <link linkend='cross-development-toolchain'>Cross Development Toolchain</link>, - the QEMU emulator, and a number of supported target image files. - You just need to follow these general steps: - <orderedlist> - <listitem><para><emphasis>Install the cross-development - toolchain for your target hardware:</emphasis> - For information on how to install the toolchain, see the - "<ulink url='&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>" - section in the Yocto Project Application Developer's - Guide.</para></listitem> - <listitem><para><emphasis>Download the Target Image:</emphasis> - The Yocto Project supports several target architectures - and has many pre-built kernel images and root filesystem - images.</para> - <para>If you are going to develop your application on - hardware, go to the - <ulink url='&YOCTO_MACHINES_DL_URL;'><filename>machines</filename></ulink> - download area and choose a target machine area - from which to download the kernel image and root filesystem. - This download area could have several files in it that - support development using actual hardware. - For example, the area might contain - <filename>.hddimg</filename> files that combine the - kernel image with the filesystem, boot loaders, and - so forth. - Be sure to get the files you need for your particular - development process.</para> - <para>If you are going to develop your application and - then run and test it using the QEMU emulator, go to the - <ulink url='&YOCTO_QEMU_DL_URL;'><filename>machines/qemu</filename></ulink> - download area. - From this area, go down into the directory for your - target architecture (e.g. <filename>qemux86_64</filename> - for an <trademark class='registered'>Intel</trademark>-based - 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 - "<ulink url='&YOCTO_DOCS_ADT_URL;#extracting-the-root-filesystem'>Extracting the Root Filesystem</ulink>" - 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. - If you need to separately install and use the QEMU - emulator, you can go to - <ulink url='http://wiki.qemu.org/Main_Page'>QEMU Home Page</ulink> - to download and learn about the emulator. - You can see the - "<link linkend='dev-manual-qemu'>Using the Quick EMUlator (QEMU)</link>" - chapter for information on using QEMU within the Yocto - Project.</para></listitem> - </orderedlist> - </para> - </section> </section> <section id="dev-modifying-source-code"> @@ -1719,7 +605,7 @@ describes this workflow. If you want more information that showcases the workflow, click <ulink url='https://drive.google.com/a/linaro.org/file/d/0B3KGzY5fW7laTDVxUXo3UDRvd2s/view'>here</ulink> - for an excellent presentation by Trevor Woerner that + for a presentation by Trevor Woerner that, while somewhat dated, provides detailed background information and a complete working tutorial. </para></listitem> @@ -1743,212 +629,647 @@ As mentioned earlier, <filename>devtool</filename> helps you easily develop projects whose build output must be part of an image built using the OpenEmbedded build system. - The remainder of this section presents the workflow you would - use that includes <filename>devtool</filename>. - <footnote> - <para> - Kudos and thanks to - <ulink url='mailto:twoerner@gmail.com'>Trevor Woerner</ulink> - whose - "<ulink url='https://drive.google.com/file/d/0B3KGzY5fW7laTDVxUXo3UDRvd2s/view'>Yocto Project Developer Workflow Tutorial</ulink>" - paper contributed nicely towards the development of this - section. - </para> - </footnote> </para> <para> - The steps in this section assume 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. + Three entry points exist that allow you to develop using + <filename>devtool</filename>: + <itemizedlist> + <listitem><para><emphasis><filename>devtool add</filename></emphasis> + </para></listitem> + <listitem><para><emphasis><filename>devtool modify</filename></emphasis> + </para></listitem> + <listitem><para><emphasis><filename>devtool upgrade</filename></emphasis> + </para></listitem> + </itemizedlist> + </para> + + <para> + The remainder of this section presents these workflows. </para> - <section id='update-your-external-source'> - <title>Update Your External Source</title> + <section id='use-devtool-to-integrate-new-code'> + <title>Use <filename>devtool add</filename> to Integrate New Code</title> <para> - Part of the development flow using - <filename>devtool</filename> of course involves updating - your source files. - Several opportunities exist in the workflow to extract and - work on the files. - For now, just realize that you need to be able to have - access to and edit files. - One obvious solution is to initially extract the code into an - isolated area in preparation for modification. + 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> + 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> - Another option is to use the - <filename>devtool modify</filename> command. - This command makes use of a "workspace" layer where much of - the transitional work occurs, which is needed for setting up - Metadata used by the OpenEmbedded build system that lets you - build your software. - Options (i.e. "-x") exist using <filename>devtool</filename> - that enable you to use the tool to extract source code. + 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> - - <section id='use-devtool-to-integrate-your-code-with-the-image'> - <title>Use <filename>devtool add</filename> to Integrate Your Code with the Image</title> <para> - The <filename>devtool add</filename> command automatically - generates the needed Metadata that allows the OpenEmbedded - build system to build your code into the image. - <note> - If a package or packages produced by the recipe on which - you are working are not already in - <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink> - for the image, you must add them. - The <filename>devtool add</filename> command does not - add them for you. - </note> - Use the following command form: - <literallayout class='monospaced'> - $ devtool add <replaceable>your-project-name</replaceable> <replaceable>path-to-source</replaceable> - </literallayout> + <imagedata fileref="figures/devtool-add-flow.png" align="center" /> </para> <para> - Running <filename>devtool</filename> for the first time - creates a workspace layer through the - <filename>bblayers.conf</filename> file that - is based on your project's location: - <literallayout class='monospaced'> - <replaceable>path-to-source</replaceable>/<replaceable>build-directory</replaceable>/<replaceable>workspace-layer</replaceable> - </literallayout> - By default, the name of the workspace layer is "workspace". + <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>: + <note> + You could use <filename>bitbake</filename> to build + the recipe as well. + </note> + <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> </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> <para> - For details on the workspace layer created in the - <replaceable>build-directory</replaceable>, - see the - "<link linkend='devtool-adding-a-new-recipe-to-the-workspace'>Adding a New Recipe to the Workspace Layer</link>" - section. + 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> - Of course, each layer must have a - <filename>layer.conf</filename> configuration file. - <filename>devtool</filename> also creates this configuration - file: - <literallayout class='monospaced'> - $ cat workspace/conf/layer.conf - # ### workspace layer autogenerated by devtool ### - BBPATH =. "${LAYERDIR}:" - BBFILES += "${LAYERDIR}/recipes/*/*.bb \ - ${LAYERDIR}/appends/*.bbappend" - BBFILE_COLLECTIONS += "workspacelayer" - BBFILE_PATTERN_workspacelayer = "^${LAYERDIR}/" - BBFILE_PATTERN_IGNORE_EMPTY_workspacelayer = "1" - BBFILE_PRIORITY_workspacelayer = "99" - </literallayout> + 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> - Running <filename>devtool add</filename> automatically - generates your recipe: - <literallayout class='monospaced'> - $ cat workspace/recipes/<replaceable>your-project-name</replaceable>/<replaceable>your-project-name</replaceable>.bb - # Recipe created by recipetool - # This is the basis of a recipe and may need further editing in order to be fully functional. - # (Feel free to remove these comments when editing.) - # - # Unable to find any files that looked like license statements. Check the accompanying - # documentation and source headers and set LICENSE and LIC_FILES_CHKSUM accordingly. - LICENSE = "CLOSED" - LIC_FILES_CHKSUM = "" - - # No information for SRC_URI yet (only an external source tree was - # specified) - SRC_URI = "" - - DEPENDS = "libx11" - # NOTE: if this software is not capable of being built in a separate build directory - # from the source, you should replace autotools with autotools-brokensep in the - # inherit line - inherit autotools - - # Specify any options you want to pass to the configure script using EXTRA_OECONF: - EXTRA_OECONF = "" - </literallayout> + <imagedata fileref="figures/devtool-modify-flow.png" align="center" /> </para> <para> - Lastly, the <filename>devtool add</filename> command creates the - <filename>.bbappend</filename> file: - <literallayout class='monospaced'> - $ cat workspace/appends/<replaceable>your-project-name</replaceable>.bbappend - inherit externalsrc - EXTERNALSRC = "/<replaceable>path-to-source</replaceable>/<replaceable>your-project-name</replaceable>" + <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> - # initial_rev: <replaceable>commit-ID</replaceable> - </literallayout> + <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. + 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>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 id='build-your-project'> - <title>Build Your Project</title> + <section id='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> - You can use BitBake or <filename>devtool build</filename> to - build your modified project. + 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> - To use BitBake, use the following: - <literallayout class='monospaced'> - $ bitbake <replaceable>your-project-name</replaceable> - </literallayout> - Alternatively, you can use - <filename>devtool build</filename>, which is equivalent to - <filename>bitbake -c populate_sysroot</filename>. - For example: - <literallayout class='monospaced'> - $ devtool build <replaceable>your-project-name</replaceable> - </literallayout> + 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> - </section> - -<!-- - <section id='dev-build-the-image'> - <title>Build the Image</title> <para> - The final step before testing is to rebuild the base image - with your project changes as part of the image. - Simply run BitBake again on your image. - Here is an example: - <literallayout class='monospaced'> - $ bitbake <replaceable>image</replaceable> - </literallayout> + <imagedata fileref="figures/devtool-upgrade-flow.png" align="center" /> </para> - </section> - - <section id='dev-testing-the-image'> - <title>Testing the Image</title> <para> - Once you have the image, you can test it using QEMU. - Here is an example assuming "qemux86": - <literallayout class='monospaced'> - $ runqemu qemux86 <replaceable>image</replaceable> - </literallayout> - For information on how to test an image using QEMU, see the - "<link linkend='dev-manual-qemu'>Using the Quick EMUlator (QEMU)</link>" - section. + <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>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. + </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> + </literallayout> + </para></listitem> + </orderedlist> </para> </section> ---> </section> <section id='devtool-quick-reference'> @@ -1959,7 +1280,7 @@ adding a new recipe and the supporting Metadata to a temporary workspace layer. This section provides a short reference on - <filename>devtool</filename> for most of the commands. + <filename>devtool</filename> and its commands. </para> <section id='devtool-getting-help'> @@ -1970,32 +1291,43 @@ <filename>devtool</filename> command is using the <filename>--help</filename> option: <literallayout class='monospaced'> - $ devtool --help - usage: devtool [-h] [--basepath BASEPATH] [-d] [-q] [--color COLOR] - <subcommand> ... + usage: devtool [--basepath BASEPATH] [--bbpath BBPATH] [-d] [-q] + [--color COLOR] [-h] + <subcommand> ... OpenEmbedded development tool optional arguments: - -h, --help show this help message and exit --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: - <subcommand> - create-workspace Set up a workspace - deploy-target Deploy recipe output files to live target machine - undeploy-target Undeploy recipe output files in live target machine - add Add a new recipe - modify Modify the source for an existing recipe - extract Extract the source for an existing recipe - update-recipe Apply changes from external source tree to recipe - status Show workspace status - build Build a recipe - reset Remove a recipe from your workspace - + 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> @@ -2006,22 +1338,95 @@ name and using <filename>--help</filename>: <literallayout class='monospaced'> $ devtool add --help - usage: devtool add [-h] [--same-dir] [--fetch URI] [--version VERSION] - recipename srctree + 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 + 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 - srctree Path to external source tree + 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 + 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> @@ -2040,51 +1445,69 @@ <para> The following example creates and adds a new recipe named - <filename>jackson</filename> to the workspace layer. + <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> - <note> - For complete syntax, use the - <filename>devtool add --help</filename> command. - </note> </para> <para> If you add a recipe and the workspace layer does not exist, - the command creates the layer and populates it as follows: + 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> - <imagedata fileref="figures/build-workspace-directory.png" - width="6in" depth="4in" align="center" scale="100" /> + 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> - <literallayout class='monospaced'> - README - Provides information on what is in workspace layer and how to - manage it. + 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> - appends - A directory that contains *.bbappend files, which point to - external source. + <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> - conf - A configuration directory that contains the layer.conf file. + <section id='devtool-synchronizing-a-recipes-extracted-source-tree'> + <title>Synchronizing a Recipe's Extracted Source Tree</title> - recipes - A directory containing recipes. This directory contains a - folder for each directory added whose name matches that of the - added recipe. devtool places the <replaceable>recipe</replaceable>.bb file - within that sub-directory. - </literallayout> + <para> + 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> - Running <filename>devtool add</filename> when the - workspace layer exists causes the tool to add the recipe - and append files into the existing workspace layer. - The <filename>.bbappend</filename> file is created to point - to the external source tree. + 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> @@ -2110,14 +1533,37 @@ You can use the following command to checkout the source files: <literallayout class='monospaced'> - $ devtool modify -x <replaceable>recipe</replaceable> <replaceable>path-to-source</replaceable> + $ devtool modify <replaceable>recipe</replaceable> </literallayout> - Using the above command form, the default development branch - would be "devtool". - <note> - For complete syntax, use the - <filename>devtool modify --help</filename> command. - </note> + 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> @@ -2167,10 +1613,32 @@ file. If an append file already exists, the command updates it appropriately. - <note> - For complete syntax, use the - <filename>devtool update-recipe --help</filename> command. - </note> + </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> @@ -2195,32 +1663,64 @@ the recipe or the append files have been modified, the command preserves the modified files in a separate "attic" subdirectory under the workspace layer. - <note> - For complete syntax, use the - <filename>devtool reset --help</filename> command. - </note> + </para> + + <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-software'> - <title>Building Your Software</title> + <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 software based - on the recipe file. + 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> - <note> - For complete syntax, use the - <filename>devtool build --help</filename> command. - </note> - Building your software using <filename>devtool build</filename> - is identical to using BitBake to build the software. + </para> + </section> + + <section id='devtool-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> @@ -2252,12 +1752,6 @@ You should never use it to update an image that will be used in production. </para> - - <para> - For complete syntax, use the - <filename>devtool deploy-target --help</filename> - command. - </para> </note> </para> </section> @@ -2278,10 +1772,6 @@ The <replaceable>target</replaceable> is the address of the target machine, which must be running an SSH server (i.e. <filename>user@hostname</filename>). - <note> - For complete syntax, use the - <filename>devtool undeploy-target --help</filename> command. - </note> </para> </section> @@ -2304,10 +1794,6 @@ <literallayout class='monospaced'> $ devtool create-workspace </literallayout> - <note> - For complete syntax, use the - <filename>devtool create-workspace --help</filename> command. - </note> </para> <para> @@ -2320,6 +1806,54 @@ </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"> @@ -2541,56 +2075,19 @@ </para> </section> -<section id='image-development-using-hob'> - <title>Image Development Using Hob</title> - - <para> - The <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink> is a graphical user interface for the - OpenEmbedded build system, which is based on BitBake. - You can use the Hob to build custom operating system images within the Yocto Project build environment. - Hob simply provides a friendly interface over the build system used during development. - In other words, building images with the Hob lets you take care of common build tasks more easily. - </para> - - <para> - For a better understanding of Hob, see the project page at - <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'></ulink> - on the Yocto Project website. - If you follow the "Documentation" link from the Hob page, you will - find a short introductory training video on Hob. - The following lists some features of Hob: - <itemizedlist> - <listitem><para>You can setup and run Hob using these commands: - <literallayout class='monospaced'> - $ source oe-init-build-env - $ hob - </literallayout></para></listitem> - <listitem><para>You can set the - <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> - for which you are building the image.</para></listitem> - <listitem><para>You can modify various policy settings such as the - package format with which to build, - the parallelism BitBake uses, whether or not to build an - external toolchain, and which host to build against. - </para></listitem> - <listitem><para>You can manage - <link linkend='understanding-and-creating-layers'>layers</link>.</para></listitem> - <listitem><para>You can select a base image and then add extra packages for your custom build. - </para></listitem> - <listitem><para>You can launch and monitor the build from within Hob.</para></listitem> - </itemizedlist> - </para> -</section> - <section id="platdev-appdev-devshell"> <title>Using a Development Shell</title> <para> When debugging certain commands or even when just editing packages, <filename>devshell</filename> can be a useful tool. - When you invoke <filename>devshell</filename>, source files are - extracted into your working directory and patches are applied. - Then, a new terminal is opened and you are placed in the working directory. + When you invoke <filename>devshell</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 and you are placed in + <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink><filename>}</filename>, + the source directory. In the new terminal, all the OpenEmbedded build-related environment variables are still defined so you can use commands such as <filename>configure</filename> and <filename>make</filename>. @@ -2634,24 +2131,64 @@ </para> <para> - When you are finished, you just exit the shell or close the terminal window. + To manually run a specific task using <filename>devshell</filename>, + run the corresponding <filename>run.*</filename> script in + the + <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/temp</filename> + directory (e.g., + <filename>run.do_configure.</filename><replaceable>pid</replaceable>). + If a task's script does not exist, which would be the case if the task was + skipped by way of the sstate cache, you can create the task by first running + it outside of the <filename>devshell</filename>: + <literallayout class='monospaced'> + $ bitbake -c <replaceable>task</replaceable> + </literallayout> + <note><title>Notes</title> + <itemizedlist> + <listitem><para>Execution of a task's <filename>run.*</filename> + script and BitBake's execution of a task are identical. + In other words, running the script re-runs the task + just as it would be run using the + <filename>bitbake -c</filename> command. + </para></listitem> + <listitem><para>Any <filename>run.*</filename> file that does not + have a <filename>.pid</filename> extension is a + symbolic link (symlink) to the most recent version of that + file. + </para></listitem> + </itemizedlist> + </note> </para> - <note> - <para> - It is worth remembering that when using <filename>devshell</filename> - you need to use the full compiler name such as <filename>arm-poky-linux-gnueabi-gcc</filename> - instead of just using <filename>gcc</filename>. - The same applies to other applications such as <filename>binutils</filename>, - <filename>libtool</filename> and so forth. - BitBake sets up environment variables such as <filename>CC</filename> - to assist applications, such as <filename>make</filename> to find the correct tools. - </para> + <para> + Remember, that the <filename>devshell</filename> is a mechanism that allows + you to get into the BitBake task execution environment. + And as such, all commands must be called just as BitBake would call them. + That means you need to provide the appropriate options for + cross-compilation and so forth as applicable. + </para> - <para> - It is also worth noting that <filename>devshell</filename> still works over - X11 forwarding and similar situations. - </para> + <para> + When you are finished using <filename>devshell</filename>, exit the shell + or close the terminal window. + </para> + + <note><title>Notes</title> + <itemizedlist> + <listitem><para> + It is worth remembering that when using <filename>devshell</filename> + you need to use the full compiler name such as <filename>arm-poky-linux-gnueabi-gcc</filename> + instead of just using <filename>gcc</filename>. + The same applies to other applications such as <filename>binutils</filename>, + <filename>libtool</filename> and so forth. + BitBake sets up environment variables such as <filename>CC</filename> + to assist applications, such as <filename>make</filename> to find the correct tools. + </para></listitem> + <listitem><para> + It is also worth noting that <filename>devshell</filename> still works over + X11 forwarding and similar situations. + </para></listitem> + </itemizedlist> </note> </section> diff --git a/yocto-poky/documentation/dev-manual/dev-manual-newbie.xml b/yocto-poky/documentation/dev-manual/dev-manual-newbie.xml index 70fa96975..75c992f16 100644 --- a/yocto-poky/documentation/dev-manual/dev-manual-newbie.xml +++ b/yocto-poky/documentation/dev-manual/dev-manual-newbie.xml @@ -96,7 +96,10 @@ <para> For developers who mainly do application level work on top of an existing software stack, - here are some practices that work best: + the following list shows practices that work best. + For information on using a Software Development Kit (SDK), see + the + <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-intro'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>: <itemizedlist> <listitem><para>Use a pre-built toolchain that contains the software stack itself. @@ -106,12 +109,9 @@ isolated applications.</para></listitem> <listitem><para>When possible, use the Yocto Project plug-in for the <trademark class='trade'>Eclipse</trademark> IDE - and other pieces of Application Development - Technology (ADT). + and SDK development practices. For more information, see the - "<link linkend='application-development-workflow'>Application - Development Workflow</link>" section as well as the - <ulink url='&YOCTO_DOCS_ADT_URL;'>Yocto Project Application Developer's Guide</ulink>. + "<ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>". </para></listitem> <listitem><para>Keep your cross-development toolchains updated. @@ -603,7 +603,7 @@ the <link linkend='build-directory'>Build Directory</link> contains user-defined variables that affect every build. - The <filename>meta-yocto/conf/distro/poky.conf</filename> + The <filename>meta-poky/conf/distro/poky.conf</filename> configuration file defines Yocto "distro" configuration variables used only when building with this policy. Machine configuration files, which @@ -636,8 +636,6 @@ <listitem><para>A relocatable toolchain used outside of BitBake by developers when developing applications that will run on a targeted device. - Sometimes this relocatable cross-development - toolchain is referred to as the meta-toolchain. </para></listitem> </itemizedlist> </para> @@ -650,8 +648,7 @@ section in the Yocto Project Reference Manual. You can also find more information on using the relocatable toolchain in the - <ulink url='&YOCTO_DOCS_ADT_URL;'>Yocto Project - Application Developer's Guide</ulink>. + <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>. </para></listitem> <listitem><para><emphasis>Image:</emphasis> An image is an artifact of the BitBake build process given @@ -667,10 +664,6 @@ "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>" section in the Yocto Project Board Support Packages (BSP) Developer's Guide.</para></listitem> - <listitem><para id='meta-toolchain'><emphasis>Meta-Toolchain:</emphasis> - A term sometimes used for - <link linkend='cross-development-toolchain'>Cross-Development Toolchain</link>. - </para></listitem> <listitem><para id='metadata'><emphasis>Metadata:</emphasis> The files that BitBake parses when building an image. In general, Metadata includes recipes, classes, and @@ -983,7 +976,7 @@ Git uses "branches" to organize different development efforts. For example, the <filename>poky</filename> repository has several branches that include the current - <filename>&DISTRO_NAME;</filename> branch, the + <filename>&DISTRO_NAME_NO_CAP;</filename> branch, the <filename>master</filename> branch, and many branches for past Yocto Project releases. You can see all the branches by going to @@ -1015,14 +1008,14 @@ $ cd ~ $ git clone git://git.yoctoproject.org/poky $ cd poky - $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME; + $ git checkout -b &DISTRO_NAME_NO_CAP; origin/&DISTRO_NAME_NO_CAP; </literallayout> In this example, the name of the top-level directory of your local <link linkend='source-directory'>Source Directory</link> is "poky" and the name of that local working area (local branch) - you just created and checked out is "&DISTRO_NAME;". + you just created and checked out is "&DISTRO_NAME_NO_CAP;". The files in your local repository now reflect the same files that - are in the "&DISTRO_NAME;" development branch of the + are in the "&DISTRO_NAME_NO_CAP;" development branch of the Yocto Project's "poky" upstream repository. It is important to understand that when you create and checkout a local working branch based on a branch name, @@ -1030,7 +1023,7 @@ at the time you created your local branch, which could be different from the files at the time of a similarly named release. In other words, creating and checking out a local branch based on - the "&DISTRO_NAME;" branch name is not the same as + the "&DISTRO_NAME_NO_CAP;" branch name is not the same as cloning and checking out the "master" branch. Keep reading to see how you create a local snapshot of a Yocto Project Release. @@ -1049,10 +1042,11 @@ </para> <para> - Some key tags are <filename>dylan-9.0.4</filename>, - <filename>dora-10.0.4</filename>, <filename>daisy-11.0.2</filename>, - <filename>dizzy-12.0.0</filename>, and - <filename>&DISTRO_NAME;-&POKYVERSION;</filename>. + Some key tags are + <filename>dizzy-12.0.0</filename>, + <filename>fido-13.0.0</filename>, + <filename>jethro-14.0.0</filename>, and + <filename>&DISTRO_NAME_NO_CAP;-&POKYVERSION;</filename>. These tags represent Yocto Project releases. </para> @@ -1070,14 +1064,14 @@ $ cd ~ $ git clone git://git.yoctoproject.org/poky $ cd poky - $ git checkout -b my-&DISTRO_NAME;-&POKYVERSION; &DISTRO_NAME;-&POKYVERSION; + $ git checkout -b my-&DISTRO_NAME_NO_CAP;-&POKYVERSION; &DISTRO_NAME_NO_CAP;-&POKYVERSION; </literallayout> In this example, the name of the top-level directory of your local Yocto Project Files Git repository is <filename>poky</filename>. And, the name of the local branch you have created and checked out is - <filename>my-&DISTRO_NAME;-&POKYVERSION;</filename>. + <filename>my-&DISTRO_NAME_NO_CAP;-&POKYVERSION;</filename>. The files in your repository now exactly match the Yocto Project &DISTRO; - Release tag (<filename>&DISTRO_NAME;-&POKYVERSION;</filename>). + Release tag (<filename>&DISTRO_NAME_NO_CAP;-&POKYVERSION;</filename>). It is important to understand that when you create and checkout a local working branch based on a tag, your environment matches a specific point in time and not the entire development branch. @@ -1131,20 +1125,20 @@ into the project’s upstream (or master) repository.</para></listitem> <listitem><para><emphasis><filename>git status</filename>:</emphasis> Reports any modified files that possibly need to be staged and committed.</para></listitem> - <listitem><para><emphasis><filename>git checkout <branch-name></filename>:</emphasis> Changes + <listitem><para><emphasis><filename>git checkout</filename> <replaceable>branch-name</replaceable>:</emphasis> Changes your working branch. This command is analogous to "cd".</para></listitem> - <listitem><para><emphasis><filename>git checkout –b <working-branch></filename>:</emphasis> Creates + <listitem><para><emphasis><filename>git checkout –b</filename> <replaceable>working-branch</replaceable>:</emphasis> Creates a working branch on your local machine where you can isolate work. It is a good idea to use local branches when adding specific features or changes. This way if you do not like what you have done you can easily get rid of the work.</para></listitem> <listitem><para><emphasis><filename>git branch</filename>:</emphasis> Reports existing local branches and tells you the branch in which you are currently working.</para></listitem> - <listitem><para><emphasis><filename>git branch -D <branch-name></filename>:</emphasis> + <listitem><para><emphasis><filename>git branch -D</filename> <replaceable>branch-name</replaceable>:</emphasis> Deletes an existing local branch. You need to be in a local branch other than the one you are deleting - in order to delete <filename><branch-name></filename>.</para></listitem> + in order to delete <replaceable>branch-name</replaceable>.</para></listitem> <listitem><para><emphasis><filename>git pull</filename>:</emphasis> Retrieves information from an upstream Git repository and places it in your local Git repository. @@ -1410,7 +1404,7 @@ Examine the <filename>maintainers.inc</filename> file, which is located in the <link linkend='source-directory'>Source Directory</link> - at <filename>meta-yocto/conf/distro/include</filename>, to + at <filename>meta-poky/conf/distro/include</filename>, to see who is responsible for code. </para></listitem> <listitem><para><emphasis>Board Support Package (BSP) README Files:</emphasis> @@ -1454,7 +1448,7 @@ <listitem><para>For changes to BitBake (anything under the <filename>bitbake</filename> directory), send your patch to the <ulink url='&OE_LISTS_URL;/listinfo/bitbake-devel'>bitbake-devel</ulink> mailing list.</para></listitem> - <listitem><para>For changes to <filename>meta-yocto</filename>, send your patch to the + <listitem><para>For changes to <filename>meta-poky</filename>, send your patch to the <ulink url='&YOCTO_LISTS_URL;/listinfo/poky'>poky</ulink> mailing list.</para></listitem> <listitem><para>For changes to other layers hosted on <filename>yoctoproject.org</filename> (unless the diff --git a/yocto-poky/documentation/dev-manual/dev-manual-qemu.xml b/yocto-poky/documentation/dev-manual/dev-manual-qemu.xml index 903028f5c..41c18298a 100644 --- a/yocto-poky/documentation/dev-manual/dev-manual-qemu.xml +++ b/yocto-poky/documentation/dev-manual/dev-manual-qemu.xml @@ -47,11 +47,10 @@ <para> QEMU is made available with the Yocto Project a number of ways. - The easiest and recommended method for getting QEMU is to run the - ADT installer. For more information on how to make sure you have + One method is to install a Software Development Kit (SDK). + For more information on how to make sure you have QEMU available, see the - "<ulink url='&YOCTO_DOCS_ADT_URL;#the-qemu-emulator'>The QEMU Emulator</ulink>" - section in the Yocto Project Application Developer's Guide. + <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-intro'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>. </para> </section> diff --git a/yocto-poky/documentation/dev-manual/dev-manual-start.xml b/yocto-poky/documentation/dev-manual/dev-manual-start.xml index db989b7bf..23bf8eb0e 100644 --- a/yocto-poky/documentation/dev-manual/dev-manual-start.xml +++ b/yocto-poky/documentation/dev-manual/dev-manual-start.xml @@ -221,10 +221,8 @@ </literallayout> where <replaceable>bsp_name</replaceable> is the recognized BSP name. - Here are some examples: + Here is an example: <literallayout class='monospaced'> - meta-crownbay - meta-emenlow meta-raspberrypi </literallayout> See the @@ -263,11 +261,12 @@ $ cd ~/poky $ git clone git://git.yoctoproject.org/meta-intel.git Cloning into 'meta-intel'... - remote: Counting objects: 8844, done. - remote: Compressing objects: 100% (2864/2864), done. - remote: Total 8844 (delta 4931), reused 8780 (delta 4867) - Receiving objects: 100% (8844/8844), 2.48 MiB | 264 KiB/s, done. - Resolving deltas: 100% (4931/4931), done. + remote: Counting objects: 11917, done. + remote: Compressing objects: 100% (3842/3842), done. + remote: Total 11917 (delta 6840), reused 11699 (delta 6622) + Receiving objects: 100% (11917/11917), 2.92 MiB | 2.88 MiB/s, done. + Resolving deltas: 100% (6840/6840), done. + Checking connectivity... done. </literallayout></para> <para>The same @@ -279,8 +278,9 @@ applications using the Eclipse Integrated Development Environment (IDE), you will need this plug-in. See the - "<link linkend='setting-up-the-eclipse-ide'>Setting up the Eclipse IDE</link>" - section for more information.</para></listitem> + "<ulink url='&YOCTO_DOCS_SDK_URL;#setting-up-the-eclipse-ide'>Setting up the Eclipse IDE</ulink>" + section in the Yocto Project Software Development Kit (SDK) + Developer's Guide for more information.</para></listitem> </itemizedlist> </para> </section> @@ -341,14 +341,17 @@ </para> <para> - Using a pre-built binary is ideal for developing software applications to run on your - target hardware. - To do this, you need to be able to access the appropriate cross-toolchain tarball for - the architecture on which you are developing. - If you are using an SDK type image, the image ships with the complete toolchain native to - the architecture. - If you are not using an SDK type image, you need to separately download and - install the stand-alone Yocto Project cross-toolchain tarball. + Using a pre-built binary is ideal for developing software + applications to run on your target hardware. + To do this, you need to be able to access the appropriate + cross-toolchain tarball for the architecture on which you are + developing. + If you are using an SDK type image, the image ships with the complete + toolchain native to the architecture (i.e. a toolchain designed to + run on the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>). + If you are not using an SDK type image, you need to separately download + and install the stand-alone Yocto Project cross-toolchain tarball. </para> <para> @@ -363,8 +366,7 @@ by sourcing an environment setup script. Finally, you start the QEMU emulator. You can find details on all these steps in the - "<ulink url='&YOCTO_DOCS_QS_URL;#using-pre-built'>Example Using Pre-Built Binaries and QEMU</ulink>" - section of the Yocto Project Application Developer's Guide. + <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-manual'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>. You can learn more about using QEMU with the Yocto Project in the "<link linkend='dev-manual-qemu'>Using the Quick EMUlator (QEMU)</link>" section. diff --git a/yocto-poky/documentation/dev-manual/dev-manual.xml b/yocto-poky/documentation/dev-manual/dev-manual.xml index 3ddd01fde..791a8cb6a 100644 --- a/yocto-poky/documentation/dev-manual/dev-manual.xml +++ b/yocto-poky/documentation/dev-manual/dev-manual.xml @@ -81,6 +81,11 @@ <date>October 2015</date> <revremark>Released with the Yocto Project 2.0 Release.</revremark> </revision> + <revision> + <revnumber>2.1</revnumber> + <date>April 2016</date> + <revremark>Released with the Yocto Project 2.1 Release.</revremark> + </revision> </revhistory> <copyright> diff --git a/yocto-poky/documentation/dev-manual/dev-style.css b/yocto-poky/documentation/dev-manual/dev-style.css index b900ffc9b..6d0aa8e9f 100644 --- a/yocto-poky/documentation/dev-manual/dev-style.css +++ b/yocto-poky/documentation/dev-manual/dev-style.css @@ -730,6 +730,10 @@ div.navfooter { border-color: black; } +.writernotes { + color: red; +} + /*********** / / graphics / diff --git a/yocto-poky/documentation/dev-manual/figures/app-dev-flow.png b/yocto-poky/documentation/dev-manual/figures/app-dev-flow.png Binary files differdeleted file mode 100644 index ec93374ee..000000000 --- a/yocto-poky/documentation/dev-manual/figures/app-dev-flow.png +++ /dev/null diff --git a/yocto-poky/documentation/dev-manual/figures/build-workspace-directory.png b/yocto-poky/documentation/dev-manual/figures/build-workspace-directory.png Binary files differindex f561f8fee..5387d33f0 100644 --- a/yocto-poky/documentation/dev-manual/figures/build-workspace-directory.png +++ b/yocto-poky/documentation/dev-manual/figures/build-workspace-directory.png diff --git a/yocto-poky/documentation/dev-manual/figures/devtool-add-flow.png b/yocto-poky/documentation/dev-manual/figures/devtool-add-flow.png Binary files differnew file mode 100644 index 000000000..c09e60e35 --- /dev/null +++ b/yocto-poky/documentation/dev-manual/figures/devtool-add-flow.png diff --git a/yocto-poky/documentation/dev-manual/figures/devtool-modify-flow.png b/yocto-poky/documentation/dev-manual/figures/devtool-modify-flow.png Binary files differnew file mode 100644 index 000000000..cd7f4d05b --- /dev/null +++ b/yocto-poky/documentation/dev-manual/figures/devtool-modify-flow.png diff --git a/yocto-poky/documentation/dev-manual/figures/devtool-upgrade-flow.png b/yocto-poky/documentation/dev-manual/figures/devtool-upgrade-flow.png Binary files differnew file mode 100644 index 000000000..d25168c84 --- /dev/null +++ b/yocto-poky/documentation/dev-manual/figures/devtool-upgrade-flow.png diff --git a/yocto-poky/documentation/kernel-dev/kernel-dev-advanced.xml b/yocto-poky/documentation/kernel-dev/kernel-dev-advanced.xml index 4fdb853f9..9e15f178a 100644 --- a/yocto-poky/documentation/kernel-dev/kernel-dev-advanced.xml +++ b/yocto-poky/documentation/kernel-dev/kernel-dev-advanced.xml @@ -29,8 +29,8 @@ source Git repositories. This Metadata defines Board Support Packages (BSPs) that correspond to definitions in linux-yocto recipes for the same BSPs. - A BSP consists of an aggregation of kernel policy and hardware-specific - feature enablements. + A BSP consists of an aggregation of kernel policy and enabled + hardware-specific features. The BSP can be influenced from within the linux-yocto recipe. <note> Linux kernel source that contains kernel Metadata is said to be @@ -171,8 +171,8 @@ <title>Kernel Metadata Location</title> <para> - Kernel Metadata can be defined in either the kernel recipe - (recipe-space) or in the kernel tree (in-tree). + Kernel Metadata always exists outside of the kernel tree either + defined in a kernel recipe (recipe-space) or outside of the recipe. Where you choose to define the Metadata depends on what you want to do and how you intend to work. Regardless of where you define the kernel Metadata, the syntax used @@ -195,10 +195,10 @@ <para> Conversely, if you are actively developing a kernel and are already maintaining a Linux kernel Git repository of your own, you might find - it more convenient to work with the kernel Metadata in the same - repository as the Linux kernel sources. - This method can make iterative development of the Linux kernel - more efficient outside of the BitBake environment. + it more convenient to work with kernel Metadata kept outside the + recipe-space. + Working with Metadata in this area can make iterative development of + the Linux kernel more efficient outside of the BitBake environment. </para> <section id='recipe-space-metadata'> @@ -249,38 +249,52 @@ </para> </section> - <section id='in-tree-metadata'> - <title>In-Tree Metadata</title> + <section id='metadata-outside-the-recipe-space'> + <title>Metadata Outside the Recipe-Space</title> <para> - When stored in-tree, the kernel Metadata files reside in the - <filename>meta</filename> directory of the Linux kernel sources. - The <filename>meta</filename> directory can be present in the - same repository branch as the sources, - such as "master", or <filename>meta</filename> can be its own - orphan branch. - <note> - An orphan branch in Git is a branch with unique history and - content to the other branches in the repository. - Orphan branches are useful to track Metadata changes - independently from the sources of the Linux kernel, while - still keeping them together in the same repository. - </note> - For the purposes of this document, we will discuss all - in-tree Metadata as residing below the - <filename>meta/cfg/kernel-cache</filename> directory. + When stored outside of the recipe-space, the kernel Metadata + files reside in a separate repository. + The OpenEmbedded build system adds the Metadata to the build as + a "ktype=meta" repository through the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + variable. + As an example, consider the following <filename>SRC_URI</filename> + statement from the <filename>linux-yocto_4.4.bb</filename> + kernel recipe: + <literallayout class='monospaced'> + SRC_URI = "git://git.yoctoproject.org/linux-yocto-4.4.git;name=machine;branch=${KBRANCH}; \ + git://git.yoctoproject.org/yocto-kernel-cache;type=kmeta;name=meta;branch=yocto-4.4;destsuffix=${KMETA}" + </literallayout> + <filename>${KMETA}</filename>, in this context, is simply used to + name the directory into which the Git fetcher places the Metadata. + This behavior is no different than any multi-repository + <filename>SRC_URI</filename> statement used in a recipe. </para> <para> + You can keep kernel Metadata in a "kernel-cache", which is a + directory containing configuration fragments. + As with any Metadata kept outside the recipe-space, you simply + need to use the <filename>SRC_URI</filename> statement with the + "type=kmeta" attribute. + Doing so makes the kernel Metadata available during the + configuration phase. + </para> + +<!-- + + + <para> Following is an example that shows how a trivial tree of Metadata is stored in a custom Linux kernel Git repository: <literallayout class='monospaced'> meta/ - `-- cfg - `-- kernel-cache - |-- bsp-standard.scc - |-- bsp.cfg - `-- standard.cfg + `‐‐ cfg + `‐‐ kernel-cache + |‐‐ bsp-standard.scc + |‐‐ bsp.cfg + `‐‐ standard.cfg </literallayout> </para> @@ -301,16 +315,15 @@ orphan <filename>meta</filename> branch, use these commands from within your Linux kernel Git repository: <literallayout class='monospaced'> - $ git checkout --orphan meta + $ git checkout ‐‐orphan meta $ git rm -rf . - $ git commit --allow-empty -m "Create orphan meta branch" + $ git commit ‐‐allow-empty -m "Create orphan meta branch" </literallayout> </para> +--> <para> - If you modify the Metadata in the linux-yocto - <filename>meta</filename> branch, you must not forget to update - the + If you modify the Metadata, you must not forget to update the <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink> statements in the kernel's recipe. In particular, you need to update the @@ -437,7 +450,7 @@ if you are creating Metadata in <link linkend='recipe-space-metadata'>recipe-space</link>, or <filename>meta/cfg/kernel-cache/</filename> if you are creating - Metadata <link linkend='in-tree-metadata'>in-tree</link>. + <link linkend='metadata-outside-the-recipe-space'>Metadata outside of the recipe-space</link>. </para> <section id='configuration'> diff --git a/yocto-poky/documentation/kernel-dev/kernel-dev-common.xml b/yocto-poky/documentation/kernel-dev/kernel-dev-common.xml index ab7f80fbe..261471c46 100644 --- a/yocto-poky/documentation/kernel-dev/kernel-dev-common.xml +++ b/yocto-poky/documentation/kernel-dev/kernel-dev-common.xml @@ -270,11 +270,12 @@ edit the recipe that builds your kernel so that it has the following command form: <literallayout class='monospaced'> - KBUILD_DEFCONFIG_<ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'>KMACHINE</ulink> ?= <replaceable>defconfig_file</replaceable> + KBUILD_DEFCONFIG_KMACHINE ?= <replaceable>defconfig_file</replaceable> </literallayout> You need to append the variable with - <filename>KMACHINE</filename> and then supply the path to - your "in-tree" <filename>defconfig</filename> file. + <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink> + and then supply the path to your "in-tree" + <filename>defconfig</filename> file. </para> <para> @@ -1031,6 +1032,127 @@ </para> </section> </section> + + <section id='adding-recipe-space-kernel-features'> + <title>Adding Recipe-Space Kernel Features</title> + + <para> + You can add kernel features in the + <link linkend='recipe-space-metadata'>recipe-space</link> by + using the + <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink> + variable and by specifying the feature's <filename>.scc</filename> + file path in the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + statement. + When you add features using this method, the OpenEmbedded build + system checks to be sure the features are present. + If the features are not present, the build stops. + Kernel features are the last elements processed for configuring + and patching the kernel. + Therefore, adding features in this manner is a way + to enforce specific features are present and enabled + without needing to do a full audit of any other layer's additions + to the <filename>SRC_URI</filename> statement. + </para> + + <para> + You add a kernel feature by providing the feature as part of the + <filename>KERNEL_FEATURES</filename> variable and by providing the + path to the feature's <filename>.scc</filename> file, which is + relative to the root of the kernel Metadata. + The OpenEmbedded build system searches all forms of kernel + Metadata on the <filename>SRC_URI</filename> statement regardless + of whether the Metadata is in the "kernel-cache", system kernel + Metadata, or a recipe-space Metadata. + See the + "<link linkend='kernel-metadata-location'>Kernel Metadata Location</link>" + section for additional information. + </para> + + <para> + When you specify the feature's <filename>.scc</filename> file + on the <filename>SRC_URI</filename> statement, the OpenEmbedded + build system adds the directory of that + <filename>.scc</filename> file along with all its subdirectories + to the kernel feature search path. + Because subdirectories are searched, you can reference a single + <filename>.scc</filename> file in the + <filename>SRC_URI</filename> statement to reference multiple kernel + features. + </para> + + <para> + Consider the following example that adds the "test.scc" feature + to the build. + <orderedlist> + <listitem><para> + Create a <filename>.scc</filename> file and locate it + just as you would any other patch file, + <filename>.cfg</filename> file, or fetcher item + you specify in the <filename>SRC_URI</filename> + statement. + <note><title>Notes</title> + <itemizedlist> + <listitem><para> + You must add the directory of the + <filename>.scc</filename> file to the fetcher's + search path in the same manner as you would + add a <filename>.patch</filename> file. + </para></listitem> + <listitem><para> + You can create additional + <filename>.scc</filename> files beneath the + directory that contains the file you are + adding. + All subdirectories are searched during the + build as potential feature directories. + </para></listitem> + </itemizedlist> + </note> + Continuing with the example, suppose the "test.scc" + feature you are adding has a + <filename>test.scc</filename> file in the following + directory: + <literallayout class='monospaced'> + <replaceable>my_recipe</replaceable> + | + +-linux-yocto + | + +-test.cfg + +-test.scc + </literallayout> + In this example, the <filename>linux-yocto</filename> + directory has both the feature + <filename>test.scc</filename> file and a similarly + named configuration fragment file + <filename>test.cfg</filename>. + </para></listitem> + <listitem><para> + Add the <filename>.scc</filename> file to the + recipe's <filename>SRC_URI</filename> statement: + <literallayout class='monospaced'> + SRC_URI_append = " file://test.scc" + </literallayout> + The leading space before the path is important as the + path is appended to the existing path. + </para></listitem> + <listitem><para> + Specify the feature as a kernel feature: + <literallayout class='monospaced'> + KERNEL_FEATURES_append = " test.scc" + </literallayout> + The OpenEmbedded build system processes the kernel feature + when it builds the kernel. + <note> + If other features are contained below "test.scc", + then their directories are relative to the directory + containing the <filename>test.scc</filename> file. + </note> + </para></listitem> + </orderedlist> + </para> + </section> </chapter> <!-- vim: expandtab tw=80 ts=4 diff --git a/yocto-poky/documentation/kernel-dev/kernel-dev.xml b/yocto-poky/documentation/kernel-dev/kernel-dev.xml index 38850fa3c..fb11dd15c 100644 --- a/yocto-poky/documentation/kernel-dev/kernel-dev.xml +++ b/yocto-poky/documentation/kernel-dev/kernel-dev.xml @@ -66,6 +66,11 @@ <date>October 2015</date> <revremark>Released with the Yocto Project 2.0 Release.</revremark> </revision> + <revision> + <revnumber>2.1</revnumber> + <date>April 2016</date> + <revremark>Released with the Yocto Project 2.1 Release.</revremark> + </revision> </revhistory> <copyright> diff --git a/yocto-poky/documentation/mega-manual/figures/adt-title.png b/yocto-poky/documentation/mega-manual/figures/adt-title.png Binary files differdeleted file mode 100644 index 6e71e41f1..000000000 --- a/yocto-poky/documentation/mega-manual/figures/adt-title.png +++ /dev/null diff --git a/yocto-poky/documentation/mega-manual/figures/app-dev-flow.png b/yocto-poky/documentation/mega-manual/figures/app-dev-flow.png Binary files differdeleted file mode 100644 index 4927b93d6..000000000 --- a/yocto-poky/documentation/mega-manual/figures/app-dev-flow.png +++ /dev/null diff --git a/yocto-poky/documentation/mega-manual/figures/build-workspace-directory.png b/yocto-poky/documentation/mega-manual/figures/build-workspace-directory.png Binary files differindex f561f8fee..5387d33f0 100644 --- a/yocto-poky/documentation/mega-manual/figures/build-workspace-directory.png +++ b/yocto-poky/documentation/mega-manual/figures/build-workspace-directory.png diff --git a/yocto-poky/documentation/mega-manual/figures/compatible-layers.png b/yocto-poky/documentation/mega-manual/figures/compatible-layers.png Binary files differnew file mode 100644 index 000000000..38436b075 --- /dev/null +++ b/yocto-poky/documentation/mega-manual/figures/compatible-layers.png diff --git a/yocto-poky/documentation/mega-manual/figures/devtool-add-flow.png b/yocto-poky/documentation/mega-manual/figures/devtool-add-flow.png Binary files differnew file mode 100644 index 000000000..c09e60e35 --- /dev/null +++ b/yocto-poky/documentation/mega-manual/figures/devtool-add-flow.png diff --git a/yocto-poky/documentation/mega-manual/figures/devtool-modify-flow.png b/yocto-poky/documentation/mega-manual/figures/devtool-modify-flow.png Binary files differnew file mode 100644 index 000000000..cd7f4d05b --- /dev/null +++ b/yocto-poky/documentation/mega-manual/figures/devtool-modify-flow.png diff --git a/yocto-poky/documentation/mega-manual/figures/devtool-upgrade-flow.png b/yocto-poky/documentation/mega-manual/figures/devtool-upgrade-flow.png Binary files differnew file mode 100644 index 000000000..d25168c84 --- /dev/null +++ b/yocto-poky/documentation/mega-manual/figures/devtool-upgrade-flow.png diff --git a/yocto-poky/documentation/mega-manual/figures/image-generation.png b/yocto-poky/documentation/mega-manual/figures/image-generation.png Binary files differindex ab962580c..71a48dc6f 100644 --- a/yocto-poky/documentation/mega-manual/figures/image-generation.png +++ b/yocto-poky/documentation/mega-manual/figures/image-generation.png diff --git a/yocto-poky/documentation/mega-manual/figures/import-layer.png b/yocto-poky/documentation/mega-manual/figures/import-layer.png Binary files differnew file mode 100644 index 000000000..436ec7af4 --- /dev/null +++ b/yocto-poky/documentation/mega-manual/figures/import-layer.png diff --git a/yocto-poky/documentation/mega-manual/figures/new-project.png b/yocto-poky/documentation/mega-manual/figures/new-project.png Binary files differnew file mode 100644 index 000000000..dbc50b991 --- /dev/null +++ b/yocto-poky/documentation/mega-manual/figures/new-project.png diff --git a/yocto-poky/documentation/mega-manual/figures/sdk-devtool-add-flow.png b/yocto-poky/documentation/mega-manual/figures/sdk-devtool-add-flow.png Binary files differnew file mode 100644 index 000000000..c09e60e35 --- /dev/null +++ b/yocto-poky/documentation/mega-manual/figures/sdk-devtool-add-flow.png diff --git a/yocto-poky/documentation/mega-manual/figures/sdk-devtool-modify-flow.png b/yocto-poky/documentation/mega-manual/figures/sdk-devtool-modify-flow.png Binary files differnew file mode 100644 index 000000000..cd06c0181 --- /dev/null +++ b/yocto-poky/documentation/mega-manual/figures/sdk-devtool-modify-flow.png diff --git a/yocto-poky/documentation/mega-manual/figures/sdk-eclipse-dev-flow.png b/yocto-poky/documentation/mega-manual/figures/sdk-eclipse-dev-flow.png Binary files differnew file mode 100644 index 000000000..9f986e0d4 --- /dev/null +++ b/yocto-poky/documentation/mega-manual/figures/sdk-eclipse-dev-flow.png diff --git a/yocto-poky/documentation/mega-manual/figures/sdk-environment.png b/yocto-poky/documentation/mega-manual/figures/sdk-environment.png Binary files differnew file mode 100644 index 000000000..78b8cad39 --- /dev/null +++ b/yocto-poky/documentation/mega-manual/figures/sdk-environment.png diff --git a/yocto-poky/documentation/mega-manual/figures/sdk-generation.png b/yocto-poky/documentation/mega-manual/figures/sdk-generation.png Binary files differindex c37e2748c..adbe1f4ac 100644..100755 --- a/yocto-poky/documentation/mega-manual/figures/sdk-generation.png +++ b/yocto-poky/documentation/mega-manual/figures/sdk-generation.png diff --git a/yocto-poky/documentation/mega-manual/figures/sdk-installed-extensible-sdk-directory.png b/yocto-poky/documentation/mega-manual/figures/sdk-installed-extensible-sdk-directory.png Binary files differnew file mode 100644 index 000000000..99e07ce6f --- /dev/null +++ b/yocto-poky/documentation/mega-manual/figures/sdk-installed-extensible-sdk-directory.png diff --git a/yocto-poky/documentation/mega-manual/figures/sdk-installed-standard-sdk-directory.png b/yocto-poky/documentation/mega-manual/figures/sdk-installed-standard-sdk-directory.png Binary files differnew file mode 100644 index 000000000..d4af85020 --- /dev/null +++ b/yocto-poky/documentation/mega-manual/figures/sdk-installed-standard-sdk-directory.png diff --git a/yocto-poky/documentation/mega-manual/figures/sdk-title.png b/yocto-poky/documentation/mega-manual/figures/sdk-title.png Binary files differnew file mode 100644 index 000000000..e9d5b346b --- /dev/null +++ b/yocto-poky/documentation/mega-manual/figures/sdk-title.png diff --git a/yocto-poky/documentation/mega-manual/figures/sdk.png b/yocto-poky/documentation/mega-manual/figures/sdk.png Binary files differindex a539cc52f..5c36b7548 100644 --- a/yocto-poky/documentation/mega-manual/figures/sdk.png +++ b/yocto-poky/documentation/mega-manual/figures/sdk.png diff --git a/yocto-poky/documentation/mega-manual/figures/user-configuration.png b/yocto-poky/documentation/mega-manual/figures/user-configuration.png Binary files differindex f2b3f8e7f..c298401fc 100644..100755 --- a/yocto-poky/documentation/mega-manual/figures/user-configuration.png +++ b/yocto-poky/documentation/mega-manual/figures/user-configuration.png diff --git a/yocto-poky/documentation/mega-manual/mega-manual.xml b/yocto-poky/documentation/mega-manual/mega-manual.xml index 5c1faec7a..154e369ab 100644 --- a/yocto-poky/documentation/mega-manual/mega-manual.xml +++ b/yocto-poky/documentation/mega-manual/mega-manual.xml @@ -50,6 +50,11 @@ <date>October 2015</date> <revremark>Released with the Yocto Project 2.0 Release.</revremark> </revision> + <revision> + <revnumber>2.1</revnumber> + <date>April 2016</date> + <revremark>Released with the Yocto Project 2.1 Release.</revremark> + </revision> </revhistory> <copyright> @@ -97,22 +102,22 @@ <xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../dev-manual/dev-manual-qemu.xml"/> -<!-- Includes adt-manual title image and then adt-manual chapters --> +<!-- Includes sdk-manual title image and then sdk-manual chapters --> <para> - <imagedata fileref="figures/adt-title.png" width="100%" align="left" scalefit="1" /> + <imagedata fileref="figures/sdk-title.png" width="100%" align="left" scalefit="1" /> </para> <xi:include - xmlns:xi="http://www.w3.org/2003/XInclude" href="../adt-manual/adt-manual-intro.xml"/> + 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="../adt-manual/adt-intro.xml"/> + 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="../adt-manual/adt-prepare.xml"/> + 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="../adt-manual/adt-package.xml"/> + 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="../adt-manual/adt-command.xml"/> + xmlns:xi="http://www.w3.org/2003/XInclude" href="../sdk-manual/sdk-appendix-customizing.xml"/> <!-- Includes bsp-guide title image and then bsp-guide chapters --> diff --git a/yocto-poky/documentation/poky.ent b/yocto-poky/documentation/poky.ent index 33d52c04b..673ab23c9 100644 --- a/yocto-poky/documentation/poky.ent +++ b/yocto-poky/documentation/poky.ent @@ -1,11 +1,12 @@ -<!ENTITY DISTRO "2.0"> -<!ENTITY DISTRO_COMPRESSED "20"> -<!ENTITY DISTRO_NAME "jethro"> -<!ENTITY YOCTO_DOC_VERSION "2.0"> -<!ENTITY POKYVERSION "14.0.0"> -<!ENTITY POKYVERSION_COMPRESSED "1400"> -<!ENTITY YOCTO_POKY "poky-&DISTRO_NAME;-&POKYVERSION;"> -<!ENTITY COPYRIGHT_YEAR "2010-2015"> +<!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 YOCTO_POKY "poky-&DISTRO_NAME_NO_CAP;-&POKYVERSION;"> +<!ENTITY COPYRIGHT_YEAR "2010-2016"> <!ENTITY YOCTO_DL_URL "http://downloads.yoctoproject.org"> <!ENTITY YOCTO_HOME_URL "http://www.yoctoproject.org"> <!ENTITY YOCTO_LISTS_URL "http://lists.yoctoproject.org"> @@ -14,7 +15,7 @@ <!ENTITY YOCTO_AB_URL "http://autobuilder.yoctoproject.org"> <!ENTITY YOCTO_GIT_URL "http://git.yoctoproject.org"> <!ENTITY YOCTO_ADTREPO_URL "http://adtrepo.yoctoproject.org"> -<!ENTITY YOCTO_RELEASE_NOTES "&YOCTO_HOME_URL;/downloads/core/&DISTRO_NAME;&DISTRO_COMPRESSED;"> +<!ENTITY YOCTO_RELEASE_NOTES "&YOCTO_HOME_URL;/downloads/core/&DISTRO_NAME_NO_CAP;&DISTRO_COMPRESSED;"> <!ENTITY OE_HOME_URL "http://www.openembedded.org"> <!ENTITY OE_LISTS_URL "http://lists.openembedded.org/mailman"> <!ENTITY OE_DOCS_URL "http://docs.openembedded.org"> @@ -54,6 +55,7 @@ <!ENTITY YOCTO_DOCS_MM_URL "&YOCTO_DOCS_URL;/&YOCTO_DOC_VERSION;/mega-manual/mega-manual.html"> <!ENTITY YOCTO_DOCS_BB_URL "&YOCTO_DOCS_URL;/&YOCTO_DOC_VERSION;/bitbake-user-manual/bitbake-user-manual.html"> <!ENTITY YOCTO_DOCS_TOAST_URL "&YOCTO_DOCS_URL;/&YOCTO_DOC_VERSION;/toaster-manual/toaster-manual.html"> +<!ENTITY YOCTO_DOCS_SDK_URL "&YOCTO_DOCS_URL;/&YOCTO_DOC_VERSION;/sdk-manual/sdk-manual.html"> <!ENTITY YOCTO_ADTPATH_DIR "/opt/poky/&DISTRO;"> <!ENTITY YOCTO_POKY_TARBALL "&YOCTO_POKY;.tar.bz2"> <!ENTITY OE_INIT_PATH "&YOCTO_POKY;/oe-init-build-env"> @@ -62,7 +64,7 @@ build-essential chrpath socat"> <!ENTITY FEDORA_HOST_PACKAGES_ESSENTIAL "gawk make wget tar bzip2 gzip python unzip perl patch \ diffutils diffstat git cpp gcc gcc-c++ glibc-devel texinfo chrpath \ - ccache perl-Data-Dumper perl-Text-ParseWords perl-Thread-Queue socat \ + ccache perl-Data-Dumper perl-Text-ParseWords perl-Thread-Queue perl-bignum socat \ findutils which"> <!ENTITY OPENSUSE_HOST_PACKAGES_ESSENTIAL "python gcc gcc-c++ git chrpath make wget python-xml \ diffstat makeinfo python-curses patch socat"> diff --git a/yocto-poky/documentation/profile-manual/profile-manual-usage.xml b/yocto-poky/documentation/profile-manual/profile-manual-usage.xml index 95ad73909..310e8f01c 100644 --- a/yocto-poky/documentation/profile-manual/profile-manual-usage.xml +++ b/yocto-poky/documentation/profile-manual/profile-manual-usage.xml @@ -2169,16 +2169,16 @@ ### Shell environment set up for builds. ### - You can now run 'bitbake <replaceable>target</replaceable>' + You can now run 'bitbake <target>' Common targets are: - core-image-minimal - core-image-sato - meta-toolchain - adt-installer - meta-ide-support + core-image-minimal + core-image-sato + meta-toolchain + meta-ide-support You can also run generated qemu images with a command like 'runqemu qemux86' + </literallayout> Once you've done that, you can cd to whatever directory contains your scripts and use 'crosstap' to run the script: @@ -2228,541 +2228,6 @@ </section> </section> -<section id='profile-manual-oprofile'> - <title>oprofile</title> - - <para> - oprofile itself is a command-line application that runs on the - target system. - </para> - - <section id='oprofile-setup'> - <title>Setup</title> - - <para> - For this section, we'll assume you've already performed the - basic setup outlined in the - "<link linkend='profile-manual-general-setup'>General Setup</link>" - section. - </para> - - <para> - For the section that deals with running oprofile from the command-line, - we assume you've ssh'ed to the host and will be running - oprofile on the target. - </para> - - <para> - oprofileui (oprofile-viewer) is a GUI-based program that runs - on the host and interacts remotely with the target. - See the oprofileui section for the exact steps needed to - install oprofileui on the host. - </para> - </section> - - <section id='oprofile-basic-usage'> - <title>Basic Usage</title> - - <para> - Oprofile as configured in Yocto is a system-wide profiler - (i.e. the version in Yocto doesn't yet make use of the - perf_events interface which would allow it to profile - specific processes and workloads). It relies on hardware - counter support in the hardware (but can fall back to a - timer-based mode), which means that it doesn't take - advantage of tracepoints or other event sources for example. - </para> - - <para> - It consists of a kernel module that collects samples and a - userspace daemon that writes the sample data to disk. - </para> - - <para> - The 'opcontrol' shell script is used for transparently - managing these components and starting and stopping - profiles, and the 'opreport' command is used to - display the results. - </para> - - <para> - The oprofile daemon should already be running, but before - you start profiling, you may need to change some settings - and some of these settings may require the daemon to not - be running. One of these settings is the path to the - vmlinux file, which you'll want to set using the --vmlinux - option if you want the kernel profiled: - <literallayout class='monospaced'> - root@crownbay:~# opcontrol --vmlinux=/boot/vmlinux-`uname -r` - The profiling daemon is currently active, so changes to the configuration - will be used the next time you restart oprofile after a --shutdown or --deinit. - </literallayout> - You can check if vmlinux file: is set using opcontrol --status: - <literallayout class='monospaced'> - root@crownbay:~# opcontrol --status - Daemon paused: pid 1334 - Separate options: library - vmlinux file: none - Image filter: none - Call-graph depth: 6 - </literallayout> - If it's not, you need to shutdown the daemon, add the setting - and restart the daemon: - <literallayout class='monospaced'> - root@crownbay:~# opcontrol --shutdown - Killing daemon. - - root@crownbay:~# opcontrol --vmlinux=/boot/vmlinux-`uname -r` - root@crownbay:~# opcontrol --start-daemon - Using default event: CPU_CLK_UNHALTED:100000:0:1:1 - Using 2.6+ OProfile kernel interface. - Reading module info. - Using log file /var/lib/oprofile/samples/oprofiled.log - Daemon started. - </literallayout> - If we check the status again we now see our updated settings: - <literallayout class='monospaced'> - root@crownbay:~# opcontrol --status - Daemon paused: pid 1649 - Separate options: library - vmlinux file: /boot/vmlinux-3.4.11-yocto-standard - Image filter: none - Call-graph depth: 6 - </literallayout> - We're now in a position to run a profile. For that we use - 'opcontrol --start': - <literallayout class='monospaced'> - root@crownbay:~# opcontrol --start - Profiler running. - </literallayout> - In another window, run our wget workload: - <literallayout class='monospaced'> - root@crownbay:~# rm linux-2.6.19.2.tar.bz2; wget <ulink url='http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2'>http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2</ulink>; sync - Connecting to downloads.yoctoproject.org (140.211.169.59:80) - linux-2.6.19.2.tar.b 100% |*******************************| 41727k 0:00:00 ETA - </literallayout> - To stop the profile we use 'opcontrol --shutdown', which not - only stops the profile but shuts down the daemon as well: - <literallayout class='monospaced'> - root@crownbay:~# opcontrol --shutdown - Stopping profiling. - Killing daemon. - </literallayout> - Oprofile writes sample data to /var/lib/oprofile/samples, - which you can look at if you're interested in seeing how the - samples are structured. This is also interesting because - it's related to how you dive down to get further details - about specific executables in OProfile. - </para> - - <para> - To see the default display output for a profile, simply type - 'opreport', which will show the results using the data in - /var/lib/oprofile/samples: - <literallayout class='monospaced'> - root@crownbay:~# opreport - - WARNING! The OProfile kernel driver reports sample buffer overflows. - Such overflows can result in incorrect sample attribution, invalid sample - files and other symptoms. See the oprofiled.log for details. - You should adjust your sampling frequency to eliminate (or at least minimize) - these overflows. - CPU: Intel Architectural Perfmon, speed 1.3e+06 MHz (estimated) - Counted CPU_CLK_UNHALTED events (Clock cycles when not halted) with a unit mask of 0x00 (No unit mask) count 100000 - CPU_CLK_UNHALT...| - samples| %| - ------------------ - 464365 79.8156 vmlinux-3.4.11-yocto-standard - 65108 11.1908 oprofiled - CPU_CLK_UNHALT...| - samples| %| - ------------------ - 64416 98.9372 oprofiled - 692 1.0628 libc-2.16.so - 36959 6.3526 no-vmlinux - 4378 0.7525 busybox - CPU_CLK_UNHALT...| - samples| %| - ------------------ - 2844 64.9612 libc-2.16.so - 1337 30.5391 busybox - 193 4.4084 ld-2.16.so - 2 0.0457 libnss_compat-2.16.so - 1 0.0228 libnsl-2.16.so - 1 0.0228 libnss_files-2.16.so - 4344 0.7467 bash - CPU_CLK_UNHALT...| - samples| %| - ------------------ - 2657 61.1648 bash - 1665 38.3287 libc-2.16.so - 18 0.4144 ld-2.16.so - 3 0.0691 libtinfo.so.5.9 - 1 0.0230 libdl-2.16.so - 3118 0.5359 nf_conntrack - 686 0.1179 matchbox-terminal - CPU_CLK_UNHALT...| - samples| %| - ------------------ - 214 31.1953 libglib-2.0.so.0.3200.4 - 114 16.6181 libc-2.16.so - 79 11.5160 libcairo.so.2.11200.2 - 78 11.3703 libgdk-x11-2.0.so.0.2400.8 - 51 7.4344 libpthread-2.16.so - 45 6.5598 libgobject-2.0.so.0.3200.4 - 29 4.2274 libvte.so.9.2800.2 - 25 3.6443 libX11.so.6.3.0 - 19 2.7697 libxcb.so.1.1.0 - 17 2.4781 libgtk-x11-2.0.so.0.2400.8 - 12 1.7493 librt-2.16.so - 3 0.4373 libXrender.so.1.3.0 - 671 0.1153 emgd - 411 0.0706 nf_conntrack_ipv4 - 391 0.0672 iptable_nat - 378 0.0650 nf_nat - 263 0.0452 Xorg - CPU_CLK_UNHALT...| - samples| %| - ------------------ - 106 40.3042 Xorg - 53 20.1521 libc-2.16.so - 31 11.7871 libpixman-1.so.0.27.2 - 26 9.8859 emgd_drv.so - 16 6.0837 libemgdsrv_um.so.1.5.15.3226 - 11 4.1825 libEMGD2d.so.1.5.15.3226 - 9 3.4221 libfb.so - 7 2.6616 libpthread-2.16.so - 1 0.3802 libudev.so.0.9.3 - 1 0.3802 libdrm.so.2.4.0 - 1 0.3802 libextmod.so - 1 0.3802 mouse_drv.so - . - . - . - 9 0.0015 connmand - CPU_CLK_UNHALT...| - samples| %| - ------------------ - 4 44.4444 libglib-2.0.so.0.3200.4 - 2 22.2222 libpthread-2.16.so - 1 11.1111 connmand - 1 11.1111 libc-2.16.so - 1 11.1111 librt-2.16.so - 6 0.0010 oprofile-server - CPU_CLK_UNHALT...| - samples| %| - ------------------ - 3 50.0000 libc-2.16.so - 1 16.6667 oprofile-server - 1 16.6667 libpthread-2.16.so - 1 16.6667 libglib-2.0.so.0.3200.4 - 5 8.6e-04 gconfd-2 - CPU_CLK_UNHALT...| - samples| %| - ------------------ - 2 40.0000 libdbus-1.so.3.7.2 - 2 40.0000 libglib-2.0.so.0.3200.4 - 1 20.0000 libc-2.16.so - </literallayout> - The output above shows the breakdown or samples by both - number of samples and percentage for each executable. - Within an executable, the sample counts are broken down - further into executable and shared libraries (DSOs) used - by the executable. - </para> - - <para> - To get even more detailed breakdowns by function, we need to - have the full paths to the DSOs, which we can get by - using -f with opreport: - <literallayout class='monospaced'> - root@crownbay:~# opreport -f - - CPU: Intel Architectural Perfmon, speed 1.3e+06 MHz (estimated) - Counted CPU_CLK_UNHALTED events (Clock cycles when not halted) with a unit mask of 0x00 (No unit mask) count 100000 - CPU_CLK_UNHALT...| - samples| %| - - 464365 79.8156 /boot/vmlinux-3.4.11-yocto-standard - 65108 11.1908 /usr/bin/oprofiled - CPU_CLK_UNHALT...| - samples| %| - ------------------ - 64416 98.9372 /usr/bin/oprofiled - 692 1.0628 /lib/libc-2.16.so - 36959 6.3526 /no-vmlinux - 4378 0.7525 /bin/busybox - CPU_CLK_UNHALT...| - samples| %| - ------------------ - 2844 64.9612 /lib/libc-2.16.so - 1337 30.5391 /bin/busybox - 193 4.4084 /lib/ld-2.16.so - 2 0.0457 /lib/libnss_compat-2.16.so - 1 0.0228 /lib/libnsl-2.16.so - 1 0.0228 /lib/libnss_files-2.16.so - 4344 0.7467 /bin/bash - CPU_CLK_UNHALT...| - samples| %| - ------------------ - 2657 61.1648 /bin/bash - 1665 38.3287 /lib/libc-2.16.so - 18 0.4144 /lib/ld-2.16.so - 3 0.0691 /lib/libtinfo.so.5.9 - 1 0.0230 /lib/libdl-2.16.so - . - . - . - </literallayout> - Using the paths shown in the above output and the -l option to - opreport, we can see all the functions that have hits in the - profile and their sample counts and percentages. Here's a - portion of what we get for the kernel: - <literallayout class='monospaced'> - root@crownbay:~# opreport -l /boot/vmlinux-3.4.11-yocto-standard - - CPU: Intel Architectural Perfmon, speed 1.3e+06 MHz (estimated) - Counted CPU_CLK_UNHALTED events (Clock cycles when not halted) with a unit mask of 0x00 (No unit mask) count 100000 - samples % symbol name - 233981 50.3873 intel_idle - 15437 3.3243 rb_get_reader_page - 14503 3.1232 ring_buffer_consume - 14092 3.0347 mutex_spin_on_owner - 13024 2.8047 read_hpet - 8039 1.7312 sub_preempt_count - 7096 1.5281 ioread32 - 6997 1.5068 add_preempt_count - 3985 0.8582 rb_advance_reader - 3488 0.7511 add_event_entry - 3303 0.7113 get_parent_ip - 3104 0.6684 rb_buffer_peek - 2960 0.6374 op_cpu_buffer_read_entry - 2614 0.5629 sync_buffer - 2545 0.5481 debug_smp_processor_id - 2456 0.5289 ohci_irq - 2397 0.5162 memset - 2349 0.5059 __copy_to_user_ll - 2185 0.4705 ring_buffer_event_length - 1918 0.4130 in_lock_functions - 1850 0.3984 __schedule - 1767 0.3805 __copy_from_user_ll_nozero - 1575 0.3392 rb_event_data_length - 1256 0.2705 memcpy - 1233 0.2655 system_call - 1213 0.2612 menu_select - </literallayout> - Notice that above we see an entry for the __copy_to_user_ll() - function that we've looked at with other profilers as well. - </para> - - <para> - Here's what we get when we do the same thing for the - busybox executable: - <literallayout class='monospaced'> - CPU: Intel Architectural Perfmon, speed 1.3e+06 MHz (estimated) - Counted CPU_CLK_UNHALTED events (Clock cycles when not halted) with a unit mask of 0x00 (No unit mask) count 100000 - samples % image name symbol name - 349 8.4198 busybox retrieve_file_data - 308 7.4306 libc-2.16.so _IO_file_xsgetn - 283 6.8275 libc-2.16.so __read_nocancel - 235 5.6695 libc-2.16.so syscall - 233 5.6212 libc-2.16.so clearerr - 215 5.1870 libc-2.16.so fread - 181 4.3667 libc-2.16.so __write_nocancel - 158 3.8118 libc-2.16.so __underflow - 151 3.6429 libc-2.16.so _dl_addr - 150 3.6188 busybox progress_meter - 150 3.6188 libc-2.16.so __poll_nocancel - 148 3.5706 libc-2.16.so _IO_file_underflow@@GLIBC_2.1 - 137 3.3052 busybox safe_poll - 125 3.0157 busybox bb_progress_update - 122 2.9433 libc-2.16.so __x86.get_pc_thunk.bx - 95 2.2919 busybox full_write - 81 1.9542 busybox safe_write - 77 1.8577 busybox xwrite - 72 1.7370 libc-2.16.so _IO_file_read - 71 1.7129 libc-2.16.so _IO_sgetn - 67 1.6164 libc-2.16.so poll - 52 1.2545 libc-2.16.so _IO_switch_to_get_mode - 45 1.0856 libc-2.16.so read - 34 0.8203 libc-2.16.so write - 32 0.7720 busybox monotonic_sec - 25 0.6031 libc-2.16.so vfprintf - 22 0.5308 busybox get_mono - 14 0.3378 ld-2.16.so strcmp - 14 0.3378 libc-2.16.so __x86.get_pc_thunk.cx - . - . - . - </literallayout> - Since we recorded the profile with a callchain depth of 6, we - should be able to see our __copy_to_user_ll() callchains in - the output, and indeed we can if we search around a bit in - the 'opreport --callgraph' output: - <literallayout class='monospaced'> - root@crownbay:~# opreport --callgraph /boot/vmlinux-3.4.11-yocto-standard - - 392 6.9639 vmlinux-3.4.11-yocto-standard sock_aio_read - 736 13.0751 vmlinux-3.4.11-yocto-standard __generic_file_aio_write - 3255 57.8255 vmlinux-3.4.11-yocto-standard inet_recvmsg - 785 0.1690 vmlinux-3.4.11-yocto-standard tcp_recvmsg - 1790 31.7940 vmlinux-3.4.11-yocto-standard local_bh_enable - 1238 21.9893 vmlinux-3.4.11-yocto-standard __kfree_skb - 992 17.6199 vmlinux-3.4.11-yocto-standard lock_sock_nested - 785 13.9432 vmlinux-3.4.11-yocto-standard tcp_recvmsg [self] - 525 9.3250 vmlinux-3.4.11-yocto-standard release_sock - 112 1.9893 vmlinux-3.4.11-yocto-standard tcp_cleanup_rbuf - 72 1.2789 vmlinux-3.4.11-yocto-standard skb_copy_datagram_iovec - - 170 0.0366 vmlinux-3.4.11-yocto-standard skb_copy_datagram_iovec - 1491 73.3038 vmlinux-3.4.11-yocto-standard memcpy_toiovec - 327 16.0767 vmlinux-3.4.11-yocto-standard skb_copy_datagram_iovec - 170 8.3579 vmlinux-3.4.11-yocto-standard skb_copy_datagram_iovec [self] - 20 0.9833 vmlinux-3.4.11-yocto-standard copy_to_user - - 2588 98.2909 vmlinux-3.4.11-yocto-standard copy_to_user - 2349 0.5059 vmlinux-3.4.11-yocto-standard __copy_to_user_ll - 2349 89.2138 vmlinux-3.4.11-yocto-standard __copy_to_user_ll [self] - 166 6.3046 vmlinux-3.4.11-yocto-standard do_page_fault - </literallayout> - Remember that by default OProfile sessions are cumulative - i.e. if you start and stop a profiling session, then start a - new one, the new one will not erase the previous run(s) but - will build on it. If you want to restart a profile from scratch, - you need to reset: - <literallayout class='monospaced'> - root@crownbay:~# opcontrol --reset - </literallayout> - </para> - </section> - - <section id='oprofileui-a-gui-for-oprofile'> - <title>OProfileUI - A GUI for OProfile</title> - - <para> - Yocto also supports a graphical UI for controlling and viewing - OProfile traces, called OProfileUI. To use it, you first need - to clone the oprofileui git repo, then configure, build, and - install it: - <literallayout class='monospaced'> - [trz@empanada tmp]$ git clone git://git.yoctoproject.org/oprofileui - [trz@empanada tmp]$ cd oprofileui - [trz@empanada oprofileui]$ ./autogen.sh - [trz@empanada oprofileui]$ sudo make install - </literallayout> - OprofileUI replaces the 'opreport' functionality with a GUI, - and normally doesn't require the user to use 'opcontrol' either. - If you want to profile the kernel, however, you need to either - use the UI to specify a vmlinux or use 'opcontrol' to specify - it on the target: - </para> - - <para> - First, on the target, check if vmlinux file: is set: - <literallayout class='monospaced'> - root@crownbay:~# opcontrol --status - </literallayout> - If not: - <literallayout class='monospaced'> - root@crownbay:~# opcontrol --shutdown - root@crownbay:~# opcontrol --vmlinux=/boot/vmlinux-`uname -r` - root@crownbay:~# opcontrol --start-daemon - </literallayout> - Now, start the oprofile UI on the host system: - <literallayout class='monospaced'> - [trz@empanada oprofileui]$ oprofile-viewer - </literallayout> - To run a profile on the remote system, first connect to the - remote system by pressing the 'Connect' button and supplying - the IP address and port of the remote system (the default - port is 4224). - </para> - - <para> - The oprofile server should automatically be started already. - If not, the connection will fail and you either typed in the - wrong IP address and port (see below), or you need to start - the server yourself: - <literallayout class='monospaced'> - root@crownbay:~# oprofile-server - </literallayout> - Or, to specify a specific port: - <literallayout class='monospaced'> - root@crownbay:~# oprofile-server --port 8888 - </literallayout> - Once connected, press the 'Start' button and then run the - wget workload on the remote system: - <literallayout class='monospaced'> - root@crownbay:~# rm linux-2.6.19.2.tar.bz2; wget <ulink url='http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2'>http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2</ulink>; sync - Connecting to downloads.yoctoproject.org (140.211.169.59:80) - linux-2.6.19.2.tar.b 100% |*******************************| 41727k 0:00:00 ETA - </literallayout> - Once the workload completes, press the 'Stop' button. At that - point the OProfile viewer will download the profile files it's - collected (this may take some time, especially if the kernel - was profiled). While it downloads the files, you should see - something like the following: - </para> - - <para> - <imagedata fileref="figures/oprofileui-downloading.png" width="6in" depth="7in" align="center" scalefit="1" /> - </para> - - <para> - Once the profile files have been retrieved, you should see a - list of the processes that were profiled: - </para> - - <para> - <imagedata fileref="figures/oprofileui-processes.png" width="6in" depth="7in" align="center" scalefit="1" /> - </para> - - <para> - If you select one of them, you should see all the symbols that - were hit during the profile. Selecting one of them will show a - list of callers and callees of the chosen function in two - panes below the top pane. For example, here's what we see - when we select __copy_to_user_ll(): - </para> - - <para> - <imagedata fileref="figures/oprofileui-copy-to-user.png" width="6in" depth="7in" align="center" scalefit="1" /> - </para> - - <para> - As another example, we can look at the busybox process and see - that the progress meter made a system call: - </para> - - <para> - <imagedata fileref="figures/oprofileui-busybox.png" width="6in" depth="7in" align="center" scalefit="1" /> - </para> - </section> - - <section id='oprofile-documentation'> - <title>Documentation</title> - - <para> - Yocto already has some information on setting up and using - OProfile and oprofileui. As this document doesn't cover - everything in detail, it may be worth taking a look at the - "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-oprofile'>Profiling with OProfile</ulink>" - section in the Yocto Project Development Manual - </para> - - <para> - The OProfile manual can be found here: - <ulink url='http://oprofile.sourceforge.net/doc/index.html'>OProfile manual</ulink> - </para> - - <para> - The OProfile website contains links to the above manual and - bunch of other items including an extensive set of examples: - <ulink url='http://oprofile.sourceforge.net/about/'>About OProfile</ulink> - </para> - </section> -</section> - <section id='profile-manual-sysprof'> <title>Sysprof</title> diff --git a/yocto-poky/documentation/profile-manual/profile-manual.xml b/yocto-poky/documentation/profile-manual/profile-manual.xml index 7f9b2c43b..1e0ccc1aa 100644 --- a/yocto-poky/documentation/profile-manual/profile-manual.xml +++ b/yocto-poky/documentation/profile-manual/profile-manual.xml @@ -66,6 +66,11 @@ <date>October 2015</date> <revremark>Released with the Yocto Project 2.0 Release.</revremark> </revision> + <revision> + <revnumber>2.1</revnumber> + <date>April 2016</date> + <revremark>Released with the Yocto Project 2.1 Release.</revremark> + </revision> </revhistory> <copyright> diff --git a/yocto-poky/documentation/ref-manual/closer-look.xml b/yocto-poky/documentation/ref-manual/closer-look.xml index 45dcd9b3c..84ff584ba 100644 --- a/yocto-poky/documentation/ref-manual/closer-look.xml +++ b/yocto-poky/documentation/ref-manual/closer-look.xml @@ -73,7 +73,7 @@ </para> <para> - <imagedata fileref="figures/user-configuration.png" align="center" width="5.5in" depth="3.5in" /> + <imagedata fileref="figures/user-configuration.png" align="center" /> </para> <para> @@ -100,7 +100,7 @@ </para> <para> - The <filename>meta-yocto</filename> layer inside Poky contains + The <filename>meta-poky</filename> layer inside Poky contains a <filename>conf</filename> directory that has example configuration files. These example files are used as a basis for creating actual @@ -158,7 +158,7 @@ To see the default configurations in a <filename>local.conf</filename> file created by the build environment script, see the <filename>local.conf.sample</filename> in the - <filename>meta-yocto</filename> layer: + <filename>meta-poky</filename> layer: <itemizedlist> <listitem><para><emphasis>Parallelism Options:</emphasis> Controlled by the @@ -208,8 +208,10 @@ The files <filename>site.conf</filename> and <filename>auto.conf</filename> are not created by the environment initialization script. - If you want these configuration files, you must create them - yourself: + If you want the <filename>site.conf</filename> file, you need to + create that yourself. + The <filename>auto.conf</filename> file is typically created by + an autobuilder: <itemizedlist> <listitem><para><emphasis><filename>site.conf</filename>:</emphasis> You can use the <filename>conf/site.conf</filename> @@ -235,8 +237,7 @@ directory's <filename>conf/local.conf</filename> file. </para></listitem> <listitem><para><emphasis><filename>auto.conf</filename>:</emphasis> - This file is not hand-created. - Rather, the file is usually created and written to by + The file is usually created and written to by an autobuilder. The settings put into the file are typically the same as you would find in the <filename>conf/local.conf</filename> @@ -254,9 +255,24 @@ <para> When you launch your build with the - <filename>bitbake <replaceable>target</replaceable></filename> command, BitBake - sorts out the configurations to ultimately define your build - environment. + <filename>bitbake <replaceable>target</replaceable></filename> + command, BitBake sorts out the configurations to ultimately + define your build environment. + It is important to understand that the OpenEmbedded build system + reads the configuration files in a specific order: + <filename>site.conf</filename>, <filename>auto.conf</filename>, + and <filename>local.conf</filename>. + And, the build system applies the normal assignment statement + rules. + Because the files are parsed in a specific order, variable + assignments for the same variable could be affected. + For example, if the <filename>auto.conf</filename> file and + the <filename>local.conf</filename> set + <replaceable>variable1</replaceable> to different values, because + the build system parses <filename>local.conf</filename> after + <filename>auto.conf</filename>, + <replaceable>variable1</replaceable> is assigned the value from + the <filename>local.conf</filename> file. </para> </section> @@ -992,11 +1008,13 @@ <para> The image generation process consists of several stages and - depends on many variables. + depends on several tasks and variables. The <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link> - task uses these key variables - to help create the list of packages to actually install: + task creates the root filesystem (file and directory structure) + for an image. + This task uses several key variables to help create the list + of packages to actually install: <itemizedlist> <listitem><para><link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>: Lists out the base set of packages to install from @@ -1016,23 +1034,34 @@ Determines the language(s) for which additional language support packages are installed. </para></listitem> + <listitem><para><link linkend='var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></link>: + The final list of packages passed to the package manager + for installation into the image. + </para></listitem> </itemizedlist> </para> <para> + With + <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link> + pointing to the location of the filesystem under construction and + the <filename>PACKAGE_INSTALL</filename> variable providing the + final list of packages to install, the root file system is + created. + </para> + + <para> Package installation is under control of the package manager (e.g. smart/rpm, opkg, or apt/dpkg) regardless of whether or not package management is enabled for the target. At the end of the process, if package management is not enabled for the target, the package manager's data files are deleted from the root filesystem. - </para> - - <para> - During image generation, the build system attempts to run - all post-installation scripts. - Any that fail to run on the build host are run on the - target when the target system is first booted. + As part of the final stage of package installation, postinstall + scripts that are part of the packages are run. + Any scripts that fail to run + on the build host are run on the target when the target system + is first booted. If you are using a <ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem'>read-only root filesystem</ulink>, all the post installation scripts must succeed during the @@ -1041,24 +1070,17 @@ </para> <para> - During Optimization, optimizing processes are run across - the image. - These processes include <filename>mklibs</filename> and - <filename>prelink</filename>. - The <filename>mklibs</filename> process optimizes the size - of the libraries. - A <filename>prelink</filename> process optimizes the dynamic - linking of shared libraries to reduce start up time of - executables. + The final stages of the <filename>do_rootfs</filename> task + handle post processing. + Post processing includes creation of a manifest file and + optimizations. </para> <para> - Along with writing out the root filesystem image, the - <filename>do_rootfs</filename> task creates a manifest file - (<filename>.manifest</filename>) in the same directory as - the root filesystem image that lists out, line-by-line, the - installed packages. - This manifest file is useful for the + The manifest file (<filename>.manifest</filename>) resides + in the same directory as the root filesystem image. + This file lists out, line-by-line, the installed packages. + The manifest file is useful for the <link linkend='ref-classes-testimage*'><filename>testimage</filename></link> class, for example, to determine whether or not to run specific tests. @@ -1068,21 +1090,54 @@ </para> <para> - Part of the image generation process includes compressing the - root filesystem image. - Compression is accomplished through several optimization - routines designed to reduce the overall size of the image. + Optimizing processes run across the image include + <filename>mklibs</filename>, <filename>prelink</filename>, + and any other post-processing commands as defined by the + <link linkend='var-ROOTFS_POSTPROCESS_COMMAND'><filename>ROOTFS_POSTPROCESS_COMMAND</filename></link> + variable. + The <filename>mklibs</filename> process optimizes the size + of the libraries, while the + <filename>prelink</filename> process optimizes the dynamic + linking of shared libraries to reduce start up time of + executables. </para> <para> - After the root filesystem has been constructed, the image - generation process turns everything into an image file or - a set of image files. + After the root filesystem is built, processing begins on + the image through the <filename>do_image</filename> task. + The build system runs any pre-processing commands as defined + by the + <link linkend='var-IMAGE_PREPROCESS_COMMAND'><filename>IMAGE_PREPROCESS_COMMAND</filename></link> + variable. + This variable specifies a list of functions to call before + the OpenEmbedded build system creates the final image output + files. + </para> + + <para> + The <filename>do_image</filename> task dynamically creates + other <filename>do_image_*</filename> tasks as needed, which + include compressing the root filesystem image to reduce the + overall size of the image. + The process turns everything into an image file or a set of + image files. The formats used for the root filesystem depend on the <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link> variable. </para> + <para> + The final task involved in image creation is the + <filename>do_image_complete</filename> task. + This task completes the image by applying any image + post processing as defined through the + <link linkend='var-IMAGE_POSTPROCESS_COMMAND'><filename>IMAGE_POSTPROCESS_COMMAND</filename></link> + variable. + The variable specifies a list of functions to call once the + OpenEmbedded build system has created the final image output + files. + </para> + <note> The entire image generation process is run under Pseudo. Running under Pseudo ensures that the files in the root @@ -1095,8 +1150,9 @@ <para> The OpenEmbedded build system uses BitBake to generate the - Software Development Kit (SDK) installer script: - <imagedata fileref="figures/sdk-generation.png" align="center" width="6in" depth="7in" /> + Software Development Kit (SDK) installer script for both the + standard and extensible SDKs: + <imagedata fileref="figures/sdk-generation.png" align="center" /> </para> <note> @@ -1108,14 +1164,16 @@ cross-development toolchain using the <link linkend='ref-tasks-populate_sdk'><filename>do_populate_sdk</filename></link> task, see the - "<ulink url='&YOCTO_DOCS_ADT_URL;#optionally-building-a-toolchain-installer'>Optionally Building a Toolchain Installer</ulink>" - section in the Yocto Project Application Developer's Guide. + "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer'>Building an SDK Installer</ulink>" + section in the Yocto Project Software Development Kit (SDK) + Developer's Guide. </note> <para> Like image generation, the SDK script process consists of several stages and depends on many variables. - The <filename>do_populate_sdk</filename> task uses these + The <filename>do_populate_sdk</filename> and + <filename>do_populate_sdk_ext</filename> tasks use these key variables to help create the list of packages to actually install. For information on the variables listed in the figure, see the @@ -1124,8 +1182,9 @@ </para> <para> - The <filename>do_populate_sdk</filename> task handles two - parts: a target part and a host part. + The <filename>do_populate_sdk</filename> task helps create + the standard SDK and handles two parts: a target part and a + host part. The target part is the part built for the target hardware and includes libraries and headers. The host part is the part of the SDK that runs on the @@ -1133,16 +1192,19 @@ </para> <para> - Once both parts are constructed, the - <filename>do_populate_sdk</filename> task performs some cleanup - on both parts. - After the cleanup, the task creates a cross-development - environment setup script and any configuration files that - might be needed. + The <filename>do_populate_sdk_ext</filename> task helps create + the extensible SDK and handles host and target parts + differently than its counter part does for the standard SDK. + For the extensible SDK, the task encapsulates the build system, + which includes everything needed (host and target) for the SDK. </para> <para> - The final output of the task is the Cross-development + Regardless of the type of SDK being constructed, the + tasks perform some cleanup after which a cross-development + environment setup script and any needed configuration files + are created. + The final output is the Cross-development toolchain installation script (<filename>.sh</filename> file), which includes the environment setup script. </para> @@ -1239,8 +1301,13 @@ <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>, the output labeled "Application Development SDK" represents an SDK. + The SDK generation process differs depending on whether you build + a standard SDK + (e.g. <filename>bitbake -c populate_sdk</filename> <replaceable>imagename</replaceable>) + or an extensible SDK + (e.g. <filename>bitbake -c populate_sdk_ext</filename> <replaceable>imagename</replaceable>). This section is going to take a closer look at this output: - <imagedata fileref="figures/sdk.png" align="center" width="5in" depth="4in" /> + <imagedata fileref="figures/sdk.png" align="center" width="9in" depth="7.25in" /> </para> <para> @@ -1255,20 +1322,16 @@ part because it runs on the SDK machine. You can think of the libraries and headers as the "target" part because they are built for the target hardware. - The setup script is added so that you can initialize the - environment before using the tools. + The environment setup script is added so that you can initialize + the environment before using the tools. </para> <note> <para> The Yocto Project supports several methods by which you can set up this cross-development environment. - These methods include downloading pre-built SDK installers, - building and installing your own SDK installer, or running - an Application Development Toolkit (ADT) installer to - install not just cross-development toolchains - but also additional tools to help in this type of - development. + These methods include downloading pre-built SDK installers + or building and installing your own SDK installer. </para> <para> @@ -1278,8 +1341,7 @@ section. For information on setting up a cross-development environment, see the - "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>" - section in the Yocto Project Application Developer's Guide. + <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-manual'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>. </para> </note> @@ -1288,7 +1350,10 @@ <filename>deploy/sdk</filename> folder inside the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> as shown in the figure at the beginning of this section. - Several variables exist that help configure these files: + Depending on the type of SDK, several variables exist that help + configure these files. + The following list shows the variables associated with a standard + SDK: <itemizedlist> <listitem><para><link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>: Points to the <filename>deploy</filename> @@ -1322,6 +1387,36 @@ installation script. </para></listitem> </itemizedlist> + This next list, shows the variables associated with an extensible + SDK: + <itemizedlist> + <listitem><para><link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>: + Points to the <filename>deploy</filename> directory. + </para></listitem> + <listitem><para><link linkend='var-SDK_EXT_TYPE'><filename>SDK_EXT_TYPE</filename></link>: + Controls whether or not shared state artifacts are copied + into the extensible SDK. + By default, all required shared state artifacts are copied + into the SDK. + </para></listitem> + <listitem><para><link linkend='var-SDK_INCLUDE_PKGDATA'><filename>SDK_INCLUDE_PKGDATA</filename></link>: + 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_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. + </para></listitem> + <listitem><para><link linkend='var-SDK_LOCAL_CONF_BLACKLIST'><filename>SDK_LOCAL_CONF_BLACKLIST</filename></link>: + A list of variables not allowed through from the build + system configuration into the extensible SDK configuration. + </para></listitem> + <listitem><para><link linkend='var-SDK_INHERIT_BLACKLIST'><filename>SDK_INHERIT_BLACKLIST</filename></link>: + A list of classes to remove from the + <link linkend='var-INHERIT'><filename>INHERIT</filename></link> + value globally within the extensible SDK configuration. + </para></listitem> + </itemizedlist> </para> </section> diff --git a/yocto-poky/documentation/ref-manual/faq.xml b/yocto-poky/documentation/ref-manual/faq.xml index 197d49074..d2e4e8eb1 100644 --- a/yocto-poky/documentation/ref-manual/faq.xml +++ b/yocto-poky/documentation/ref-manual/faq.xml @@ -280,23 +280,42 @@ <qandaentry> <question> - <para> + <para id='i-am-behind-a-firewall-and-need-to-use-a-proxy-server'> I'm behind a firewall and need to use a proxy server. How do I do that? </para> </question> <answer> <para> - Most source fetching by the OpenEmbedded build system is done by <filename>wget</filename> - and you therefore need to specify the proxy settings in a - <filename>.wgetrc</filename> file in your home directory. - Here are some example settings: + Most source fetching by the OpenEmbedded build system is done + by <filename>wget</filename> and you therefore need to specify + the proxy settings in a <filename>.wgetrc</filename> file, + which can be in your home directory if you are a single user + or can be in <filename>/usr/local/etc/wgetrc</filename> as + a global user file. + </para> + + <para> + Following is the applicable code for setting various proxy + types in the <filename>.wgetrc</filename> file. + By default, these settings are disabled with comments. + To use them, remove the comments: <literallayout class='monospaced'> - http_proxy = http://proxy.yoyodyne.com:18023/ - ftp_proxy = http://proxy.yoyodyne.com:18023/ + # You can set the default proxies for Wget to use for http, https, and ftp. + # They will override the value in the environment. + #https_proxy = http://proxy.yoyodyne.com:18023/ + #http_proxy = http://proxy.yoyodyne.com:18023/ + #ftp_proxy = http://proxy.yoyodyne.com:18023/ + + # If you do not want to use proxy at all, set this to off. + #use_proxy = on </literallayout> The Yocto Project also includes a - <filename>site.conf.sample</filename> file that shows how to - configure CVS and Git proxy servers if needed. + <filename>meta-poky/conf/site.conf.sample</filename> file that + shows how to configure CVS and Git proxy servers if needed. + For more information on setting up various proxy types and + configuring proxy servers, see the + "<ulink url='&YOCTO_WIKI_URL;/wiki/Working_Behind_a_Network_Proxy'>Working Behind a Network Proxy</ulink>" + Wiki page. </para> </answer> </qandaentry> @@ -367,7 +386,7 @@ <para> This issue is just a single manifestation of "system - leakage" issues caused when the OpenEbedded build system + leakage" issues caused when the OpenEmbedded build system finds and uses previously installed files during a native build. This type of issue might not be limited to @@ -782,7 +801,7 @@ <qandaentry> <question> <para> - The files provided by my <filename>-native</filename> recipe do + The files provided by my <filename>*-native</filename> recipe do not appear to be available to other recipes. Files are missing from the native sysroot, my recipe is installing to the wrong place, or I am getting permissions diff --git a/yocto-poky/documentation/ref-manual/figures/image-generation.png b/yocto-poky/documentation/ref-manual/figures/image-generation.png Binary files differindex ab962580c..71a48dc6f 100644 --- a/yocto-poky/documentation/ref-manual/figures/image-generation.png +++ b/yocto-poky/documentation/ref-manual/figures/image-generation.png diff --git a/yocto-poky/documentation/ref-manual/figures/sdk-generation.png b/yocto-poky/documentation/ref-manual/figures/sdk-generation.png Binary files differindex c37e2748c..adbe1f4ac 100644..100755 --- a/yocto-poky/documentation/ref-manual/figures/sdk-generation.png +++ b/yocto-poky/documentation/ref-manual/figures/sdk-generation.png diff --git a/yocto-poky/documentation/ref-manual/figures/sdk.png b/yocto-poky/documentation/ref-manual/figures/sdk.png Binary files differindex a539cc52f..5c36b7548 100644 --- a/yocto-poky/documentation/ref-manual/figures/sdk.png +++ b/yocto-poky/documentation/ref-manual/figures/sdk.png diff --git a/yocto-poky/documentation/ref-manual/figures/user-configuration.png b/yocto-poky/documentation/ref-manual/figures/user-configuration.png Binary files differindex f2b3f8e7f..c298401fc 100644..100755 --- a/yocto-poky/documentation/ref-manual/figures/user-configuration.png +++ b/yocto-poky/documentation/ref-manual/figures/user-configuration.png diff --git a/yocto-poky/documentation/ref-manual/introduction.xml b/yocto-poky/documentation/ref-manual/introduction.xml index 0b165443f..ce8fa5c65 100644 --- a/yocto-poky/documentation/ref-manual/introduction.xml +++ b/yocto-poky/documentation/ref-manual/introduction.xml @@ -9,19 +9,26 @@ <title>Introduction</title> <para> - This manual provides reference information for the current release of the Yocto Project. - The Yocto Project is an open-source collaboration project focused on embedded Linux - developers. - Amongst other things, the Yocto Project uses the OpenEmbedded build system, which - is based on the Poky project, to construct complete Linux images. - You can find complete introductory and getting started information on the Yocto Project - by reading the + This manual provides reference information for the current release + of the Yocto Project. + The Yocto Project is an open-source collaboration project focused + on embedded Linux developers. + Amongst other things, the Yocto Project uses the OpenEmbedded build + system, which is based on the Poky project, to construct complete + Linux images. + You can find complete introductory and getting started information + on the Yocto Project by reading the <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>. + </para> + + <para> For task-based information using the Yocto Project, see the <ulink url='&YOCTO_DOCS_DEV_URL;'>Yocto Project Development Manual</ulink> and the <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>. For Board Support Package (BSP) structure information, see the <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>. + For information on how to use a Software Development Kit, (SDK), see the + <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>. You can find information on tracing and profiling in the <ulink url='&YOCTO_DOCS_PROF_URL;'>Yocto Project Profiling and Tracing Manual</ulink>. For information on BitBake, which is the task execution tool the @@ -40,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 debugging images created in the Yocto Project. + followed by information about debugng 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> @@ -192,10 +199,6 @@ supported Linux distribution, instances might exist where you encounter a problem while using the Yocto Project on a specific distribution. - For example, the CentOS 6.4 distribution does not include the - Gtk+ 2.20.0 and PyGtk 2.21.0 (or higher) packages, which are - required to run - <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink>. </note> </section> @@ -249,9 +252,9 @@ <literallayout class='monospaced'> $ sudo apt-get install make xsltproc docbook-utils fop dblatex xmlto </literallayout></para></listitem> - <listitem><para><emphasis>ADT Installer Extras:</emphasis> + <listitem><para><emphasis>SDK Installer Extras:</emphasis> Packages needed if you are going to be using the - <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>: + the standard or extensible SDK: <literallayout class='monospaced'> $ sudo apt-get install autoconf automake libtool libglib2.0-dev libarchive-dev </literallayout></para></listitem> @@ -293,9 +296,9 @@ $ 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>ADT Installer Extras:</emphasis> + <listitem><para><emphasis>SDK Installer Extras:</emphasis> Packages needed if you are going to be using the - <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>: + standard or extensible SDK: <literallayout class='monospaced'> $ sudo dnf install autoconf automake libtool glib2-devel libarchive-devel </literallayout></para></listitem> @@ -336,9 +339,9 @@ <literallayout class='monospaced'> $ sudo zypper install make fop xsltproc dblatex xmlto </literallayout></para></listitem> - <listitem><para><emphasis>ADT Installer Extras:</emphasis> + <listitem><para><emphasis>SDK Installer Extras:</emphasis> Packages needed if you are going to be using the - <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>: + standard or extensible SDK: <literallayout class='monospaced'> $ sudo zypper install autoconf automake libtool glib2-devel libarchive-devel </literallayout></para></listitem> @@ -359,14 +362,14 @@ The following list shows the required packages by function given a supported CentOS Linux distribution: <note> - For CentOS 6.x, some of the versions - of the components provided by the distribution are - too old (e.g. Git, Python, and tar). - It is recommended that you install the buildtools - in order to provide versions that will work with - the OpenEmbedded build system. - For information on how to install the buildtools - tarball, see the + For CentOS 6.x, some of the versions of the components + provided by the distribution are too old (e.g. Git, Python, + and tar). + It is recommended that you install the buildtools in order + to provide versions that will work with the OpenEmbedded + build system. + For information on how to install the buildtools tarball, + see the "<link linkend='required-git-tar-and-python-versions'>Required Git, Tar, and Python Versions</link>" section. </note> @@ -391,21 +394,12 @@ $ 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>ADT Installer Extras:</emphasis> + <listitem><para><emphasis>SDK Installer Extras:</emphasis> Packages needed if you are going to be using the - <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>: + standard or extensible SDK: <literallayout class='monospaced'> $ sudo yum install autoconf automake libtool glib2-devel libarchive-devel - </literallayout> - <note> - For CentOS 6.x, in order for the - ADT installer script to work, you must have - installed the <filename>liblzma5</filename>, - <filename>libarchive3.x</filename>, and - <filename>libarchive-devel-3.1.3</filename> - (or older) packages, in that order. - </note> - </para></listitem> + </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>: @@ -426,7 +420,7 @@ must meet the following version requirements for Git, tar, and Python: <itemizedlist> - <listitem><para>Git 1.7.8 or greater</para></listitem> + <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> @@ -597,8 +591,8 @@ <listitem><para><emphasis>Nightly Builds:</emphasis> These tarball releases are available at <ulink url='&YOCTO_AB_NIGHTLY_URL;'/>. - These builds include Yocto Project releases, meta-toolchain - tarball installation scripts, and experimental builds. + These builds include Yocto Project releases, SDK installation + scripts, and experimental builds. </para></listitem> <listitem><para><emphasis>Yocto Project Website:</emphasis> You can find tarball releases of the Yocto Project and supported BSPs diff --git a/yocto-poky/documentation/ref-manual/migration.xml b/yocto-poky/documentation/ref-manual/migration.xml index 21763e3a4..e6c0aa36b 100644 --- a/yocto-poky/documentation/ref-manual/migration.xml +++ b/yocto-poky/documentation/ref-manual/migration.xml @@ -97,13 +97,14 @@ <para> The shared state cache (sstate-cache), as pointed to by - <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>, by default - now has two-character subdirectories to prevent issues arising - from too many files in the same directory. - Also, native sstate-cache packages will go into a subdirectory named using + <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>, + by default now has two-character subdirectories to prevent + issues arising from too many files in the same directory. + Also, native sstate-cache packages, which are built to run + on the host system, will go into a subdirectory named using the distro ID string. - If you copy the newly structured sstate-cache to a mirror location - (either local or remote) and then point to it in + If you copy the newly structured sstate-cache to a mirror + location (either local or remote) and then point to it in <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>, you need to append "PATH" to the end of the mirror URL so that the path used by BitBake before the mirror substitution is @@ -124,7 +125,7 @@ reference hardware Board Support Packages (BSPs), respectively: <filename>meta-yocto</filename> and <filename>meta-yocto-bsp</filename>. - When running BitBake or Hob for the first time after upgrading, + When running BitBake for the first time after upgrading, your <filename>conf/bblayers.conf</filename> file will be updated to handle this change and you will be asked to re-run or restart for the changes to take effect. @@ -191,8 +192,10 @@ The suffix <filename>nativesdk</filename> is now implemented as a prefix, which simplifies a lot of the packaging code for <filename>nativesdk</filename> recipes. - All custom <filename>nativesdk</filename> recipes and any - references need to be updated to use + All custom <filename>nativesdk</filename> recipes, which are + relocatable packages that are native to + <link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link>, + and any references need to be updated to use <filename>nativesdk-*</filename> instead of <filename>*-nativesdk</filename>. </para> @@ -1443,18 +1446,6 @@ </section> </section> - <section id='migration-1.6-directory-layout-changes'> - <title>Directory Layout Changes</title> - - <para> - The <filename>meta-hob</filename> layer has been removed from - the top-level of the - <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. - The contents of this layer are no longer needed by the Hob - user interface for building images and toolchains. - </para> - </section> - <section id='migration-1.6-package-test-ptest'> <title>Package Test (ptest)</title> @@ -2456,9 +2447,10 @@ </literallayout> </para></listitem> <listitem><para> - <filename>d.delVar('VARNAME')</filename> and - <filename>d.setVar('VARNAME', None)</filename> result - in the variable and all of its overrides being cleared out. + <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 were cleared. </para></listitem> @@ -2735,6 +2727,558 @@ </section> </section> +<section id='moving-to-the-yocto-project-2.1-release'> + <title>Moving to the Yocto Project 2.1 Release</title> + + <para> + This section provides migration information for moving to the + Yocto Project 2.1 Release from the prior release. + </para> + + <section id='migration-2.1-variable-expansion-in-python-functions'> + <title>Variable Expansion in Python Functions</title> + + <para> + Variable expressions, such as + <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 + variables through <filename>d.getVar()</filename>. + To alternatively expand more complex expressions, + use <filename>d.expand()</filename>. + </para> + </section> + + <section id='migration-2.1-overrides-must-now-be-lower-case'> + <title>Overrides Must Now be Lower-Case</title> + + <para> + The convention for overrides has always been for them to be + lower-case characters. + This practice is now a requirement as BitBake's datastore now + assumes lower-case characters in order to give a slight performance + boost during parsing. + In practical terms, this requirement means that anything that ends + up in + <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link> + must now appear in lower-case characters (e.g. values for + <filename>MACHINE</filename>, <filename>TARGET_ARCH</filename>, + <filename>DISTRO</filename>, and also recipe names if + <filename>_pn-</filename><replaceable>recipename</replaceable> + overrides are to be effective). + </para> + </section> + + <section id='migration-2.1-expand-parameter-to-getvar-and-getvarflag-now-mandatory'> + <title>Expand Parameter to <filename>getVar()</filename> and + <filename>getVarFlag()</filename> is Now Mandatory</title> + + <para> + The expand parameter to <filename>getVar()</filename> and + <filename>getVarFlag()</filename> previously defaulted to + False if not specified. + Now, however, no default exists so one must be specified. + You must change any <filename>getVar()</filename> calls that + do not specify the final expand parameter to calls that do specify + the parameter. + You can run the following <filename>sed</filename> command at the + base of a layer to make this change: + <literallayout class='monospaced'> + sed -e 's:\(\.getVar([^,()]*\)):\1, False):g' -i `grep -ril getVar *` + sed -e 's:\(\.getVarFlag([^,()]*, [^,()]*\)):\1, False):g' -i `grep -ril getVarFlag *` + </literallayout> + <note> + The reason for this change is that it prepares the way for + changing the default to True in a future Yocto Project release. + This future change is a much more sensible default than False. + However, the change needs to be made gradually as a sudden + change of the default would potentially cause side-effects + that would be difficult to detect. + </note> + </para> + </section> + + <section id='migration-2.1-makefile-environment-changes'> + <title>Makefile Environment Changes</title> + + <para> + <link linkend='var-EXTRA_OEMAKE'><filename>EXTRA_OEMAKE</filename></link> + now defaults to "" instead of "-e MAKEFLAGS=". + Setting <filename>EXTRA_OEMAKE</filename> to "-e MAKEFLAGS=" by + default was a historical accident that has required many classes + (e.g. <filename>autotools</filename>, <filename>module</filename>) + and recipes to override this default in order to work with + sensible build systems. + When upgrading to the release, you must edit any recipe that + relies upon this old default by either setting + <filename>EXTRA_OEMAKE</filename> back to "-e MAKEFLAGS=" or by + explicitly setting any required variable value overrides using + <filename>EXTRA_OEMAKE</filename>, which is typically only needed + when a Makefile sets a default value for a variable that is + inappropriate for cross-compilation using the "=" operator rather + than the "?=" operator. + </para> + </section> + + <section id='migration-2.1-libexecdir-reverted-to-prefix-libexec'> + <title><filename>libexecdir</filename> Reverted to <filename>${prefix}/libexec</filename></title> + + <para> + The use of <filename>${libdir}/${BPN}</filename> as + <filename>libexecdir</filename> is different as compared to all + other mainstream distributions, which either uses + <filename>${prefix}/libexec</filename> or + <filename>${libdir}</filename>. + The use is also contrary to the GNU Coding Standards + (i.e. <ulink url='https://www.gnu.org/prep/standards/html_node/Directory-Variables.html'></ulink>) + that suggest <filename>${prefix}/libexec</filename> and also + notes that any package-specific nesting should be done by the + package itself. + Finally, having <filename>libexecdir</filename> change between + recipes makes it very difficult for different recipes to invoke + binaries that have been installed into + <filename>libexecdir</filename>. + The Filesystem Hierarchy Standard + (i.e. <ulink url='http://refspecs.linuxfoundation.org/FHS_3.0/fhs/ch04s07.html'></ulink>) + now recognizes the use of <filename>${prefix}/libexec/</filename>, + giving distributions the choice between + <filename>${prefix}/lib</filename> or + <filename>${prefix}/libexec</filename> without breaking FHS. + </para> + </section> + + <section id='migration-2.1-ac-cv-sizeof-off-t-no-longer-cached-in-site-files'> + <title><filename>ac_cv_sizeof_off_t</filename> is No Longer Cached in Site Files</title> + + <para> + For recipes inheriting the + <link linkend='ref-classes-autotools'><filename>autotools</filename></link> + class, <filename>ac_cv_sizeof_off_t</filename> is no longer cached + in the site files for <filename>autoconf</filename>. + The reason for this change is because the + <filename>ac_cv_sizeof_off_t</filename> value is not necessarily + static per architecture as was previously assumed. + Rather, the value changes based on whether large file support is + enabled. + For most software that uses <filename>autoconf</filename>, this + change should not be a problem. + However, if you have a recipe that bypasses the standard + <link linkend='ref-tasks-configure'><filename>do_configure</filename></link> + task from the <filename>autotools</filename> class and the software + the recipe is building uses a very old version of + <filename>autoconf</filename>, the recipe might be incapable of + determining the correct size of <filename>off_t</filename> during + <filename>do_configure</filename>. + </para> + + <para> + The best course of action is to patch the software as necessary + 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 + overridden <filename>do_configure</filename> task such that the + default implementation does get used. + </para> + </section> + + <section id='migration-2.1-image-generation-split-out-from-filesystem-generation'> + <title>Image Generation is Now Split Out from Filesystem Generation</title> + + <para> + Previously, for image recipes the + <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link> + task assembled the filesystem and then from that filesystem + generated images. + With this Yocto Project release, image generation is split into + separate + <link linkend='ref-tasks-image'><filename>do_image_*</filename></link> + tasks for clarity both in operation and in the code. + </para> + + <para> + For most cases, this change does not present any problems. + However, if you have made customizations that directly modify the + <filename>do_rootfs</filename> task or that mention + <filename>do_rootfs</filename>, you might need to update those + changes. + In particular, if you had added any tasks after + <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 + run at the correct time. + </para> + + <para> + A minor part of this restructuring is that the post-processing + definitions and functions have been moved from the + <link linkend='ref-classes-image'><filename>image</filename></link> + class to the + <link linkend='ref-classes-rootfs*'><filename>rootfs-postcommands</filename></link> + class. + Functionally, however, they remain unchanged. + </para> + </section> + + <section id='migration-2.1-removed-recipes'> + <title>Removed Recipes</title> + + <para> + The following recipes have been removed in the 2.1 release: + <itemizedlist> + <listitem><para><filename>gcc</filename> version 4.8: + Versions 4.9 and 5.3 remain. + </para></listitem> + <listitem><para><filename>qt4</filename>: + All support for Qt 4.x has been moved out to a separate + <filename>meta-qt4</filename> layer because Qt 4 is no + longer supported upstream. + </para></listitem> + <listitem><para><filename>x11vnc</filename>: + Moved to the <filename>meta-oe</filename> layer. + </para></listitem> + <listitem><para><filename>linux-yocto-3.14</filename>: + No longer supported. + </para></listitem> + <listitem><para><filename>linux-yocto-3.19</filename>: + No longer supported. + </para></listitem> + <listitem><para><filename>libjpeg</filename>: + Replaced by the <filename>libjpeg-turbo</filename> recipe. + </para></listitem> + <listitem><para><filename>pth</filename>: + Became obsolete. + </para></listitem> + <listitem><para><filename>liboil</filename>: + Recipe is no longer needed and has been moved to the + <filename>meta-multimedia</filename> layer. + </para></listitem> + <listitem><para><filename>gtk-theme-torturer</filename>: + Recipe is no longer needed and has been moved to the + <filename>meta-gnome</filename> layer. + </para></listitem> + <listitem><para><filename>gnome-mime-data</filename>: + Recipe is no longer needed and has been moved to the + <filename>meta-gnome</filename> layer. + </para></listitem> + <listitem><para><filename>udev</filename>: + Replaced by the <filename>eudev</filename> recipe for + compatibility when using <filename>sysvinit</filename> + with newer kernels. + </para></listitem> + <listitem><para><filename>python-pygtk</filename>: + Recipe became obsolete. + </para></listitem> + <listitem><para><filename>adt-installer</filename>: + Recipe became obsolete. + See the + "<link linkend='migration-2.1-adt-removed'>ADT Removed</link>" + section for more information. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.1-class-changes'> + <title>Class Changes</title> + + <para> + The following classes have changed: + <itemizedlist> + <listitem><para><filename>autotools_stage</filename>: + Removed because the + <link linkend='ref-classes-autotools'><filename>autotools</filename></link> + class now provides its functionality. + Recipes that inherited from + <filename>autotools_stage</filename> should now inherit + from <filename>autotools</filename> instead. + </para></listitem> + <listitem><para><filename>boot-directdisk</filename>: + Merged into the + <link linkend='ref-classes-image-vm'><filename>image-vm</filename></link> + class. + The <filename>boot-directdisk</filename> class was rarely + directly used. + Consequently, this change should not cause any issues. + </para></listitem> + <listitem><para><filename>bootimg</filename>: + Merged into the + <link linkend='ref-classes-image-live'><filename>image-live</filename></link> + class. + The <filename>bootimg</filename> class was rarely + directly used. + Consequently, this change should not cause any issues. + </para></listitem> + <listitem><para><filename>packageinfo</filename>: + Removed due to its limited use by the Hob UI, which has + itself been removed. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.1-build-system-ui-changes'> + <title>Build System User Interface Changes</title> + + <para> + The following changes have been made to the build system user + interface: + <itemizedlist> + <listitem><para><emphasis>Hob GTK+-based UI</emphasis>: + Removed because it is unmaintained and based on the + outdated GTK+ 2 library. + The Toaster web-based UI is much more capable and is + actively maintained. + See the + "<ulink url='&YOCTO_DOCS_TOAST_URL;#using-the-toaster-web-interface'>Using the Toaster Web Interface</ulink>" + section in the Yocto Project Toaster User Manual for more + information on this interface. + </para></listitem> + <listitem><para><emphasis>"puccho" BitBake UI</emphasis>: + Removed because is unmaintained and no longer useful. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.1-adt-removed'> + <title>ADT Removed</title> + + <para> + The Application Development Toolkit (ADT) has been removed + because its functionality almost completely overlapped with the + <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-using-the-standard-sdk'>standard SDK</ulink> + and the + <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>. + </para> + </section> + + <section id='migration-2.1-poky-reference-distribution-changes'> + <title>Poky Reference Distribution Changes</title> + + <para> + The following changes have been made for the Poky distribution: + <itemizedlist> + <listitem><para> + The <filename>meta-yocto</filename> layer has been renamed + to <filename>meta-poky</filename> to better match its + purpose, which is to provide the Poky reference + distribution. + The <filename>meta-yocto-bsp</filename> layer retains its + original name since it provides reference machines for + the Yocto Project and it is otherwise unrelated to Poky. + References to <filename>meta-yocto</filename> in your + <filename>conf/bblayers.conf</filename> should + automatically be updated, so you should not need to change + anything unless you are relying on this naming elsewhere. + </para></listitem> + <listitem><para> + The + <link linkend='ref-classes-uninative'><filename>uninative</filename></link> + class is now enabled by default in Poky. + This class attempts to isolate the build system from the + host distribution's C library and makes re-use of native + shared state artifacts across different host distributions + practical. + With this class enabled, a tarball containing a pre-built + C library is downloaded at the start of the build.</para> + + <para>The <filename>uninative</filename> class is enabled + through the + <filename>meta/conf/distro/include/yocto-uninative.inc</filename> + file, which for those not using the Poky distribution, can + include to easily enable the same functionality.</para> + + <para>Alternatively, if you wish to build your own + <filename>uninative</filename> tarball, you can do so by + building the <filename>uninative-tarball</filename> recipe, + making it available to your build machines + (e.g. over HTTP/HTTPS) and setting a similar configuration + as the one set by <filename>yocto-uninative.inc</filename>. + </para></listitem> + <listitem><para> + Static library generation, for most cases, is now disabled + by default in the Poky distribution. + Disabling this generation saves some build time as well + as the size used for build output artifacts.</para> + + <para>Disabling this library generation is accomplished + through a + <filename>meta/conf/distro/include/no-static-libs.inc</filename>, + which for those not using the Poky distribution can + easily include to enable the same functionality.</para> + + <para>Any recipe that needs to opt-out of having the + "--disable-static" option specified on the configure + command line either because it is not a supported option + for the configure script or because static libraries are + needed should set the following variable: + <literallayout class='monospaced'> + DISABLE_STATIC = "" + </literallayout> + </para></listitem> + <listitem><para> + 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 + distribution and facilitates much greater maintainability + because musl is designed to have a small footprint.</para> + + <para>If you have used <filename>poky-tiny</filename> and + have customized the <filename>glibc</filename> + configuration you will need to redo those customizations + with musl when upgrading to the new release. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.1-packaging-changes'> + <title>Packaging Changes</title> + + <para> + The following changes have been made to packaging: + <itemizedlist> + <listitem><para> + The <filename>runuser</filename> and + <filename>mountpoint</filename> binaries, which were + previously in the main <filename>util-linux</filename> + package, have been split out into the + <filename>util-linux-runuser</filename> and + <filename>util-linux-mountpoint</filename> packages, + respectively. + </para></listitem> + <listitem><para> + The <filename>python-elementtree</filename> package has + been merged into the <filename>python-xml</filename> + package. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.1-tuning-file-changes'> + <title>Tuning File Changes</title> + + <para> + The following changes have been made to the tuning files: + <itemizedlist> + <listitem><para> + The "no-thumb-interwork" tuning feature has been dropped + from the ARM tune include files. + Because interworking is required for ARM EABI, attempting + to disable it through a tuning feature no longer makes + sense. + <note> + Support for ARM OABI was deprecated in gcc 4.7. + </note> + </para></listitem> + <listitem><para> + The <filename>tune-cortexm*.inc</filename> and + <filename>tune-cortexr4.inc</filename> files have been + removed because they are poorly tested. + Until the OpenEmbedded build system officially gains + support for CPUs without an MMU, these tuning files would + probably be better maintained in a separate layer + if needed. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='migration-2.1-miscellaneous-changes'> + <title>Miscellaneous Changes</title> + + <para> + These additional changes exist: + <itemizedlist> + <listitem><para> + The minimum Git version has been increased to 1.8.3.1. + If your host distribution does not provide a sufficiently + recent version, you can install the buildtools, which + will provide it. + </para></listitem> + <listitem><para> + The buggy and incomplete support for the RPM version 4 + package manager has been removed. + The well-tested and maintained support for RPM version 5 + remains. + </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 + is most commonly expected. + 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 + <filename>devtool modify</filename>. + </para></listitem> + <listitem><para> + If the formfactor for a machine is either not supplied + 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> + <listitem><para> + The <filename>.debug</filename> directory packaging is + now automatic. + If your recipe builds software that installs binaries into + directories other than the standard ones, you no longer + need to take care of setting + <filename>FILES_${PN}-dbg</filename> to pick up the + resulting <filename>.debug</filename> directories as these + directories are automatically found and added. + </para></listitem> + <listitem><para> + Inaccurate disk and CPU percentage data has been dropped + from <filename>buildstats</filename> output. + 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. + </para></listitem> + <listitem><para> + The + <filename>meta/conf/distro/include/package_regex.inc</filename> + is now deprecated. + The contents of this file have been moved to individual + recipes. + <note><title>Tip</title> + Because this file will likely be removed in a future + Yocto Project release, it is suggested that you remove + any references to the file that might be in your + configuration. + </note> + </para></listitem> + <listitem><para> + The <filename>v86d/uvesafb</filename> has been removed from + the <filename>genericx86</filename> and + <filename>genericx86-64</filename> reference machines, + which are provided by the + <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. + </para></listitem> + </itemizedlist> + </para> + </section> +</section> </chapter> <!-- diff --git a/yocto-poky/documentation/ref-manual/ref-bitbake.xml b/yocto-poky/documentation/ref-manual/ref-bitbake.xml index dc402dbff..1de114826 100644 --- a/yocto-poky/documentation/ref-manual/ref-bitbake.xml +++ b/yocto-poky/documentation/ref-manual/ref-bitbake.xml @@ -414,7 +414,7 @@ Options: -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS Show debug logging for the specified logging domains -P, --profile Profile the command and save reports. - -u UI, --ui=UI The user interface to use (e.g. knotty, hob, depexp). + -u UI, --ui=UI The user interface to use (e.g. knotty and depexp). -t SERVERTYPE, --servertype=SERVERTYPE Choose which server to use, process or xmlrpc. --revisions-changed Set the exit code depending on whether upstream diff --git a/yocto-poky/documentation/ref-manual/ref-classes.xml b/yocto-poky/documentation/ref-manual/ref-classes.xml index b2941b8bf..e919bd7eb 100644 --- a/yocto-poky/documentation/ref-manual/ref-classes.xml +++ b/yocto-poky/documentation/ref-manual/ref-classes.xml @@ -128,8 +128,7 @@ <para> By default, the <filename>autotools*</filename> classes use out-of-tree builds (i.e. - <filename>autotools.bbclass</filename> and - <filename>autotools_stage.bbclass</filename>). + <filename>autotools.bbclass</filename>). (<link linkend='var-B'><filename>B</filename></link> <filename>!=</filename> <link linkend='var-S'><filename>S</filename></link>). </para> @@ -139,8 +138,7 @@ using out-of-tree builds, you should have the recipe inherit the <filename>autotools-brokensep</filename> class. The <filename>autotools-brokensep</filename> class behaves the same - as the <filename>autotools</filename> and - <filename>autotools_stage</filename> classes but builds with + as the <filename>autotools</filename> class but builds with <link linkend='var-B'><filename>B</filename></link> == <link linkend='var-S'><filename>S</filename></link>. This method is useful when out-of-tree build support is either not @@ -201,6 +199,15 @@ </para> </section> +<section id='ref-classes-bash-completion'> + <title><filename>bash-completion.bbclass</filename></title> + + <para> + Sets up packaging and dependencies appropriate for recipes that + build software that includes bash-completion data. + </para> +</section> + <section id='ref-classes-bin-package'> <title><filename>bin_package.bbclass</filename></title> @@ -319,64 +326,6 @@ </para> </section> -<section id='ref-classes-boot-directdisk'> - <title><filename>boot-directdisk.bbclass</filename></title> - - <para> - The <filename>boot-directdisk</filename> class - creates an image that can be placed directly onto a hard disk using - <filename>dd</filename> and then booted. - The image uses SYSLINUX. - </para> - - <para> - The end result is a 512 boot sector populated with a - Master Boot Record (MBR) and partition table followed by an MSDOS - FAT16 partition containing SYSLINUX and a Linux kernel completed by - the <filename>ext2</filename> and <filename>ext3</filename> - root filesystems. - </para> -</section> - -<section id='ref-classes-bootimg'> - <title><filename>bootimg.bbclass</filename></title> - - <para> - The <filename>bootimg</filename> class creates a bootable - image using SYSLINUX, your kernel, and an optional initial RAM disk - (<filename>initrd</filename>). - </para> - - <para> - When you use this class, two things happen: - <itemizedlist> - <listitem><para> - A <filename>.hddimg</filename> file is created. - This file is an MSDOS filesystem that contains SYSLINUX, - a kernel, an <filename>initrd</filename>, and a root filesystem - image. - All three of these can be written to hard drives directly and - also booted on a USB flash disks using <filename>dd</filename>. - </para></listitem> - <listitem><para> - A CD <filename>.iso</filename> image is created. - When this file is booted, the <filename>initrd</filename> - boots and processes the label selected in SYSLINUX. - Actions based on the label are then performed (e.g. installing - to a hard drive).</para></listitem> - </itemizedlist> - </para> - - <para> - The <filename>bootimg</filename> class supports the - <link linkend='var-INITRD'><filename>INITRD</filename></link>, - <link linkend='var-NOISO'><filename>NOISO</filename></link>, - <link linkend='var-NOHDD'><filename>NOHDD</filename></link>, and - <link linkend='var-ROOTFS'><filename>ROOTFS</filename></link> - variables. - </para> -</section> - <section id='ref-classes-bugzilla'> <title><filename>bugzilla.bbclass</filename></title> @@ -714,7 +663,9 @@ provides for automatic checking for upstream recipe updates. The class creates a comma-separated value (CSV) spreadsheet that contains information about the recipes. - The information provides the <filename>do_distrodata</filename> and + The information provides the + <link linkend='ref-tasks-distrodata'><filename>do_distrodata</filename></link> + and <filename>do_distro_check</filename> tasks, which do upstream checking and also verify if a package is used in multiple major distributions. </para> @@ -728,6 +679,13 @@ INHERIT+= "distrodata" </literallayout> </para> + + <para> + The <filename>distrodata</filename> class also provides the + <link linkend='ref-tasks-checkpkg'><filename>do_checkpkg</filename></link> + task, which can be used against a simple recipe or against an + image to get all its recipe information. + </para> </section> <section id='ref-classes-distutils'> @@ -999,6 +957,28 @@ </para> </section> +<section id='ref-classes-gobject-introspection'> + <title><filename>gobject-introspection.bbclass</filename></title> + + <para> + Provides support for recipes building software that + supports GObject introspection. + This functionality is only enabled if the + "gobject-introspection-data" feature is in + <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link> + as well as "qemu-usermode" being in + <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>. + <note> + This functionality is backfilled by default and, + if not applicable, should be disabled through + <link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename></link> + or + <link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename></link>, + respectively. + </note> + </para> +</section> + <section id='ref-classes-grub-efi'> <title><filename>grub-efi.bbclass</filename></title> @@ -1146,8 +1126,8 @@ <title><filename>gzipnative.bbclass</filename></title> <para> - The <filename>gzipnative</filename> - class enables the use of native versions of <filename>gzip</filename> + The <filename>gzipnative</filename> class enables the use of + different native versions of <filename>gzip</filename> and <filename>pigz</filename> rather than the versions of these tools from the build host. </para> @@ -2284,6 +2264,29 @@ </para> </section> +<section id='ref-classes-nopackages'> + <title><filename>nopackages.bbclass</filename></title> + + <para> + Disables packaging tasks for those recipes and classes where + packaging is not needed. + </para> +</section> + +<section id='ref-classes-npm'> + <title><filename>npm.bbclass</filename></title> + + <para> + Provides support for building Node.js software fetched using the npm + package manager. + <note> + Currently, recipes inheriting this class must use the + <filename>npm://</filename> fetcher to have dependencies fetched + and packaged automatically. + </note> + </para> +</section> + <section id='ref-classes-oelint'> <title><filename>oelint.bbclass</filename></title> @@ -2558,22 +2561,6 @@ </para> </section> -<section id='ref-classes-packageinfo'> - <title><filename>packageinfo.bbclass</filename></title> - - <para> - The <filename>packageinfo</filename> class - gives a BitBake user interface the ability to retrieve information - about output packages from the <filename>pkgdata</filename> files. - </para> - - <para> - This class is enabled automatically when using the - <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink> - user interface. - </para> -</section> - <section id='ref-classes-patch'> <title><filename>patch.bbclass</filename></title> @@ -2654,8 +2641,8 @@ toolchain using the <link linkend='ref-tasks-populate_sdk'><filename>do_populate_sdk</filename></link> task, see the - "<ulink url='&YOCTO_DOCS_ADT_URL;#optionally-building-a-toolchain-installer'>Optionally Building a Toolchain Installer</ulink>" - section in the Yocto Project Application Developer's Guide. + "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer'>Building an SDK Installer</ulink>" + section in the Yocto Project Software Development Kit (SDK) Developer's Guide. </para> </section> @@ -2734,8 +2721,9 @@ cross-development toolchain using the <link linkend='ref-tasks-populate_sdk'><filename>do_populate_sdk</filename></link> task, see the - "<ulink url='&YOCTO_DOCS_ADT_URL;#optionally-building-a-toolchain-installer'>Optionally Building a Toolchain Installer</ulink>" - section in the Yocto Project Application Developer's Guide. + "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer'>Building an SDK Installer</ulink>" + section in the Yocto Project Software Development Kit (SDK) Developer's + Guide. </para> </section> @@ -2869,66 +2857,6 @@ </para> </section> -<section id='ref-classes-qmake*'> - <title><filename>qmake*.bbclass</filename></title> - - <para> - The <filename>qmake*</filename> classes support recipes that - need to build software that uses Qt's <filename>qmake</filename> - build system and are comprised of the following: - <itemizedlist> - <listitem><para><emphasis><filename>qmake_base</filename>:</emphasis> - Provides base functionality for all versions of - <filename>qmake</filename>.</para></listitem> - <listitem><para><emphasis><filename>qmake2</filename>:</emphasis> - Extends base functionality for <filename>qmake</filename> 2.x as - used by Qt 4.x.</para></listitem> - </itemizedlist> - </para> - - <para> - If you need to set any configuration variables or pass any options to - <filename>qmake</filename>, you can add these to the - <link linkend='var-EXTRA_QMAKEVARS_PRE'><filename>EXTRA_QMAKEVARS_PRE</filename></link> - or - <link linkend='var-EXTRA_QMAKEVARS_POST'><filename>EXTRA_QMAKEVARS_POST</filename></link> - variables, depending on whether the arguments need to be before or - after the <filename>.pro</filename> file list on the command line, - respectively. - </para> - - <para> - By default, all <filename>.pro</filename> files are built. - If you want to specify your own subset of <filename>.pro</filename> - files to be built, specify them in the - <link linkend='var-QMAKE_PROFILES'><filename>QMAKE_PROFILES</filename></link> - variable. - </para> -</section> - -<section id='ref-classes-qt4*'> - <title><filename>qt4*.bbclass</filename></title> - - <para> - The <filename>qt4*</filename> classes support recipes that need to - build software that uses the Qt development framework version 4.x - and consist of the following: - <itemizedlist> - <listitem><para><emphasis><filename>qt4e</filename>:</emphasis> - Supports building against Qt/Embedded, which uses the - framebuffer for graphical output.</para></listitem> - <listitem><para><emphasis><filename>qt4x11</filename>:</emphasis> - Supports building against Qt/X11.</para></listitem> - </itemizedlist> - </para> - - <para> - The classes inherit the - <link linkend='ref-classes-qmake*'><filename>qmake2</filename></link> - class. - </para> -</section> - <section id='ref-classes-recipe_sanity'> <title><filename>recipe_sanity.bbclass</filename></title> @@ -2958,6 +2886,33 @@ </para> </section> +<section id='ref-classes-remove-libtool'> + <title><filename>remove-libtool.bbclass</filename></title> + + <para> + The <filename>remove-libtool</filename> class adds a post function + to the + <link linkend='ref-tasks-install'><filename>do_install</filename></link> + task to remove all <filename>.la</filename> files installed by + <filename>libtool</filename>. + Removing these files results in them being absent from both the + sysroot and target packages. + </para> + + <para> + If a recipe needs the <filename>.la</filename> files to be installed, + then the recipe can override the removal by setting + <filename>REMOVE_LIBTOOL_LA</filename> to "0" as follows: + <literallayout class='monospaced'> + REMOVE_LIBTOOL_LA = "0" + </literallayout> + <note> + The <filename>remove-libtool</filename> class is not enabled by + default. + </note> + </para> +</section> + <section id='ref-classes-report-error'> <title><filename>report-error.bbclass</filename></title> @@ -3026,6 +2981,10 @@ the root filesystem for an image and consist of the following classes: <itemizedlist> <listitem><para> + The <filename>rootfs-postcommands</filename> class, which + defines filesystem post-processing functions for image recipes. + </para></listitem> + <listitem><para> The <filename>rootfs_deb</filename> class, which supports creation of root filesystems for images built using <filename>.deb</filename> packages.</para></listitem> @@ -3225,10 +3184,10 @@ <title><filename>staging.bbclass</filename></title> <para> - The <filename>staging</filename> class provides support for staging - files into the sysroot during the + The <filename>staging</filename> class provides the <link linkend='ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></link> - task. + task, which stages files into the sysroot to make them available to + other recipes at build time. The class is enabled by default because it is inherited by the <link linkend='ref-classes-base'><filename>base</filename></link> class. @@ -3398,6 +3357,20 @@ </para> </section> +<section id='ref-classes-testsdk'> + <title><filename>testsdk.bbclass</filename></title> + + <para> + This class supports running automated tests against + software development kits (SDKs). + The <filename>testsdk</filename> class runs tests on an SDK when + called using the following: + <literallayout class='monospaced'> + $ bitbake -c testsdk image + </literallayout> + </para> +</section> + <section id='ref-classes-texinfo'> <title><filename>texinfo.bbclass</filename></title> @@ -3498,14 +3471,23 @@ <title><filename>uninative.bbclass</filename></title> <para> - Provides a means of reusing <filename>native/cross</filename> over - multiple distros. - <note> - Currently, the method used by the <filename>uninative</filename> - class is experimental. - </note> - For more information, see the commit message - <ulink url='http://cgit.openembedded.org/openembedded-core/commit/?id=e66c96ae9c7ba21ebd04a4807390f0031238a85a'>here</ulink>. + Attempts to isolate the build system from the host + distribution's C library in order to make re-use of native shared state + artifacts across different host distributions practical. + With this class enabled, a tarball containing a pre-built C library + is downloaded at the start of the build. + In the Poky reference distribution this is enabled by default + through + <filename>meta/conf/distro/include/yocto-uninative.inc</filename>. + Other distributions that do not derive from poky can also + "<filename>require conf/distro/include/yocto-uninative.inc</filename>" + to use this. + Alternatively if you prefer, you can build the uninative-tarball recipe + yourself, publish the resulting tarball (e.g. via HTTP) and set + <filename>UNINATIVE_URL</filename> and + <filename>UNINATIVE_CHECKSUM</filename> appropriately. + For an example, see the + <filename>meta/conf/distro/include/yocto-uninative.inc</filename>. </para> </section> diff --git a/yocto-poky/documentation/ref-manual/ref-features.xml b/yocto-poky/documentation/ref-manual/ref-features.xml index 798e0a2a1..fd7693500 100644 --- a/yocto-poky/documentation/ref-manual/ref-features.xml +++ b/yocto-poky/documentation/ref-manual/ref-features.xml @@ -308,8 +308,12 @@ <listitem><para><emphasis>nfs-server:</emphasis> Installs an NFS server. </para></listitem> - <listitem><para><emphasis>qt4-pkgs:</emphasis> - Supports Qt4/X11 and demo applications. + <listitem><para><emphasis>perf:</emphasis> + Installs profiling tools such as + <filename>perf</filename>, <filename>systemtap</filename>, + and <filename>LTTng</filename>. + For general information on user-space tools, 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>ssh-server-dropbear:</emphasis> Installs the Dropbear minimal SSH server. @@ -331,15 +335,6 @@ For information on tracing and profiling, see the <ulink url='&YOCTO_DOCS_PROF_URL;'>Yocto Project Profiling and Tracing Manual</ulink>. </para></listitem> - <listitem><para><emphasis>tools-profile:</emphasis> - Installs profiling tools such as - <filename>oprofile</filename>, <filename>exmap</filename>, - and <filename>LTTng</filename>. - For general information on user-space tools, see the - "<ulink url='&YOCTO_DOCS_ADT_URL;#user-space-tools'>User-Space Tools</ulink>" - section in the Yocto Project Application Developer's - Guide. - </para></listitem> <listitem><para><emphasis>tools-sdk:</emphasis> Installs a full SDK that runs on the device. </para></listitem> diff --git a/yocto-poky/documentation/ref-manual/ref-images.xml b/yocto-poky/documentation/ref-manual/ref-images.xml index d15ca5b93..69b58f6ab 100644 --- a/yocto-poky/documentation/ref-manual/ref-images.xml +++ b/yocto-poky/documentation/ref-manual/ref-images.xml @@ -80,7 +80,7 @@ </para></listitem> <listitem><para><filename>core-image-lsb-sdk</filename>: A <filename>core-image-lsb</filename> that includes everything in - meta-toolchain but also includes development headers and libraries + the cross-toolchain but also includes development headers and libraries to form a complete standalone SDK. This image requires a distribution configuration that enables LSB compliance (e.g. <filename>poky-lsb</filename>). @@ -114,7 +114,7 @@ tools appropriate for real-time use.</para></listitem> <listitem><para><filename>core-image-rt-sdk</filename>: A <filename>core-image-rt</filename> image that includes everything in - <filename>meta-toolchain</filename>. + the cross-toolchain. The image also includes development headers and libraries to form a complete stand-alone SDK and is suitable for development using the target. </para></listitem> @@ -132,7 +132,8 @@ This image was formerly <filename>core-image-sdk</filename>. </para></listitem> <listitem><para><filename>core-image-sato-sdk</filename>: - A <filename>core-image-sato</filename> image that includes everything in meta-toolchain. + A <filename>core-image-sato</filename> image that includes everything in + the cross-toolchain. The image also includes development headers and libraries to form a complete standalone SDK and is suitable for development using the target.</para></listitem> <listitem><para><filename>core-image-testmaster</filename>: @@ -158,9 +159,6 @@ <listitem><para><filename>core-image-x11</filename>: A very basic X11 image with a terminal. </para></listitem> - <listitem><para><filename>qt4e-demo-image</filename>: - An image that launches into the demo application for the embedded - (not based on X11) version of Qt.</para></listitem> </itemizedlist> </para> </chapter> diff --git a/yocto-poky/documentation/ref-manual/ref-manual.xml b/yocto-poky/documentation/ref-manual/ref-manual.xml index a296b9bc3..6834d5f0a 100644 --- a/yocto-poky/documentation/ref-manual/ref-manual.xml +++ b/yocto-poky/documentation/ref-manual/ref-manual.xml @@ -97,6 +97,11 @@ <date>October 2015</date> <revremark>Released with the Yocto Project 2.0 Release.</revremark> </revision> + <revision> + <revnumber>2.1</revnumber> + <date>April 2016</date> + <revremark>Released with the Yocto Project 2.1 Release.</revremark> + </revision> </revhistory> <copyright> diff --git a/yocto-poky/documentation/ref-manual/ref-qa-checks.xml b/yocto-poky/documentation/ref-manual/ref-qa-checks.xml index 38689b992..4fcf1db61 100644 --- a/yocto-poky/documentation/ref-manual/ref-qa-checks.xml +++ b/yocto-poky/documentation/ref-manual/ref-qa-checks.xml @@ -81,11 +81,13 @@ can be found then it should be implemented. I can't find one at the moment. <para> The specified package contains files in - <filename>/usr/libexec</filename>. - By default, <filename>libexecdir</filename> is set to - "${libdir}/${BPN}" rather than to "/usr/libexec". - Thus, installing to <filename>/usr/libexec</filename> - is likely not desirable. + <filename>/usr/libexec</filename> when the distro + configuration uses a different path for + <filename><libexecdir></filename> + By default, <filename><libexecdir></filename> is + <filename>$prefix/libexec</filename>. + However, this default can be changed (e.g. + <filename>${libdir}</filename>). </para> <para> diff --git a/yocto-poky/documentation/ref-manual/ref-structure.xml b/yocto-poky/documentation/ref-manual/ref-structure.xml index 48e39212a..e51ceb1bf 100644 --- a/yocto-poky/documentation/ref-manual/ref-structure.xml +++ b/yocto-poky/documentation/ref-manual/ref-structure.xml @@ -123,8 +123,8 @@ </para> </section> - <section id='structure-core-meta-yocto'> - <title><filename>meta-yocto/</filename></title> + <section id='structure-core-meta-poky'> + <title><filename>meta-poky/</filename></title> <para> This directory contains the configuration for the Poky @@ -227,14 +227,13 @@ core-image-minimal core-image-sato meta-toolchain - adt-installer meta-ide-support You can also run generated qemu images with a command like 'runqemu qemux86' </literallayout> The script gets its default list of common targets from the <filename>conf-notes.txt</filename> file, which is found in the - <filename>meta-yocto</filename> directory within the + <filename>meta-poky</filename> directory within the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. Should you have custom distributions, it is very easy to modify this configuration file to include your targets for your @@ -261,7 +260,7 @@ </literallayout> The OpenEmbedded build system uses the template configuration files, which are found by default in the - <filename>meta-yocto/conf</filename> directory in the + <filename>meta-poky/conf</filename> directory in the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. See the "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory'>Creating a Custom Template Configuration Directory</ulink>" @@ -366,7 +365,6 @@ core-image-minimal core-image-sato meta-toolchain - adt-installer meta-ide-support You can also run generated qemu images with a command like 'runqemu qemux86' @@ -375,7 +373,7 @@ </literallayout> The script gets its default list of common targets from the <filename>conf-notes.txt</filename> file, which is found in the - <filename>meta-yocto</filename> directory within the + <filename>meta-poky</filename> directory within the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. Should you have custom distributions, it is very easy to modify this configuration file to include your targets for your @@ -411,7 +409,7 @@ <para> The OpenEmbedded build system uses the template configuration files, which are found by default in the - <filename>meta-yocto/conf</filename> directory in the + <filename>meta-poky/conf</filename> directory in the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. See the "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory'>Creating a Custom Template Configuration Directory</ulink>" @@ -515,7 +513,7 @@ <para> The source <filename>local.conf.sample</filename> file used depends on the <filename>$TEMPLATECONF</filename> script variable, - which defaults to <filename>meta-yocto/conf</filename> + which defaults to <filename>meta-poky/conf</filename> when you are building from the Yocto Project development environment and defaults to <filename>meta/conf</filename> when you are building from the OpenEmbedded Core environment. @@ -538,7 +536,7 @@ <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. You can find the Yocto Project version of the <filename>local.conf.sample</filename> file in the - <filename>meta-yocto/conf</filename> directory. + <filename>meta-poky/conf</filename> directory. </note> </para> </section> @@ -569,7 +567,7 @@ <para> The source <filename>bblayers.conf.sample</filename> file used depends on the <filename>$TEMPLATECONF</filename> script variable, - which defaults to <filename>meta-yocto/conf</filename> + which defaults to <filename>meta-poky/conf</filename> when you are building from the Yocto Project development environment and defaults to <filename>meta/conf</filename> when you are building from the OpenEmbedded Core environment. @@ -590,7 +588,7 @@ <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. You can find the Yocto Project version of the <filename>bblayers.conf.sample</filename> file in the - <filename>meta-yocto/conf</filename> directory. + <filename>meta-poky/conf</filename> directory. </note> </para> </section> @@ -738,8 +736,7 @@ <para> Be careful when deleting files in this directory. You can safely delete old images from this directory (e.g. - <filename>core-image-*</filename>, <filename>hob-image-*</filename>, - etc.). + <filename>core-image-*</filename>). However, the kernel (<filename>*zImage*</filename>, <filename>*uImage*</filename>, etc.), bootloader and other supplementary files might be deployed here prior to building an image. @@ -767,8 +764,8 @@ toolchain installer scripts, which when executed, install the sysroot that matches your target hardware. You can find out more about these installers in the - "<ulink url='&YOCTO_DOCS_ADT_URL;#optionally-building-a-toolchain-installer'>Optionally Building a Toolchain Installer</ulink>" - section in the Yocto Project Application Developer's Guide. + "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer'>Building an SDK Installer</ulink>" + section in the Yocto Project Software Development Kit (SDK) Developer's Guide. </para> </section> @@ -1091,14 +1088,6 @@ </para> </section> - <section id='structure-meta-recipes-qt'> - <title><filename>meta/recipes-qt/</filename></title> - - <para> - This directory contains all things related to the Qt application framework. - </para> - </section> - <section id='structure-meta-recipes-rt'> <title><filename>meta/recipes-rt/</filename></title> diff --git a/yocto-poky/documentation/ref-manual/ref-tasks.xml b/yocto-poky/documentation/ref-manual/ref-tasks.xml index 21403c072..c46debb55 100644 --- a/yocto-poky/documentation/ref-manual/ref-tasks.xml +++ b/yocto-poky/documentation/ref-manual/ref-tasks.xml @@ -31,6 +31,36 @@ </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> + + <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-compile'> <title><filename>do_compile</filename></title> @@ -87,6 +117,32 @@ </para> </section> + <section id='ref-tasks-distrodata'> + <title><filename>do_distrodata</filename></title> + + <para> + Provides information about the recipe. + </para> + + <para> + The <filename>distrodata</filename> task is included as part of the + <link linkend='ref-classes-distrodata'><filename>distrodata</filename></link> + class. + </para> + + <para> + To build the <filename>distrodata</filename> task, use the + <filename>bitbake</filename> command with the "-c" option and + task name: + <literallayout class='monospaced'> + $ bitbake core-image-minimal -c distrodata + </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-fetch'> <title><filename>do_fetch</filename></title> @@ -99,6 +155,60 @@ </para> </section> + <section id='ref-tasks-image'> + <title><filename>do_image</filename></title> + + <para> + Starts the image generation process. + The <filename>do_image</filename> task runs after the + OpenEmbedded build system has run the + <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link> + task during which packages are identified for installation into + the image and the root filesystem is created, complete with + post-processing. + </para> + + <para> + The <filename>do_image</filename> task performs pre-processing + on the image through the + <link linkend='var-IMAGE_PREPROCESS_COMMAND'><filename>IMAGE_PREPROCESS_COMMAND</filename></link> + and dynamically generates supporting + <filename>do_image_*</filename> tasks as needed. + </para> + + <para> + For more information on image creation, see the + "<link linkend='image-generation-dev-environment'>Image Generation</link>" + section. + </para> + </section> + + <section id='ref-tasks-image-complete'> + <title><filename>do_image_complete</filename></title> + + <para> + Completes the image generation process. + The <filename>do_image_complete</filename> task runs after the + OpenEmbedded build system has run the + <link linkend='ref-tasks-rootfs'><filename>do_image</filename></link> + task during which image pre-processing occurs and through + dynamically generated <filename>do_image_*</filename> tasks the + image is constructed. + </para> + + <para> + The <filename>do_image_complete</filename> task performs + post-processing on the image through the + <link linkend='var-IMAGE_POSTPROCESS_COMMAND'><filename>IMAGE_POSTPROCESS_COMMAND</filename></link>. + </para> + + <para> + For more information on image creation, see the + "<link linkend='image-generation-dev-environment'>Image Generation</link>" + section. + </para> + </section> + <section id='ref-tasks-install'> <title><filename>do_install</filename></title> @@ -239,10 +349,16 @@ <title><filename>do_populate_sysroot</filename></title> <para> - Copies a subset of files installed by the + Copies a subset of the files installed by the <link linkend='ref-tasks-install'><filename>do_install</filename></link> - task into the sysroot in order to make them available to other - recipes. + 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. </para> <para> @@ -700,15 +816,6 @@ The following sections describe miscellaneous tasks. </para> - <section id='ref-tasks-generate_qt_config_file'> - <title><filename>do_generate_qt_config_file</filename></title> - - <para> - Writes a <filename>qt.conf</filename> configuration - file used for building a Qt-based application. - </para> - </section> - <section id='ref-tasks-spdx'> <title><filename>do_spdx</filename></title> diff --git a/yocto-poky/documentation/ref-manual/ref-variables.xml b/yocto-poky/documentation/ref-manual/ref-variables.xml index 0b2c426b6..d55bccdc6 100644 --- a/yocto-poky/documentation/ref-manual/ref-variables.xml +++ b/yocto-poky/documentation/ref-manual/ref-variables.xml @@ -32,7 +32,7 @@ <!-- <link linkend='var-glossary-n'>N</link> --> <link linkend='var-OBJCOPY'>O</link> <link linkend='var-P'>P</link> - <link linkend='var-QMAKE_PROFILES'>Q</link> +<!-- <link linkend='var-glossary-q'>Q</link> --> <link linkend='var-RANLIB'>R</link> <link linkend='var-S'>S</link> <link linkend='var-T'>T</link> @@ -1130,24 +1130,11 @@ <literallayout class='monospaced'> BBLAYERS = " \ /home/scottrif/poky/meta \ - /home/scottrif/poky/meta-yocto \ + /home/scottrif/poky/meta-poky \ /home/scottrif/poky/meta-yocto-bsp \ /home/scottrif/poky/meta-mykernel \ " - - BBLAYERS_NON_REMOVABLE ?= " \ - /home/scottrif/poky/meta \ - /home/scottrif/poky/meta-yocto \ - " </literallayout> - <note> - The - <link linkend='var-BBLAYERS_NON_REMOVABLE'><filename>BBLAYERS_NON_REMOVABLE</filename></link> - variable exists only for - <ulink url='https://www.yoctoproject.org/tools-resources/projects/hob'>Hob</ulink>. - The OpenEmbedded build system does not use this - variable. - </note> </para> <para> @@ -1157,60 +1144,15 @@ </glossdef> </glossentry> - <glossentry id='var-BBLAYERS_NON_REMOVABLE'><glossterm>BBLAYERS_NON_REMOVABLE</glossterm> - <info> - BBLAYERS_NON_REMOVABLE[doc] = "Lists core layers that cannot be removed from the bblayers.conf file." - </info> - <glossdef> - <para role="glossdeffirst"> -<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - Lists core layers that cannot be removed from the - <filename>bblayers.conf</filename> file during a build - using the - <ulink url='https://www.yoctoproject.org/tools-resources/projects/hob'>Hob</ulink>. - <note> - When building an image outside of Hob, the OpenEmbedded - build system ignores this variable. - </note> - </para> - - <para> - In order for BitBake to build your image using Hob, your - <filename>bblayers.conf</filename> file must include the - <filename>meta</filename> and <filename>meta-yocto</filename> - core layers. - Here is an example that shows these two layers listed in - the <filename>BBLAYERS_NON_REMOVABLE</filename> statement: - <literallayout class='monospaced'> - BBLAYERS = " \ - /home/scottrif/poky/meta \ - /home/scottrif/poky/meta-yocto \ - /home/scottrif/poky/meta-yocto-bsp \ - /home/scottrif/poky/meta-mykernel \ - " - - BBLAYERS_NON_REMOVABLE ?= " \ - /home/scottrif/poky/meta \ - /home/scottrif/poky/meta-yocto \ - " - </literallayout> - </para> - </glossdef> - </glossentry> - <glossentry id='var-BBMASK'><glossterm>BBMASK</glossterm> <info> - BBMASK[doc] = "Prevents BitBake from processing specific recipes or recipe append files. Use the BBMASK variable from within conf/local.conf." + BBMASK[doc] = "Prevents BitBake from processing specific recipes or recipe append files." </info> <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Prevents BitBake from processing recipes and recipe append files. - Use the <filename>BBMASK</filename> variable from within the - <filename>conf/local.conf</filename> file found - in the - <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. </para> <para> @@ -1218,14 +1160,14 @@ to "hide" these <filename>.bb</filename> and <filename>.bbappend</filename> files. BitBake ignores any recipe or recipe append files that - match the expression. + match any of the expressions. It is as if BitBake does not see them at all. Consequently, matching files are not parsed or otherwise used by BitBake.</para> <para> - The value you provide is passed to Python's regular + The values you provide are passed to Python's regular expression compiler. - The expression is compared against the full paths to + The expressions are compared against the full paths to the files. For complete syntax information, see Python's documentation at @@ -1241,18 +1183,16 @@ BBMASK = "meta-ti/recipes-misc/" </literallayout> If you want to mask out multiple directories or recipes, - use the vertical bar to separate the regular expression - fragments. + you can specify multiple regular expression fragments. This next example masks out multiple directories and individual recipes: <literallayout class='monospaced'> - BBMASK = "meta-ti/recipes-misc/|meta-ti/recipes-ti/packagegroup/" - BBMASK .= "|.*meta-oe/recipes-support/" - BBMASK .= "|.*openldap" - BBMASK .= "|.*opencv" - BBMASK .= "|.*lzma" + BBMASK += "/meta-ti/recipes-misc/ meta-ti/recipes-ti/packagegroup/" + BBMASK += "/meta-oe/recipes-support/" + BBMASK += "/meta-foo/.*/openldap" + BBMASK += "opencv.*\.bbappend" + BBMASK += "lzma" </literallayout> - Notice how the vertical bar is used to append the fragments. <note> When specifying a directory name, use the trailing slash character to ensure you match just that directory @@ -1402,15 +1342,22 @@ <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> The bare name of the recipe. - This variable is a version of the <link linkend='var-PN'><filename>PN</filename></link> variable - but removes common suffixes such as "-native" and "-cross" as well - as removes common prefixes such as multilib's "lib64-" and "lib32-". + 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 + <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. + <link linkend='var-SPECIAL_PKGSUFFIX'><filename>SPECIAL_PKGSUFFIX</filename></link> + variable. The exact list of prefixes removed is specified by the - <link linkend='var-MLPREFIX'><filename>MLPREFIX</filename></link> variable. + <link linkend='var-MLPREFIX'><filename>MLPREFIX</filename></link> + variable. Prefixes are removed for <filename>multilib</filename> - and <filename>nativesdk</filename> cases. + and <filename>nativesdk-</filename> cases. </para> </glossdef> </glossentry> @@ -1473,7 +1420,7 @@ Specifies the flags to pass to the C pre-processor (i.e. to both the C and the C++ compilers) when building for the build host. - When building in the <filename>native</filename> context, + When building in the <filename>-native</filename> context, <link linkend='var-CPPFLAGS'><filename>CPPFLAGS</filename></link> is set to the value of this variable by default. </para> @@ -1489,7 +1436,7 @@ <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the flags to pass to the C++ compiler when building for the build host. - When building in the <filename>native</filename> context, + When building in the <filename>-native</filename> context, <link linkend='var-CXXFLAGS'><filename>CXXFLAGS</filename></link> is set to the value of this variable by default. </para> @@ -1564,7 +1511,7 @@ The OpenEmbedded build system uses the <filename>BUILD_PREFIX</filename> value to set the <link linkend='var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></link> - when building for native recipes. + when building for <filename>native</filename> recipes. </para> </glossdef> </glossentry> @@ -1845,7 +1792,7 @@ <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the flags to pass to the C compiler when building for the SDK. - When building in the <filename>nativesdk</filename> + When building in the <filename>nativesdk-</filename> context, <link linkend='var-CFLAGS'><filename>CFLAGS</filename></link> is set to the value of this variable by default. @@ -1863,7 +1810,7 @@ Specifies the flags to pass to the C pre-processor (i.e. to both the C and the C++ compilers) when building for the SDK. - When building in the <filename>nativesdk</filename> + When building in the <filename>nativesdk-</filename> context, <link linkend='var-CPPFLAGS'><filename>CPPFLAGS</filename></link> is set to the value of this variable by default. @@ -1880,7 +1827,7 @@ <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the flags to pass to the C++ compiler when building for the SDK. - When building in the <filename>nativesdk</filename> + When building in the <filename>nativesdk-</filename> context, <link linkend='var-CXXFLAGS'><filename>CXXFLAGS</filename></link> is set to the value of this variable by default. @@ -2037,7 +1984,7 @@ 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 native case: + only when building for the <filename>-native</filename> case: <literallayout class='monospaced'> DEPENDS_append_class-native = " python-native" </literallayout> @@ -2354,7 +2301,20 @@ <filename>/usr/share/common-licenses</filename>, for each package. The license files are placed - in directories within the image itself. + in directories within the image itself during build time. + <note> + The <filename>COPY_LIC_DIRS</filename> does not + offer a path for adding licenses for newly installed + packages to an image, which might be most suitable + for read-only filesystems that cannot be upgraded. + See the + <link linkend='var-LICENSE_CREATE_PACKAGE'><filename>LICENSE_CREATE_PACKAGE</filename></link> + variable for additional information. + You can also reference the + "<ulink url='&YOCTO_DOCS_DEV_URL;#providing-license-text'>Providing License Text</ulink>" + section in the Yocto Project Development Manual for + information on providing license text. + </note> </para> </glossdef> </glossentry> @@ -2369,7 +2329,20 @@ If set to "1", the OpenEmbedded build system copies the license manifest for the image to <filename>/usr/share/common-licenses/license.manifest</filename> - within the image itself. + within the image itself during build time. + <note> + The <filename>COPY_LIC_MANIFEST</filename> does not + offer a path for adding licenses for newly installed + packages to an image, which might be most suitable + for read-only filesystems that cannot be upgraded. + See the + <link linkend='var-LICENSE_CREATE_PACKAGE'><filename>LICENSE_CREATE_PACKAGE</filename></link> + variable for additional information. + You can also reference the + "<ulink url='&YOCTO_DOCS_DEV_URL;#providing-license-text'>Providing License Text</ulink>" + section in the Yocto Project Development Manual for + information on providing license text. + </note> </para> </glossdef> </glossentry> @@ -2420,6 +2393,35 @@ </glossdef> </glossentry> + <glossentry id='var-COREBASE_FILES'><glossterm>COREBASE_FILES</glossterm> + <info> + COREBASE_FILES[doc] = "Lists files from the COREBASE directory that should be copied other than the layers listed in the bblayers.conf file." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Lists files from the + <link linkend='var-COREBASE'><filename>COREBASE</filename></link> + directory that should be copied other than the layers + listed in the <filename>bblayers.conf</filename> file. + The <filename>COREBASE_FILES</filename> variable exists + for the purpose of copying metadata from the + OpenEmbedded build system into the extensible + SDK. + </para> + + <para> + Explicitly listing files in <filename>COREBASE</filename> + is needed because it typically contains build + directories and other files that should not normally + be copied into the extensible SDK. + Consequently, the value of + <filename>COREBASE_FILES</filename> is used in order to + only copy the files that are actually needed. + </para> + </glossdef> + </glossentry> + <glossentry id='var-CPP'><glossterm>CPP</glossterm> <info> CPP[doc] = "Minimum command and arguments to run the C preprocessor." @@ -2547,7 +2549,7 @@ <listitem><para> <link linkend='var-BUILDSDK_CXXFLAGS'><filename>BUILDSDK_CXXFLAGS</filename></link> when building for an SDK (i.e. - <filename>nativesdk</filename>) + <filename>nativesdk-</filename>) </para></listitem> </itemizedlist> </para> @@ -3110,7 +3112,7 @@ For example, the distribution configuration file for the Poky distribution is named <filename>poky.conf</filename> and resides in the - <filename>meta-yocto/conf/distro</filename> directory of + <filename>meta-poky/conf/distro</filename> directory of the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. </para> @@ -3413,6 +3415,9 @@ see this specific question in the "<link linkend='how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>FAQ</link>" chapter. + You can also refer to the + "<ulink url='&YOCTO_WIKI_URL;/wiki/Working_Behind_a_Network_Proxy'>Working Behind a Network Proxy</ulink>" + Wiki page. </para> </glossdef> </glossentry> @@ -3814,9 +3819,6 @@ "tools-debug" - Adds debugging tools such as gdb and strace. -"tools-profile" - Adds profiling tools such as oprofile, - exmap, lttng and valgrind (x86 only). - "tools-sdk" - Adds development tools such as gcc, make, pkgconfig and so forth. @@ -3924,6 +3926,12 @@ <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Additional GNU <filename>make</filename> options. </para> + + <para> + Because the <filename>EXTRA_OEMAKE</filename> defaults to + "", you need to set the variable to specify any required + GNU options. + </para> </glossdef> </glossentry> @@ -3943,50 +3951,6 @@ </glossdef> </glossentry> - <glossentry id='var-EXTRA_QMAKEVARS_POST'><glossterm>EXTRA_QMAKEVARS_POST</glossterm> - <info> - EXTRA_QMAKEVARS_POST[doc] = "Configuration variables or options you want to pass to qmake when the arguments need to be after the .pro file list on the command line." - </info> - <glossdef> - <para role="glossdeffirst"> -<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - Configuration variables or options you want to pass to - <filename>qmake</filename>. - Use this variable when the arguments need to be after the - <filename>.pro</filename> file list on the command line. - </para> - - <para> - This variable is used with recipes that inherit the - <link linkend='ref-classes-qmake*'><filename>qmake_base</filename></link> - class or other classes that inherit - <filename>qmake_base</filename>. - </para> - </glossdef> - </glossentry> - - <glossentry id='var-EXTRA_QMAKEVARS_PRE'><glossterm>EXTRA_QMAKEVARS_PRE</glossterm> - <info> - EXTRA_QMAKEVARS_PRE[doc] = "Configuration variables or options you want to pass to qmake when the arguments need to be before the .pro file list on the command line." - </info> - <glossdef> - <para role="glossdeffirst"> -<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - Configuration variables or options you want to pass to - <filename>qmake</filename>. - Use this variable when the arguments need to be before the - <filename>.pro</filename> file list on the command line. - </para> - - <para> - This variable is used with recipes that inherit the - <link linkend='ref-classes-qmake*'><filename>qmake_base</filename></link> - class or other classes that inherit - <filename>qmake_base</filename>. - </para> - </glossdef> - </glossentry> - <glossentry id='var-EXTRA_USERS_PARAMS'><glossterm>EXTRA_USERS_PARAMS</glossterm> <info> EXTRA_USERS_PARAMS[doc] = "When a recipe inherits the extrausers class, this variable provides image level user and group operations." @@ -4760,12 +4724,12 @@ <listitem><para> <filename>BUILD_CC_ARCH</filename> when building for the build host (i.e. - <filename>native</filename>) + <filename>-native</filename>) </para></listitem> <listitem><para> <filename>BUILDSDK_CC_ARCH</filename> when building for an SDK (i.e. - <filename>nativesdk</filename>) + <filename>nativesdk-</filename>) </para></listitem> </itemizedlist> </para> @@ -5523,7 +5487,7 @@ <para> The - <link linkend='ref-classes-populate-sdk-*'><filename>package_sdk_base</filename></link> + <link linkend='ref-classes-populate-sdk-*'><filename>populate_sdk_*</filename></link> and <link linkend='ref-classes-image'><filename>image</filename></link> classes use the <filename>IMAGE_PKGTYPE</filename> for @@ -5916,6 +5880,43 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> + <glossentry id='var-INHERIT'><glossterm>INHERIT</glossterm> + <info> + INHERIT[doc] = "Causes the named class to be inherited at this point during parsing. The variable is only valid in configuration files." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Causes the named class to be inherited at + this point during parsing. + The variable is only valid in configuration files. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-INHERIT_DISTRO'><glossterm>INHERIT_DISTRO</glossterm> + <info> + INHERIT_DISTRO[doc] = "Lists classes that will be inherited at the distribution level. It is unlikely that you want to edit this variable." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Lists classes that will be inherited at the + distribution level. + It is unlikely that you want to edit this variable. + </para> + + <para> + The default value of the variable is set as follows in the + <filename>meta/conf/distro/defaultsetup.conf</filename> + file: + <literallayout class='monospaced'> + INHERIT_DISTRO ?= "debian devshell sstate license" + </literallayout> + </para> + </glossdef> + </glossentry> + <glossentry id='var-INHIBIT_DEFAULT_DEPS'><glossterm>INHIBIT_DEFAULT_DEPS</glossterm> <info> INHIBIT_DEFAULT_DEPS[doc] = "Prevents the default dependencies, namely the C compiler and standard C library (libc), from being added to DEPENDS." @@ -5980,43 +5981,6 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> - <glossentry id='var-INHERIT'><glossterm>INHERIT</glossterm> - <info> - INHERIT[doc] = "Causes the named class to be inherited at this point during parsing. The variable is only valid in configuration files." - </info> - <glossdef> - <para role="glossdeffirst"> -<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - Causes the named class to be inherited at - this point during parsing. - The variable is only valid in configuration files. - </para> - </glossdef> - </glossentry> - - <glossentry id='var-INHERIT_DISTRO'><glossterm>INHERIT_DISTRO</glossterm> - <info> - INHERIT_DISTRO[doc] = "Lists classes that will be inherited at the distribution level. It is unlikely that you want to edit this variable." - </info> - <glossdef> - <para role="glossdeffirst"> -<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - Lists classes that will be inherited at the - distribution level. - It is unlikely that you want to edit this variable. - </para> - - <para> - The default value of the variable is set as follows in the - <filename>meta/conf/distro/defaultsetup.conf</filename> - file: - <literallayout class='monospaced'> - INHERIT_DISTRO ?= "debian devshell sstate license" - </literallayout> - </para> - </glossdef> - </glossentry> - <glossentry id='var-INITRAMFS_FSTYPES'><glossterm>INITRAMFS_FSTYPES</glossterm> <info> INITRAMFS_FSTYPES[doc] = "Defines the format for the output image of an initial RAM disk (initramfs), which is used during boot." @@ -6071,7 +6035,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <para> See the - <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-yocto/conf/local.conf.sample.extended'><filename>local.conf.sample.extended</filename></ulink> + <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> @@ -6125,7 +6089,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" You cannot set the variable in a recipe file. </note> See the - <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-yocto/conf/local.conf.sample.extended'><filename>local.conf.sample.extended</filename></ulink> + <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. </para> </glossdef> @@ -6145,7 +6109,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <para> The <filename>INITRD</filename> variable is an optional variable used with the - <link linkend='ref-classes-bootimg'><filename>bootimg</filename></link> + <link linkend='ref-classes-image-live'><filename>image-live</filename></link> class. </para> </glossdef> @@ -6277,6 +6241,22 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> + <glossentry id='var-INSTALL_TIMEZONE_FILE'><glossterm>INSTALL_TIMEZONE_FILE</glossterm> + <info> + INSTALL_TIMEZONE_FILE[doc] = "Enables installation of the /etc/timezone file." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + By default, the <filename>tzdata</filename> recipe packages + an <filename>/etc/timezone</filename> file. + Set the <filename>INSTALL_TIMEZONE_FILE</filename> + variable to "0" at the configuration level to disable this + behavior. + </para> + </glossdef> + </glossentry> + <glossentry id='var-IPK_FEED_URIS'><glossterm>IPK_FEED_URIS</glossterm> <info> IPK_FEED_URIS[doc] = "List of ipkg feed records to put into generated image." @@ -7179,6 +7159,49 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> + <glossentry id='var-LICENSE_CREATE_PACKAGE'><glossterm>LICENSE_CREATE_PACKAGE</glossterm> + <info> + LICENSE_CREATE_PACKAGE[doc] = "Creates an extra package (i.e. ${PN}-lic) for each recipe and adds that package to the RRECOMMENDS+${PN}." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Setting <filename>LICENSE_CREATE_PACKAGE</filename> + to "1" causes the OpenEmbedded build system to create + an extra package (i.e. + <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}-lic</filename>) + for each recipe and to add those packages to the + <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link><filename>_${PN}</filename>. + </para> + + <para> + The <filename>${PN}-lic</filename> package installs a + directory in <filename>/usr/share/licenses</filename> + named <filename>${PN}</filename>, which is the recipe's + base name, and installs files in that directory that + contain license and copyright information (i.e. copies of + the appropriate license files from + <filename>meta/common-licenses</filename> that match the + licenses specified in the + <link linkend='var-LICENSE'><filename>LICENSE</filename></link> + variable of the recipe metadata and copies of files marked + in + <link linkend='var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></link> + as containing license text). + </para> + + <para> + For related information on providing license text, see the + <link linkend='var-COPY_LIC_DIRS'><filename>COPY_LIC_DIRS</filename></link> + variable, the + <link linkend='var-COPY_LIC_MANIFEST'><filename>COPY_LIC_MANIFEST</filename></link> + variable, and the + "<ulink url='&YOCTO_DOCS_DEV_URL;#providing-license-text'>Providing License Text</ulink>" + section in the Yocto Project Development Manual. + </para> + </glossdef> + </glossentry> + <glossentry id='var-LICENSE_FLAGS'><glossterm>LICENSE_FLAGS</glossterm> <info> LICENSE_FLAGS[doc] = "Specifies additional flags for a recipe you must whitelist through LICENSE_FLAGS_WHITELIST in order to allow the recipe to be built." @@ -7774,7 +7797,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" is "poky", the default value for <filename>MIRRORS</filename> is defined in the <filename>conf/distro/poky.conf</filename> file in the - <filename>meta-yocto</filename> Git repository. + <filename>meta-poky</filename> Git repository. </para> </glossdef> </glossentry> @@ -8066,7 +8089,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" Causes the OpenEmbedded build system to skip building the <filename>.hddimg</filename> image. The <filename>NOHDD</filename> variable is used with the - <link linkend='ref-classes-bootimg'><filename>bootimg</filename></link> + <link linkend='ref-classes-image-live'><filename>image-live</filename></link> class. Set the variable to "1" to prevent the <filename>.hddimg</filename> image from being built. @@ -8084,7 +8107,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" Causes the OpenEmbedded build system to skip building the ISO image. The <filename>NOISO</filename> variable is used with the - <link linkend='ref-classes-bootimg'><filename>bootimg</filename></link> + <link linkend='ref-classes-image-live'><filename>image-live</filename></link> class. Set the variable to "1" to prevent the ISO image from being built. @@ -8176,6 +8199,28 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> + <glossentry id='var-OE_INIT_ENV_SCRIPT'><glossterm>OE_INIT_ENV_SCRIPT</glossterm> + <info> + OE_INIT_ENV_SCRIPT[doc] = "The name of the build environment setup script for the purposes of setting up the environment within the extensible SDK." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + The name of the build environment setup script for the + purposes of setting up the environment within the + extensible SDK. + The default value is "oe-init-build-env". + </para> + + <para> + If you use a custom script to set up your build + environment, set the + <filename>OE_INIT_ENV_SCRIPT</filename> variable to its + name. + </para> + </glossdef> + </glossentry> + <glossentry id='var-OE_TERMINAL'><glossterm>OE_TERMINAL</glossterm> <info> OE_TERMINAL[doc] = "Controls how the OpenEmbedded build system spawns interactive terminals on the host development system." @@ -9539,6 +9584,17 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86" PREFERRED_PROVIDER_virtual/libgl ?= "mesa" </literallayout> + <note> + If you set <filename>PREFERRED_PROVIDER</filename> + for a <filename>virtual/*</filename> item, then any + recipe that + <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link> + that item that is not selected by + <filename>PREFERRED_PROVIDER</filename> is prevented + from building, which is usually desirable since this + mechanism is designed to select between mutually + exclusive alternative providers. + </note> </para> </glossdef> </glossentry> @@ -9566,6 +9622,23 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" PREFERRED_VERSION_python = "2.7.3" PREFERRED_VERSION_linux-yocto = "3.19%" </literallayout> + Sometimes the <filename>PREFERRED_VERSION</filename> + variable can be set by configuration files in a way that + is hard to change. + You can use + <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link> + to set a machine-specific override. + Here is an example: + <literallayout class='monospaced'> + PREFERRED_VERSION_linux-yocto_qemux86 = "3.4%" + </literallayout> + Although not recommended, worst case, you can also use the + "forcevariable" override, which is the strongest override + possible. + Here is an example: + <literallayout class='monospaced'> + PREFERRED_VERSION_linux-yocto_forcevariable = "3.4%" + </literallayout> </para> </glossdef> </glossentry> @@ -9594,7 +9667,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" is "poky", the default value for <filename>PREMIRRORS</filename> is defined in the <filename>conf/distro/poky.conf</filename> file in the - <filename>meta-yocto</filename> Git repository. + <filename>meta-poky</filename> Git repository. </para> <para> @@ -9854,35 +9927,6 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdiv> - <glossdiv id='var-glossary-q'><title>Q</title> - - <glossentry id='var-QMAKE_PROFILES'><glossterm>QMAKE_PROFILES</glossterm> - <info> - QMAKE_PROFILES[doc] = "Specifies your own subset of .pro files to be built for use with qmake." - </info> - <glossdef> - <para role="glossdeffirst"> -<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - Specifies your own subset of <filename>.pro</filename> - files to be built for use with - <filename>qmake</filename>. - If you do not set this variable, all - <filename>.pro</filename> files in the directory pointed to - by <link linkend='var-S'><filename>S</filename></link> - will be built by default. - </para> - - <para> - This variable is used with recipes that inherit the - <link linkend='ref-classes-qmake*'><filename>qmake_base</filename></link> - class or other classes that inherit - <filename>qmake_base</filename>. - </para> - </glossdef> - </glossentry> - - </glossdiv> - <glossdiv id='var-glossary-r'><title>R</title> <glossentry id='var-RANLIB'><glossterm>RANLIB</glossterm> @@ -10195,7 +10239,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <para> The <filename>ROOTFS</filename> variable is an optional variable used with the - <link linkend='ref-classes-bootimg'><filename>bootimg</filename></link> + <link linkend='ref-classes-image-live'><filename>image-live</filename></link> class. </para> </glossdef> @@ -10532,17 +10576,16 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" The location in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> where unpacked recipe source code resides. - This location is within the work directory - (<filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>), - which is not static. - The unpacked source location depends on the recipe name - (<filename><link linkend='var-PN'>PN</link></filename>) and - recipe version - (<filename><link linkend='var-PV'>PV</link></filename>) as - follows: - <literallayout class='monospaced'> - ${WORKDIR}/${PN}-${PV} - </literallayout> + By default, this directory is + <filename>${</filename><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link><filename>}/${</filename><link linkend='var-BPN'><filename>BPN</filename></link><filename>}-${</filename><link linkend='var-PV'><filename>PV</filename></link><filename>}</filename>, + where <filename>${BPN}</filename> is the base recipe name + and <filename>${PV}</filename> is the recipe version. + If the source tarball extracts the code to a directory + named anything other than <filename>${BPN}-${PV}</filename>, + or if the source code if fetched from an SCM such as + Git or Subversion, then you must set <filename>S</filename> + in the recipe so that the OpenEmbedded build system + knows where to find the unpacked source. </para> <para> @@ -10556,6 +10599,22 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <literallayout class='monospaced'> poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19 </literallayout> + The unpacked source code resides in the + <filename>db-5.1.19</filename> folder. + </para> + + <para> + This next example assumes a Git repository. + By default, Git repositories are cloned to + <filename>${WORKDIR}/git</filename> during + <link linkend='ref-tasks-fetch'><filename>do_fetch</filename></link>. + Since this path is different from the default value of + <filename>S</filename>, you must set it specifically + so the source can be located: + <literallayout class='monospaced'> + SRC_URI = "git://path/to/repo.git" + S = "${WORKDIR}/git" + </literallayout> </para> </glossdef> </glossentry> @@ -10661,6 +10720,30 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> + <glossentry id='var-SDK_EXT_TYPE'><glossterm>SDK_EXT_TYPE</glossterm> + <info> + SDK_EXT_TYPE[doc] = "Controls whether or not shared state artifacts are copied into the extensible SDK." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Controls whether or not shared state artifacts are copied + into the extensible SDK. + The default value of "full" copies all of the required + shared state artifacts into the extensible SDK. + The value "minimal" leaves these artifacts out of the + SDK. + <note> + If you set the variable to "minimal", you need to + ensure + <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link> + is set in the SDK's configuration to enable the + artifacts to be fetched as needed. + </note> + </para> + </glossdef> + </glossentry> + <glossentry id='var-SDK_HOST_MANIFEST'><glossterm>SDK_HOST_MANIFEST</glossterm> <info> SDK_HOST_MANIFEST[doc] = "The manifest file for the host part of the SDK. This file lists all the installed packages that make up the host part of the SDK." @@ -10694,6 +10777,88 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> + <glossentry id='var-SDK_INCLUDE_PKGDATA'><glossterm>SDK_INCLUDE_PKGDATA</glossterm> + <info> + SDK_INCLUDE_PKGDATA[doc] = "When set to "1", specifies to include the packagedata for all recipes in the "world" target 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 packagedata for + all recipes in the "world" target in the extensible SDK. + Including this data allows the + <filename>devtool search</filename> command to find these + recipes in search results, as well as allows the + <filename>devtool add</filename> command to map + dependencies more effectively. + <note> + Enabling the <filename>SDK_INCLUDE_PKGDATA</filename> + variable significantly increases build time because + all of world needs to be built. + Enabling the variable also slightly increases the size + of the extensible SDK. + </note> + </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." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + A list of classes to remove from the + <link linkend='var-INHERIT'><filename>INHERIT</filename></link> + value globally within the extensible SDK configuration. + The default value is "buildhistory icecc". + </para> + + <para> + Some classes are not generally applicable within + the extensible SDK context and you can use this variable + to disable them. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-SDK_LOCAL_CONF_BLACKLIST'><glossterm>SDK_LOCAL_CONF_BLACKLIST</glossterm> + <info> + SDK_LOCAL_CONF_BLACKLIST[doc] = "A list of variables not allowed through from the build system configuration into the extensible SDK configuration." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + A list of variables not allowed through from the build + system configuration into the extensible SDK configuration. + Usually, these are variables that are specific to the + machine on which the build system is running and thus + would be potentially problematic within the extensible SDK. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-SDK_LOCAL_CONF_WHITELIST'><glossterm>SDK_LOCAL_CONF_WHITELIST</glossterm> + <info> + SDK_LOCAL_CONF_WHITELIST[doc] = "A list of variables allowed through from the build system configuration into the extensible SDK configuration." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + A list of variables allowed through from the build system + configuration into the extensible SDK configuration. + This list overrides the variables specified using the + <link linkend='var-SDK_LOCAL_CONF_BLACKLIST'><filename>SDK_LOCAL_CONF_BLACKLIST</filename></link> + variable as well as any variables identified by automatic + blacklisting due to the "/" character being found at the + start of the value, which is usually indicative of being a + path and thus might not be valid on the system where the + SDK is installed. + </para> + </glossdef> + </glossentry> + <glossentry id='var-SDK_NAME'><glossterm>SDK_NAME</glossterm> <info> SDK_NAME[doc] = "The base name for SDK output files." @@ -10814,7 +10979,8 @@ 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 toolchain binary prefix used for nativesdk recipes. + The toolchain binary prefix used for + <filename>nativesdk</filename> recipes. The OpenEmbedded build system uses the <filename>SDK_PREFIX</filename> value to set the <link linkend='var-TARGET_PREFIX'><filename>TARGET_PREFIX</filename></link> @@ -10824,6 +10990,33 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> + <glossentry id='var-SDK_RECRDEP_TASKS'><glossterm>SDK_RECRDEP_TASKS</glossterm> + <info> + SDK_RECRDEP_TASKS[doc] = "A list of shared state tasks added to the extensible SDK." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + A list of shared state tasks added to the extensible SDK. + By default, the following tasks are added: + <literallayout class='monospaced'> + do_populate_lic + do_package_qa + do_populate_sysroot + do_deploy + </literallayout> + Despite the default value of "" for the + <filename>SDK_RECRDEP_TASKS</filename> variable, the + above four tasks are always added to the SDK. + To specify tasks beyond these four, you need to use + the <filename>SDK_RECRDEP_TASKS</filename> variable (e.g. + you are defining additional tasks that are needed in + order to build + <link linkend='var-SDK_TARGETS'><filename>SDK_TARGETS</filename></link>). + </para> + </glossdef> + </glossentry> + <glossentry id='var-SDK_SYS'><glossterm>SDK_SYS</glossterm> <info> SDK_SYS[doc] = "Specifies the system, including the architecture and the operating system, for which the SDK will be built." @@ -10881,6 +11074,64 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" </glossdef> </glossentry> + <glossentry id='var-SDK_TARGETS'><glossterm>SDK_TARGETS</glossterm> + <info> + SDK_TARGETS[doc] = "A list of targets to install from shared state as part of the standard or extensible SDK installation." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + A list of targets to install from shared state as part of + the standard or extensible SDK installation. + The default value is "${PN}" (i.e. the image from which + the SDK is built). + </para> + + <para> + The <filename>SDK_TARGETS</filename> variable is an + internal variable and typically would not be changed. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-SDK_TITLE'><glossterm>SDK_TITLE</glossterm> + <info> + SDK_TITLE[doc] = "Specifies a title to be printed when running the SDK installer." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + Specifies a title to be printed when running the SDK + installer. + The <filename>SDK_TITLE</filename> variable defaults to + "<replaceable>distro</replaceable> SDK" for the standard + SDK and "<replaceable>distro</replaceable> Extensible SDK" + for the extensible SDK, where + <replaceable>distro</replaceable> is the first one of + <link linkend='var-DISTRO_NAME'><filename>DISTRO_NAME</filename></link> + or + <link linkend='var-DISTRO'><filename>DISTRO</filename></link> + that is set in your configuration. + </para> + </glossdef> + </glossentry> + + <glossentry id='var-SDK_UPDATE_URL'><glossterm>SDK_UPDATE_URL</glossterm> + <info> + SDK_UPDATE_URL[doc] = "An optional URL for an update server for the extensible SDK." + </info> + <glossdef> + <para role="glossdeffirst"> +<!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> + An optional URL for an update server for the extensible + SDK. + If set, the value is used as the default update server when + running <filename>devtool sdk-update</filename> within the + extensible SDK. + </para> + </glossdef> + </glossentry> + <glossentry id='var-SDK_VENDOR'><glossterm>SDK_VENDOR</glossterm> <info> SDK_VENDOR[doc] = "Specifies the name of the SDK vendor." @@ -10902,7 +11153,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> Specifies the version of the SDK. The distribution configuration file (e.g. - <filename>/meta-yocto/conf/distro/poky.conf</filename>) + <filename>/meta-poky/conf/distro/poky.conf</filename>) defines the <filename>SDK_VERSION</filename> as follows: <literallayout class='monospaced'> SDK_VERSION := "${@'${DISTRO_VERSION}'.replace('snapshot-${DATE}','snapshot')}" @@ -10939,14 +11190,13 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <glossentry id='var-SDKMACHINE'><glossterm>SDKMACHINE</glossterm> <info> - SDKMACHINE[doc] = "Specifies the architecture (i.e. i686 or x86_64) for which to build SDK and ADT items." + SDKMACHINE[doc] = "Specifies the architecture (i.e. i686 or x86_64) for which to build SDK items." </info> <glossdef> <para role="glossdeffirst"> <!-- <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> --> - The machine for which the Application Development Toolkit - (ADT) or SDK is built. - In other words, the SDK or ADT is built such that it + The machine for which the SDK is built. + In other words, the SDK is built such that it runs on the target you specify with the <filename>SDKMACHINE</filename> value. The value points to a corresponding @@ -11892,14 +12142,14 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" <listitem><para>For recipes building for the target machine, the value is "${STAGING_DIR}/${MACHINE}". </para></listitem> - <listitem><para>For <filename>native</filename> - recipes building + <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. </para></listitem> - <listitem><para>For <filename>nativesdk</filename> - recipes that build for the SDK, the value is + <listitem><para>For native SDK + recipes that build for the SDK + (<filename>nativesdk</filename>), the value is "${STAGING_DIR}/${MULTIMACH_HOST_SYS}". </para></listitem> </itemizedlist> @@ -12707,12 +12957,13 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" "${<link linkend='var-TARGET_SYS'>TARGET_SYS</link>}-". </para></listitem> <listitem><para> - For <filename>native</filename> recipes, the build - system sets the variable to the value of + For native recipes, the build system sets the + variable to the value of <filename>BUILD_PREFIX</filename>. </para></listitem> <listitem><para> - For <filename>nativesdk</filename> recipes, the + For native SDK recipes + (<filename>nativesdk</filename>), the build system sets the variable to the value of <filename>SDK_PREFIX</filename>. </para></listitem> @@ -12751,9 +13002,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" Consider these two examples: <itemizedlist> <listitem><para> - Given a <filename>native</filename> recipe on a - 32-bit, x86 machine running Linux, the value is - "i686-linux". + Given a native recipe on a 32-bit, x86 machine + running Linux, the value is "i686-linux". </para></listitem> <listitem><para> Given a recipe being built for a little-endian, @@ -13359,11 +13609,14 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" toolchain set that runs on the <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>, and each package should usually have the prefix - "nativesdk-". - When building an SDK using - <filename>bitbake -c populate_sdk <imagename></filename>, - a default list of packages is set in this variable, but - you can add additional packages to the list. + <filename>nativesdk-</filename>. + For example, consider the following command when + building an SDK: + <literallayout class='monospaced'> + $ bitbake -c populate_sdk <replaceable>imagename</replaceable> + </literallayout> + In this case, a default list of packages is set in this + variable, but you can add additional packages to the list. </para> <para> @@ -13373,8 +13626,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" section. For information on setting up a cross-development environment, see the - "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>" - section in the Yocto Project Application Developer's Guide. + <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-manual'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>. </para> </glossdef> </glossentry> @@ -13425,8 +13677,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" section. For information on setting up a cross-development environment, see the - "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>" - section in the Yocto Project Application Developer's Guide. + <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-manual'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>. </para> </glossdef> </glossentry> @@ -14121,7 +14372,7 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" USER_CLASSES ?= "buildstats image-mklibs image-prelink" </literallayout> For more information, see - <filename>meta-yocto/conf/local.conf.sample</filename> in + <filename>meta-poky/conf/local.conf.sample</filename> in the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. </para> diff --git a/yocto-poky/documentation/ref-manual/technical-details.xml b/yocto-poky/documentation/ref-manual/technical-details.xml index 2df36521c..f06382ab5 100644 --- a/yocto-poky/documentation/ref-manual/technical-details.xml +++ b/yocto-poky/documentation/ref-manual/technical-details.xml @@ -187,7 +187,7 @@ This section provides some technical background on how cross-development toolchains are created and used. For more information on toolchains, you can also see the - <ulink url='&YOCTO_DOCS_ADT_URL;'>Yocto Project Application Developer's Guide</ulink>. + <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>. </para> <para> @@ -219,6 +219,12 @@ You can think of <filename>gcc-cross</filename> simply as an automatically generated cross-compiler that is used internally within BitBake only. + <note> + The extensible SDK does not use + <filename>gcc-cross-canadian</filename> since this SDK + ships a copy of the OpenEmbedded build system and the sysroot + within it contains <filename>gcc-cross</filename>. + </note> </para> <para> @@ -282,8 +288,10 @@ the development tools (e.g., the <filename>gcc-cross-canadian</filename>), <filename>binutils-cross-canadian</filename>, and other - <filename>nativesdk-*</filename> tools you need to cross-compile and - test your software. + <filename>nativesdk-*</filename> tools, + which are tools native to the SDK (i.e. native to + <link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link>), + you need to cross-compile and test your software. The figure shows the commands you use to easily build out this toolchain. This cross-development toolchain is built to execute on the @@ -363,8 +371,9 @@ <note> For information on advantages gained when building a cross-development toolchain installer, see the - "<ulink url='&YOCTO_DOCS_ADT_URL;#optionally-building-a-toolchain-installer'>Optionally Building a Toolchain Installer</ulink>" - section in the Yocto Project Application Developer's Guide. + "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer'>Building an SDK Installer</ulink>" + section in the Yocto Project Software Development Kit (SDK) Developer's + Guide. </note> </section> @@ -470,17 +479,24 @@ </para> <para> - To complicate the problem, there are things that should not be included in - the checksum. + To complicate the problem, there are things that should not be + included in the checksum. First, there is the actual specific build path of a given task - the <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>. - It does not matter if the work directory changes because it should not - affect the output for target packages. - Also, the build process has the objective of making native or cross packages relocatable. - The checksum therefore needs to exclude <filename>WORKDIR</filename>. + It does not matter if the work directory changes because it should + not affect the output for target packages. + Also, the build process has the objective of making native + or cross packages relocatable. + <note> + Both native and cross packages run on the build host. + However, cross packages generate output for the target + architecture. + </note> + The checksum therefore needs to exclude + <filename>WORKDIR</filename>. The simplistic approach for excluding the work directory is to set - <filename>WORKDIR</filename> to some fixed value and create the checksum - for the "run" script. + <filename>WORKDIR</filename> to some fixed value and create the + checksum for the "run" script. </para> <para> @@ -665,7 +681,6 @@ <literallayout class='monospaced'> DEPLOYDIR = "${WORKDIR}/deploy-${PN}" SSTATETASKS += "do_deploy" - do_deploy[sstate-name] = "deploy" do_deploy[sstate-inputdirs] = "${DEPLOYDIR}" do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}" @@ -770,22 +785,49 @@ Because of this, the Yocto Project includes strong debugging tools: <itemizedlist> - <listitem><para>Whenever a shared state package is written out, so is a - corresponding <filename>.siginfo</filename> file. - This practice results in a pickled Python database of all - the metadata that went into creating the hash for a given shared state - package.</para></listitem> - <listitem><para>If you run BitBake with the <filename>--dump-signatures</filename> - (or <filename>-S</filename>) option, BitBake dumps out - <filename>.siginfo</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>.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. + <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> @@ -1378,7 +1420,6 @@ <literallayout class='monospaced'> COMMERCIAL_AUDIO_PLUGINS ?= "" COMMERCIAL_VIDEO_PLUGINS ?= "" - COMMERCIAL_QT = "" </literallayout> If you want to enable these components, you can do so by making sure you have statements similar to the following @@ -1388,7 +1429,6 @@ gst-plugins-ugly-mpegaudioparse" COMMERCIAL_VIDEO_PLUGINS = "gst-plugins-ugly-mpeg2dec \ gst-plugins-ugly-mpegstream gst-plugins-bad-mpegvideoparse" - COMMERCIAL_QT ?= "qmmp" LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly commercial_gst-plugins-bad commercial_qmmp" </literallayout> Of course, you could also create a matching whitelist @@ -1406,9 +1446,8 @@ Specifying audio and video plug-ins as part of the <filename>COMMERCIAL_AUDIO_PLUGINS</filename> and <filename>COMMERCIAL_VIDEO_PLUGINS</filename> statements - or commercial Qt components as part of - the <filename>COMMERCIAL_QT</filename> statement (along - with the enabling <filename>LICENSE_FLAGS_WHITELIST</filename>) includes the + (along with the enabling + <filename>LICENSE_FLAGS_WHITELIST</filename>) includes the plug-ins or components into built images, thus adding support for media formats or components. </para> diff --git a/yocto-poky/documentation/ref-manual/usingpoky.xml b/yocto-poky/documentation/ref-manual/usingpoky.xml index ca87962e2..a7bf32d45 100644 --- a/yocto-poky/documentation/ref-manual/usingpoky.xml +++ b/yocto-poky/documentation/ref-manual/usingpoky.xml @@ -113,8 +113,7 @@ <filename class="directory">tmp/deploy/images</filename>. For information on how to run pre-built images such as <filename>qemux86</filename> and <filename>qemuarm</filename>, see the - "<ulink url='&YOCTO_DOCS_QS_URL;#using-pre-built'>Example Using Pre-Built Binaries and QEMU</ulink>" - section in the Yocto Project Application Developer's Guide. + <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-manual'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink>. For information about how to install these images, see the documentation for your particular board or machine. </para> @@ -150,10 +149,11 @@ <para> For discussions on debugging, see the - "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-gdb-remotedebug'>Debugging With the GNU Project Debugger (GDB) Remotely</ulink>" - and - "<ulink url='&YOCTO_DOCS_DEV_URL;#adt-eclipse'>Working within Eclipse</ulink>" - sections in the Yocto Project Development Manual. + "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-gdb-remotedebug'>Debugging With the GNU Project Debugger (GDB) Remotely</ulink>" section + in the Yocto Project Developer's Manual + and the + "<ulink url='&YOCTO_DOCS_SDK_URL;#adt-eclipse'>Working within Eclipse</ulink>" + section in the Yocto Project Software Development Kit (SDK) Developer's Guide. </para> <note> @@ -799,12 +799,18 @@ <section id='build-history-sdk-information'> <title>Build History SDK Information</title> + <para> Build history collects similar information on the contents - of SDKs (e.g. <filename>meta-toolchain</filename> - or <filename>bitbake -c populate_sdk imagename</filename>) + of SDKs + (e.g. <filename>bitbake -c populate_sdk imagename</filename>) as compared to information it collects for images. - The following list shows the files produced for each SDK: + Furthermore, this information differs depending on whether an + extensible or standard SDK is being produced. + </para> + + <para> + The following list shows the files produced for SDKs: <itemizedlist> <listitem><para><filename>files-in-sdk.txt:</filename> A list of files in the SDK with permissions, @@ -817,11 +823,49 @@ about the SDK. See the following listing example for more information. </para></listitem> + <listitem><para><filename>sstate-task-sizes.txt:</filename> + A text file containing name-value pairs with information + about task group sizes + (e.g. <filename>do_populate_sysroot</filename> tasks + have a total size). + The <filename>sstate-task-sizes.txt</filename> file + exists only when an extensible SDK is created. + </para></listitem> + <listitem><para><filename>sstate-package-sizes.txt:</filename> + A text file containing name-value pairs with information + for the shared-state packages and sizes in the SDK. + The <filename>sstate-package-sizes.txt</filename> file + exists only when an extensible SDK is created. + </para></listitem> + <listitem><para><filename>sdk-files:</filename> + A folder that contains copies of the files mentioned in + <filename>BUILDHISTORY_SDK_FILES</filename> if the + files are present in the output. + Additionally, the default value of + <filename>BUILDHISTORY_SDK_FILES</filename> is specific + to the extensible SDK although you can set it + differently if you would like to pull in specific files + from the standard SDK.</para> + <para>The default files are + <filename>conf/local.conf</filename>, + <filename>conf/bblayers.conf</filename>, + <filename>conf/auto.conf</filename>, + <filename>conf/locked-sigs.inc</filename>, and + <filename>conf/devtool.conf</filename>. + Thus, for an extensible SDK, these files get copied + into the <filename>sdk-files</filename> directory. + </para></listitem> <listitem><para>The following information appears under each of the <filename>host</filename> and <filename>target</filename> directories for the portions of the SDK that run on the host and on the target, respectively: + <note> + The following files for the most part are empty + when producing an extensible SDK because this + type of SDK is not constructed from packages as is + the standard SDK. + </note> <itemizedlist> <listitem><para><filename>depends.dot:</filename> Dependency graph for the SDK that is diff --git a/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-add-flow.png b/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-add-flow.png Binary files differnew file mode 100644 index 000000000..c09e60e35 --- /dev/null +++ b/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-add-flow.png diff --git a/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-modify-flow.png b/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-modify-flow.png Binary files differnew file mode 100644 index 000000000..cd06c0181 --- /dev/null +++ b/yocto-poky/documentation/sdk-manual/figures/sdk-devtool-modify-flow.png diff --git a/yocto-poky/documentation/sdk-manual/figures/sdk-eclipse-dev-flow.png b/yocto-poky/documentation/sdk-manual/figures/sdk-eclipse-dev-flow.png Binary files differnew file mode 100644 index 000000000..9f986e0d4 --- /dev/null +++ b/yocto-poky/documentation/sdk-manual/figures/sdk-eclipse-dev-flow.png diff --git a/yocto-poky/documentation/sdk-manual/figures/sdk-environment.png b/yocto-poky/documentation/sdk-manual/figures/sdk-environment.png Binary files differnew file mode 100644 index 000000000..78b8cad39 --- /dev/null +++ b/yocto-poky/documentation/sdk-manual/figures/sdk-environment.png diff --git a/yocto-poky/documentation/sdk-manual/figures/sdk-installed-extensible-sdk-directory.png b/yocto-poky/documentation/sdk-manual/figures/sdk-installed-extensible-sdk-directory.png Binary files differnew file mode 100644 index 000000000..99e07ce6f --- /dev/null +++ b/yocto-poky/documentation/sdk-manual/figures/sdk-installed-extensible-sdk-directory.png diff --git a/yocto-poky/documentation/sdk-manual/figures/sdk-installed-standard-sdk-directory.png b/yocto-poky/documentation/sdk-manual/figures/sdk-installed-standard-sdk-directory.png Binary files differnew file mode 100644 index 000000000..d4af85020 --- /dev/null +++ b/yocto-poky/documentation/sdk-manual/figures/sdk-installed-standard-sdk-directory.png diff --git a/yocto-poky/documentation/sdk-manual/figures/sdk-title.png b/yocto-poky/documentation/sdk-manual/figures/sdk-title.png Binary files differnew file mode 100644 index 000000000..e9d5b346b --- /dev/null +++ b/yocto-poky/documentation/sdk-manual/figures/sdk-title.png diff --git a/yocto-poky/documentation/sdk-manual/sdk-appendix-customizing.xml b/yocto-poky/documentation/sdk-manual/sdk-appendix-customizing.xml new file mode 100644 index 000000000..79326077f --- /dev/null +++ b/yocto-poky/documentation/sdk-manual/sdk-appendix-customizing.xml @@ -0,0 +1,388 @@ +<!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-customizing'> + +<title>Customizing the SDK</title> + +<para> + This appendix presents customizations you can apply to both the standard + and extensible SDK. + Each subsection identifies the type of SDK to which the section applies. +</para> + +<section id='sdk-configuring-the-extensible-sdk'> + <title>Configuring the Extensible SDK</title> + + <para> + The extensible SDK primarily consists of a pre-configured copy of + the OpenEmbedded build system from which it was produced. + Thus, the SDK's configuration is derived using that build system and + the following filters, which the OpenEmbedded build system applies + against <filename>local.conf</filename> and + <filename>auto.conf</filename> if they are present: + <itemizedlist> + <listitem><para> + Variables whose values start with "/" are excluded since the + assumption is that those values are paths that are likely to + be specific to the build host. + </para></listitem> + <listitem><para> + Variables listed in + <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_BLACKLIST'><filename>SDK_LOCAL_CONF_BLACKLIST</filename></ulink> + are excluded. + The default value blacklists + <ulink url='&YOCTO_DOCS_REF_URL;#var-CONF_VERSION'><filename>CONF_VERSION</filename></ulink>, + <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></ulink>, + <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink>, + <ulink url='&YOCTO_DOCS_REF_URL;#var-PRSERV_HOST'><filename>PRSERV_HOST</filename></ulink>, + and + <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></ulink>. + </para></listitem> + <listitem><para> + Variables listed in + <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_LOCAL_CONF_WHITELIST'><filename>SDK_LOCAL_CONF_WHITELIST</filename></ulink> + are included. + Including a variable in the value of + <filename>SDK_LOCAL_CONF_WHITELIST</filename> overrides either + of the above two conditions. + The default value is blank. + </para></listitem> + <listitem><para> + Classes inherited globally with + <ulink url='&YOCTO_DOCS_REF_URL;#var-INHERIT'><filename>INHERIT</filename></ulink> + that are listed in + <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INHERIT_BLACKLIST'><filename>SDK_INHERIT_BLACKLIST</filename></ulink> + are disabled. + Using <filename>SDK_INHERIT_BLACKLIST</filename> to disable + these classes is is the typical method to disable classes that + are problematic or unnecessary in the SDK context. + The default value blacklists the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-buildhistory'><filename>buildhistory</filename></ulink> + and + <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-icecc'><filename>icecc</filename></ulink> + classes. + </para></listitem> + </itemizedlist> + Additionally, the contents of <filename>conf/sdk-extra.conf</filename>, + when present, are appended to the end of + <filename>conf/local.conf</filename> within the produced SDK, without + any filtering. + The <filename>sdk-extra.conf</filename> file is particularly useful + if you want to set a variable value just for the SDK and not the + OpenEmbedded build system used to create the SDK. + </para> +</section> + +<section id='adjusting-the-extensible-sdk-to-suit-your-build-system-setup'> + <title>Adjusting the Extensible SDK to Suit Your Build System Setup</title> + + <para> + In most cases, the extensible SDK defaults should work. + However, some cases exist for which you might consider making + adjustments: + <itemizedlist> + <listitem><para> + If your SDK configuration inherits additional classes + using the + <ulink url='&YOCTO_DOCS_REF_URL;#var-INHERIT'><filename>INHERIT</filename></ulink> + variable and you do not need or want those classes enabled in + the SDK, you can blacklist them by adding them to the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INHERIT_BLACKLIST'><filename>SDK_INHERIT_BLACKLIST</filename></ulink> + variable. + The default value of <filename>SDK_INHERIT_BLACKLIST</filename> + is set using the "?=" operator. + Consequently, you will need to either set the complete value + using "=" or append the value using "_append". + </para></listitem> + <listitem><para> + If you have classes or recipes that add additional tasks to + the standard build flow (i.e. that execute as part of building + the recipe as opposed to needing to be called explicitly), then + you need to do one of the following: + <itemizedlist> + <listitem><para> + Ensure the tasks are shared state tasks (i.e. their + output is saved to and can be restored from the shared + state cache), or that the tasks are able to be + produced quickly from a task that is a shared state + task and add the task name to the value of + <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_RECRDEP_TASKS'><filename>SDK_RECRDEP_TASKS</filename></ulink>. + </para></listitem> + <listitem><para> + Disable the tasks if they are added by a class and + you do not need the functionality the class provides + in the extensible SDK. + To disable the tasks, add the class to + <filename>SDK_INHERIT_BLACKLIST</filename> as previously + described. + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para> + Generally, you want to have a shared state mirror set up so + users of the SDK can add additional items to the SDK after + installation without needing to build the items from source. + See the + "<link linkend='sdk-providing-additional-installable-extensible-sdk-content'>Providing Additional Installable Extensible SDK Content</link>" + section for information. + </para></listitem> + <listitem><para> + If you want users of the SDK to be able to easily update the + SDK, you need to set the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_UPDATE_URL'><filename>SDK_UPDATE_URL</filename></ulink> + variable. + For more information, see the + "<link linkend='sdk-providing-updates-after-installing-the-extensible-sdk'>Providing Updates After Installing the Extensible SDK</link>" + section. + </para></listitem> + <listitem><para> + If you have adjusted the list of files and directories that + appear in + <ulink url='&YOCTO_DOCS_REF_URL;#var-COREBASE'><filename>COREBASE</filename></ulink> + (other than layers that are enabled through + <filename>bblayers.conf</filename>), then you must list these + files in + <ulink url='&YOCTO_DOCS_REF_URL;#var-COREBASE_FILES'><filename>COREBASE_FILES</filename></ulink> + so that the files are copied into the SDK. + </para></listitem> + <listitem><para> + If your OpenEmbedded build system setup uses a different + environment setup script other than + <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> + or + <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>, + then you must set + <ulink url='&YOCTO_DOCS_REF_URL;#var-OE_INIT_ENV_SCRIPT'><filename>OE_INIT_ENV_SCRIPT</filename></ulink> + to point to the environment setup script you use. + <note> + You must also reflect this change in the value used for the + <filename>COREBASE_FILES</filename> variable as previously + described. + </note> + </para></listitem> + </itemizedlist> + </para> +</section> + +<section id='sdk-changing-the-appearance-of-the-extensible-sdk'> + <title>Changing the Appearance of the Extensible SDK</title> + + <para> + You can change the title shown by the SDK installer by setting the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_TITLE'><filename>SDK_TITLE</filename></ulink> + variable. + By default, this title is derived from + <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_NAME'><filename>DISTRO_NAME</filename></ulink> + when it is set. + If the <filename>DISTRO_NAME</filename> variable is not set, the title + is derived from the + <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink> + variable. + </para> +</section> + +<section id='sdk-providing-updates-after-installing-the-extensible-sdk'> + <title>Providing Updates After Installing the Extensible SDK</title> + + <para> + When you make changes to your configuration or to the metadata and + if you want those changes to be reflected in installed SDKs, you need + to perform additional steps to make it possible for those that use + the SDK to update their installations with the + <filename>devtool sdk-update</filename> command: + <orderedlist> + <listitem><para> + Arrange to be created a directory that can be shared over + HTTP or HTTPS. + </para></listitem> + <listitem><para> + Set the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_UPDATE_URL'><filename>SDK_UPDATE_URL</filename></ulink> + variable to point to the corresponding HTTP or HTTPS URL. + Setting this variable causes any SDK built to default to that + URL and thus, the user does not have to pass the URL to the + <filename>devtool sdk-update</filename> command. + </para></listitem> + <listitem><para> + Build the extensible SDK normally (i.e., use the + <filename>bitbake -c populate_sdk_ext</filename> <replaceable>imagename</replaceable> + command). + </para></listitem> + <listitem><para> + Publish the SDK using the following command: + <literallayout class='monospaced'> + $ oe-publish-sdk <replaceable>some_path</replaceable>/sdk-installer.sh <replaceable>path_to_shared/http_directory</replaceable> + </literallayout> + You must repeat this step each time you rebuild the SDK + with changes that you want to make available through the + update mechanism. + </para></listitem> + </orderedlist> + </para> + + <para> + Completing the above steps allows users of the existing SDKs to + simply run <filename>devtool sdk-update</filename> to retrieve the + latest updates. + See the + "<link linkend='sdk-updating-the-extensible-sdk'>Updating the Extensible SDK</link>" + section for further information. + </para> +</section> + +<section id='sdk-providing-additional-installable-extensible-sdk-content'> + <title>Providing Additional Installable Extensible SDK Content</title> + + <para> + If you want the users of the extensible SDK you are building to be + able to add items to the SDK without needing to build the + items from source, you need to do a number of things: + <orderedlist> + <listitem><para> + Ensure the additional items you want the user to be able to + install are actually built. + You can ensure these items are built a number of different + ways: 1) Build them explicitly, perhaps using one or more + "meta" recipes that depend on lists of other recipes to keep + things tidy, or 2) Build the "world" target and set + <filename>EXCLUDE_FROM_WORLD_pn-</filename><replaceable>recipename</replaceable> + for the recipes you do not want built. + See the + <ulink url='&YOCTO_DOCS_REF_URL;#var-EXCLUDE_FROM_WORLD'><filename>EXCLUDE_FROM_WORLD</filename></ulink> + variable for additional information. + </para></listitem> + <listitem><para> + Expose the <filename>sstate-cache</filename> directory + produced by the build. + Typically, you expose this directory over HTTP or HTTPS. + </para></listitem> + <listitem><para> + Set the appropriate configuration so that the produced SDK + knows how to find the configuration. + The variable you need to set is + <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></ulink>: + <literallayout class='monospaced'> + SSTATE_MIRRORS = "file://.* http://<replaceable>example</replaceable>.com/<replaceable>some_path</replaceable>/sstate-cache/PATH" + </literallayout> + You can set the <filename>SSTATE_MIRRORS</filename> variable + in two different places: + <itemizedlist> + <listitem><para> + If the mirror value you are setting is appropriate to + be set for both the OpenEmbedded build system that is + actually building the SDK and the SDK itself (i.e. the + mirror is accessible in both places or it will fail + quickly on the OpenEmbedded build system side, and its + contents will not interfere with the build), then you + can set the variable in your + <filename>local.conf</filename> or custom distro + configuration file. + You can then "whitelist" the variable through + to the SDK by adding the following: + <literallayout class='monospaced'> + SDK_LOCAL_CONF_WHITELIST = "SSTATE_MIRRORS" + </literallayout> + </para></listitem> + <listitem><para> + Alternatively, if you just want to set the + <filename>SSTATE_MIRRORS</filename> variable's value + for the SDK alone, create a + <filename>conf/sdk-extra.conf</filename> either in + your + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> + or within any layer and put your + <filename>SSTATE_MIRRORS</filename> setting within + that file. + <note> + This second option is the safest option should + you have any doubts as to which method to use when + setting <filename>SSTATE_MIRRORS</filename>. + </note> + </para></listitem> + </itemizedlist> + </para></listitem> + </orderedlist> + </para> +</section> + +<section id='sdk-minimizing-the-size-of-the-extensible-sdk-installer-download'> + <title>Minimizing the Size of the Extensible SDK Installer Download</title> + + <para> + By default, the extensible SDK bundles the shared state artifacts for + everything needed to reconstruct the image for which the SDK was built. + This bundling can lead to an SDK installer file that is a Gigabyte or + more in size. + If the size of this file causes a problem, you can build an SDK that + has just enough in it to install and provide access to the + <filename>devtool command</filename> by setting the following in your + configuration: + <literallayout class='monospaced'> + SDK_EXT_TYPE = "minimal" + </literallayout> + Setting + <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_EXT_TYPE'><filename>SDK_EXT_TYPE</filename></ulink> + to "minimal" produces an SDK installer that is around 35 Mbytes in + size, which downloads and installs quickly. + You need to realize, though, that the minimal installer does not + install any libraries or tools out of the box. + These must be installed either "on the fly" or through actions you + perform using <filename>devtool</filename> or explicitly with the + <filename>devtool sdk-install</filename> command. + </para> + + <para> + In most cases, when building a minimal SDK you will need to also enable + bringing in the information on a wider range of packages produced by + the system. + This is particularly true so that <filename>devtool add</filename> + is able to effectively map dependencies it discovers in a source tree + to the appropriate recipes. + Also so that the <filename>devtool search</filename> command + is able to return useful results. + </para> + + <para> + To facilitate this wider range of information, you would additionally + set the following: + <literallayout class='monospaced'> + SDK_INCLUDE_PKGDATA = "1" + </literallayout> + See the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SDK_INCLUDE_PKGDATA'><filename>SDK_INCLUDE_PKGDATA</filename></ulink> + variable for additional information. + </para> + + <para> + Setting the <filename>SDK_INCLUDE_PKGDATA</filename> variable as + shown causes the "world" target to be built so that information + for all of the recipes included within it are available. + Having these recipes available increases build time significantly and + increases the size of the SDK installer by 30-80 Mbytes depending on + how many recipes are included in your configuration. + </para> + + <para> + You can use + <filename>EXCLUDE_FROM_WORLD_pn-</filename><replaceable>recipename</replaceable> + for recipes you want to exclude. + However, it is assumed that you would need to be building the "world" + target if you want to provide additional items to the SDK. + Consequently, building for "world" should not represent undue + overhead in most cases. + <note> + If you set <filename>SDK_EXT_TYPE</filename> to "minimal", + then providing a shared state mirror is mandatory so that items + can be installed as needed. + See the + "<link linkend='sdk-providing-additional-installable-extensible-sdk-content'>Providing Additional Installable Extensible SDK Content</link>" + section for more information. + </note> + </para> +</section> +</appendix> +<!-- +vim: expandtab tw=80 ts=4 +--> diff --git a/yocto-poky/documentation/sdk-manual/sdk-appendix-obtain.xml b/yocto-poky/documentation/sdk-manual/sdk-appendix-obtain.xml new file mode 100644 index 000000000..3d4e364bf --- /dev/null +++ b/yocto-poky/documentation/sdk-manual/sdk-appendix-obtain.xml @@ -0,0 +1,252 @@ +<!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-obtain'> + +<title>Obtaining the SDK</title> + +<section id='sdk-locating-pre-built-sdk-installers'> + <title>Locating Pre-Built SDK Installers</title> + + <para> + 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 + toolchain. + </para> + + <para> + You can find SDK installers here: + <itemizedlist> + <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 + 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 + libraries appropriate for developing against that image. + For example, if your host development system is a 64-bit x86 + system and you are going to use your cross-toolchain for a + 32-bit x86 target, go into the <filename>x86_64</filename> + folder and download the following installer: + <literallayout class='monospaced'> + 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 + <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>. + </para></listitem> + </itemizedlist> + </para> +</section> + +<section id='sdk-building-an-sdk-installer'> + <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 + the environment setup script. + See the + "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>" + section in the Yocto Project Quick Start for steps that show you + how to set up the Yocto Project environment. + In particular, you need to be sure the + <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> + variable matches the architecture for which you are building and that + the + <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink> + variable is correctly set if you are building a toolchain designed to + run on an architecture that differs from your current development host + machine (i.e. the build machine). + </para> + + <para> + To build the toolchain installer for a standard SDK and populate + the SDK image, use the following command: + <literallayout class='monospaced'> + $ bitbake <replaceable>image</replaceable> -c populate_sdk + </literallayout> + You can do the same for the extensible SDK using this command: + <literallayout class='monospaced'> + $ bitbake <replaceable>image</replaceable> -c populate_sdk_ext + </literallayout> + These commands result in a toolchain installer that contains the sysroot + that matches your target root filesystem. + </para> + + <para> + When the <filename>bitbake</filename> command completes, the toolchain + 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'> + IMAGE_INSTALL_append = " glibc-staticdev" + </literallayout> + </note> + </para> +</section> + +<section id='sdk-extracting-the-root-filesystem'> + <title>Extracting the Root Filesystem</title> + + <para> + After installing the toolchain, for some use cases you + might need to separately extract a root filesystem: + <itemizedlist> + <listitem><para>You want to boot the image using NFS. + </para></listitem> + <listitem><para>You want to use the root filesystem as the + target sysroot. + For example, the Eclipse IDE environment with the Eclipse + Yocto Plug-in installed allows you to use QEMU to boot + under NFS.</para></listitem> + <listitem><para>You want to develop your target application + using the root filesystem as the target sysroot. + </para></listitem> + </itemizedlist> + </para> + + <para> + To extract the root filesystem, first <filename>source</filename> + the cross-development environment setup script to establish + necessary environment variables. + If you built the toolchain in the Build Directory, you will find + the toolchain environment script in the + <filename>tmp</filename> directory. + If you installed the toolchain by hand, the environment setup + script is located in <filename>/opt/poky/&DISTRO;</filename>. + </para> + + <para> + After sourcing the environment script, use the + <filename>runqemu-extract-sdk</filename> command and provide the + filesystem image. + </para> + + <para> + Following is an example. + The second command sets up the environment. + In this case, the setup script is located in the + <filename>/opt/poky/&DISTRO;</filename> directory. + The third command extracts the root filesystem from a previously + built filesystem that is located in the + <filename>~/Downloads</filename> directory. + Furthermore, this command extracts the root filesystem into the + <filename>qemux86-sato</filename> directory: + <literallayout class='monospaced'> + $ cd ~ + $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux + $ runqemu-extract-sdk \ + ~/Downloads/core-image-sato-sdk-qemux86-2011091411831.rootfs.tar.bz2 \ + $HOME/qemux86-sato + </literallayout> + You could now point to the target sysroot at + <filename>qemux86-sato</filename>. + </para> +</section> + +<section id='sdk-installed-standard-sdk-directory-structure'> + <title>Installed Standard SDK Directory Structure</title> + + <para> + The following figure shows the resulting directory structure after + you install the Standard SDK by running the <filename>.sh</filename> + SDK installation script: + </para> + + <para> + <imagedata fileref="figures/sdk-installed-standard-sdk-directory.png" scale="60" align="center" /> + </para> + + <para> + The installed SDK consists of an environment setup script for the SDK, + a configuration file for the target, a version file for the target, + and the root filesystem (<filename>sysroots</filename>) needed to + develop objects for the target system. + </para> + + <para> + Within the figure, italicized text is used to indicate replaceable + portions of the file or directory name. + For example, + <replaceable>install_dir</replaceable>/<replaceable>version</replaceable> + 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>). + Furthermore, <replaceable>target</replaceable> represents the target + architecture (e.g. <filename>i586</filename>) and + <replaceable>host</replaceable> represents the development system's + architecture (e.g. <filename>x86_64</filename>). + Thus, the complete names of the two directories within the + <filename>sysroots</filename> could be + <filename>i586-poky-linux</filename> and + <filename>x86_64-pokysdk-linux</filename> for the target and host, + respectively. + </para> +</section> + +<section id='sdk-installed-extensible-sdk-directory-structure'> + <title>Installed Extensible SDK Directory Structure</title> + + <para> + The following figure shows the resulting directory structure after + you install the Extensible SDK by running the <filename>.sh</filename> + SDK installation script: + </para> + + <para> + <imagedata fileref="figures/sdk-installed-extensible-sdk-directory.png" scale="60" align="center" /> + </para> + + <para> + The installed directory structure for the extensible SDK is quite + different than the installed structure for the standard SDK. + The extensible SDK does not separate host and target parts in the + same manner as does the standard SDK. + The extensible SDK uses an embedded copy of the OpenEmbedded + build system, which has its own sysroots. + </para> + + <para> + Of note in the directory structure are an environment setup script + for the SDK, a configuration file for the target, a version file for + the target, and a log file for the OpenEmbedded build system + preparation script run by the installer. + </para> + + <para> + Within the figure, italicized text is used to indicate replaceable + portions of the file or directory name. + For example, + <replaceable>install_dir</replaceable> is the directory where the SDK + is installed, which is <filename>poky_sdk</filename> by default. + <replaceable>target</replaceable> represents the target + architecture (e.g. <filename>i586</filename>) and + <replaceable>host</replaceable> represents the development system's + architecture (e.g. <filename>x86_64</filename>). + </para> +</section> + +</appendix> +<!-- +vim: expandtab tw=80 ts=4 +--> diff --git a/yocto-poky/documentation/sdk-manual/sdk-extensible.xml b/yocto-poky/documentation/sdk-manual/sdk-extensible.xml new file mode 100644 index 000000000..3e11fc97d --- /dev/null +++ b/yocto-poky/documentation/sdk-manual/sdk-extensible.xml @@ -0,0 +1,1304 @@ +<!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-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> + + <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. + </para> + + <para> + The remainder of this section presents the + <filename>devtool add</filename> and + <filename>devtool modify</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. + 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> + </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>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> + +<section id='sdk-a-closer-look-at-devtool-add'> + <title>A Closer Look at <filename>devtool add</filename></title> + + <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> + + <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> + + <para> + 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> 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. + </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). + </para> + + <para> + When writing a recipe for Makefile-only software, keep the + following in mind: + <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>. + </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. + </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. + </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> + </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. + </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 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> + <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> + </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> + 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-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> + 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. + </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. + </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-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'> + $ 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'> + $ 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> + +<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'> + $ 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'> + $ 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'> + $ 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> + +<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> + 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'> + $ 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> + + <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/yocto-poky/documentation/sdk-manual/sdk-intro.xml b/yocto-poky/documentation/sdk-manual/sdk-intro.xml new file mode 100644 index 000000000..88ae77831 --- /dev/null +++ b/yocto-poky/documentation/sdk-manual/sdk-intro.xml @@ -0,0 +1,338 @@ +<!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-intro'> +<title>Introduction</title> + +<section id='sdk-manual-intro'> + <title>Introduction</title> + + <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. + 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. + </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. + </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 + <ulink url='&YOCTO_DOCS_DEV_URL;#build-system-term'>OpenEmbedded build system</ulink>. + </para> + + <para> + SDKs are completely self-contained. + The binaries are linked against their own copy of + <filename>libc</filename>, which results in no dependencies + on the target system. + To achieve this, the pointer to the dynamic loader is + configured at install time since that path cannot be dynamically + altered. + This is the reason for a wrapper around the + <filename>populate_sdk</filename> and + <filename>populate_sdk_ext</filename> archives. + </para> + + <para> + Another feature for the SDKs is that only one set of cross-canadian + toolchain binaries are produced per 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 + variables such as + <ulink url='&YOCTO_DOCS_REF_URL;#var-CC'><filename>CC</filename></ulink> + and + <ulink url='&YOCTO_DOCS_REF_URL;#var-LD'><filename>LD</filename></ulink>. + This reduces the space needed for the tools. + Understand, however, that a sysroot is still needed for every target + since those binaries are target-specific. + </para> + + <para> + Going beyond the actual SDK, the SDK development environment consists + of the following: + <itemizedlist> + <listitem><para>An architecture-specific cross-toolchain and + matching sysroots (target and native) all built by the + OpenEmbedded build system. + 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. + </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. + </para></listitem> + <listitem><para>The Eclipse IDE Yocto Plug-in. + This plug-in is also 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. + These tools are also separate from the actual SDK but can be + independently obtained and used in the development process. + </para></listitem> + </itemizedlist> + </para> + + <section id='the-cross-development-toolchain'> + <title>The Cross-Development Toolchain</title> + + <para> + The + <ulink url='&YOCTO_DOCS_DEV_URL;#cross-development-toolchain'>Cross-Development Toolchain</ulink> + 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 + or through a + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> + that is based on your Metadata configuration or extension for + your targeted device. + The cross-toolchain works with a matching target sysroot. + </para> + </section> + + <section id='sysroot'> + <title>Sysroots</title> + + <para> + The native and target sysroots contain needed headers and libraries + for generating binaries that run on the target architecture. + The target sysroot is based on the target root filesystem image + that is built by the OpenEmbedded build system and uses the same + Metadata configuration used to build the cross-toolchain. + </para> + </section> + + <section id='the-qemu-emulator'> + <title>The QEMU Emulator</title> + + <para> + The QEMU emulator allows you to simulate your hardware while + running your application or image. + QEMU is not part of the SDK but is made available a number of ways: + <itemizedlist> + <listitem><para> + If you have cloned the <filename>poky</filename> Git + repository to create a + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> + and you have sourced the environment setup script, QEMU is + installed and automatically available. + </para></listitem> + <listitem><para> + If you have downloaded a Yocto Project release and unpacked + it to create a + <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> + and you have sourced the environment setup script, QEMU is + installed and automatically available. + </para></listitem> + <listitem><para> + If you have installed the cross-toolchain tarball and you + have sourced the toolchain's setup environment script, QEMU + is also installed and automatically available. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='eclipse-overview'> + <title>Eclipse Yocto Plug-in</title> + + <para> + The Eclipse IDE is a popular development environment and it fully + supports development using the Yocto Project. + 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. + 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> + 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>" + section. + </para> + </section> + + <section id='user-space-tools'> + <title>User-Space 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> + </para> + </section> +</section> + +<section id='sdk-development-model'> + <title>SDK Development Model</title> + + <para> + Fundamentally, the SDK fits into the development process as follows: + <imagedata fileref="figures/sdk-environment.png" align="center" width="6in" depth="5in" scalefit="100" /> + The SDK is installed on any machine and can be used to develop + applications, images, and kernels. + An SDK can even be used by a QA Engineer or Release Engineer. + The fundamental concept is that the machine that has the SDK installed + does not have to be associated with the machine that has the + Yocto Project installed. + 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. + Once the object is available, the image can be rebuilt using the + Yocto Project to produce the modified image. + </para> + + <para> + You just need to follow these general steps: + <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>" + section.</para></listitem> + <listitem><para><emphasis>Download the Target Image:</emphasis> + The Yocto Project supports several target architectures + and has many pre-built kernel images and root filesystem + images.</para> + <para>If you are going to develop your application on + hardware, go to the + <ulink url='&YOCTO_MACHINES_DL_URL;'><filename>machines</filename></ulink> + download area and choose a target machine area + from which to download the kernel image and root filesystem. + This download area could have several files in it that + support development using actual hardware. + For example, the area might contain + <filename>.hddimg</filename> files that combine the + kernel image with the filesystem, boot loaders, and + so forth. + Be sure to get the files you need for your particular + development process.</para> + <para>If you are going to develop your application and + then run and test it using the QEMU emulator, go to the + <ulink url='&YOCTO_QEMU_DL_URL;'><filename>machines/qemu</filename></ulink> + download area. + From this area, go down into the directory for your + target architecture (e.g. <filename>qemux86_64</filename> + for an <trademark class='registered'>Intel</trademark>-based + 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> + <listitem><para><emphasis>Develop and Test your + Application:</emphasis> At this point, you have the tools + to develop your application. + If you need to separately install and use the QEMU + emulator, you can go to + <ulink url='http://wiki.qemu.org/Main_Page'>QEMU Home Page</ulink> + to download and learn about the emulator. + You can 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 + Project.</para></listitem> + </orderedlist> + </para> + + <para> + The remainder of this manual describes how to use both the standard + SDK and the extensible SDK. + Information also exists in appendix form that describes how you can + build, install, and modify an SDK. + </para> +</section> + +</chapter> +<!-- +vim: expandtab tw=80 ts=4 +--> diff --git a/yocto-poky/documentation/sdk-manual/sdk-manual-customization.xsl b/yocto-poky/documentation/sdk-manual/sdk-manual-customization.xsl new file mode 100644 index 000000000..dae992c07 --- /dev/null +++ b/yocto-poky/documentation/sdk-manual/sdk-manual-customization.xsl @@ -0,0 +1,27 @@ +<?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="../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" /> + +--> + + <xsl:include href="../template/permalinks.xsl"/> + <xsl:include href="../template/section.title.xsl"/> + <xsl:include href="../template/component.title.xsl"/> + <xsl:include href="../template/division.title.xsl"/> + <xsl:include href="../template/formal.object.heading.xsl"/> + + <xsl:param name="html.stylesheet" select="'sdk-style.css'" /> + <xsl:param name="chapter.autolabel" select="1" /> + <xsl:param name="appendix.autolabel">A</xsl:param> + <xsl:param name="section.autolabel" select="1" /> + <xsl:param name="section.label.includes.component.label" select="1" /> + <xsl:param name="generate.id.attributes" select="1" /> + +</xsl:stylesheet> diff --git a/yocto-poky/documentation/sdk-manual/sdk-manual-eclipse-customization.xsl b/yocto-poky/documentation/sdk-manual/sdk-manual-eclipse-customization.xsl new file mode 100644 index 000000000..03555d6ca --- /dev/null +++ b/yocto-poky/documentation/sdk-manual/sdk-manual-eclipse-customization.xsl @@ -0,0 +1,37 @@ +<?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/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" /> + +--> + + <xsl:param name="chunker.output.indent" select="'yes'"/> + <xsl:param name="chunk.quietly" select="1"/> + <xsl:param name="chunk.first.sections" select="1"/> + <xsl:param name="chunk.section.depth" select="10"/> + <xsl:param name="use.id.as.filename" select="1"/> + <xsl:param name="ulink.target" select="'_self'" /> + <xsl:param name="base.dir" select="'html/adt-manual/'"/> + <xsl:param name="html.stylesheet" select="'../book.css'"/> + <xsl:param name="eclipse.manifest" select="0"/> + <xsl:param name="create.plugin.xml" select="0"/> + <xsl:param name="suppress.navigation" select="1"/> + <xsl:param name="generate.index" select="0"/> + <xsl:param name="chapter.autolabel" select="1" /> + <xsl:param name="appendix.autolabel" select="1" /> + <xsl:param name="section.autolabel" select="1" /> + <xsl:param name="section.label.includes.component.label" select="1" /> +</xsl:stylesheet> diff --git a/yocto-poky/documentation/sdk-manual/sdk-manual.xml b/yocto-poky/documentation/sdk-manual/sdk-manual.xml new file mode 100644 index 000000000..c860782fb --- /dev/null +++ b/yocto-poky/documentation/sdk-manual/sdk-manual.xml @@ -0,0 +1,80 @@ +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" +[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > + +<book id='sdk-manual' lang='en' + xmlns:xi="http://www.w3.org/2003/XInclude" + xmlns="http://docbook.org/ns/docbook" + > + <bookinfo> + + <mediaobject> + <imageobject> + <imagedata fileref='figures/sdk-title.png' + format='SVG' + align='left' scalefit='1' width='100%'/> + </imageobject> + </mediaobject> + + <title> + Yocto Project Software Development Kit (SDK) Developer's Guide + </title> + + <authorgroup> + <author> + <firstname>Scott</firstname> <surname>Rifenbark</surname> + <affiliation> + <orgname>Scotty's Documentation Services, LLC</orgname> + </affiliation> + <email>srifenbark@gmail.com</email> + </author> + </authorgroup> + + <revhistory> + <revision> + <revnumber>2.1</revnumber> + <date>April 2016</date> + <revremark>Released with the Yocto Project 2.1 Release.</revremark> + </revision> + </revhistory> + + <copyright> + <year>©RIGHT_YEAR;</year> + <holder>Linux Foundation</holder> + </copyright> + + <legalnotice> + <para> + Permission is granted to copy, distribute and/or modify this document under + the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England & Wales</ulink> as published by Creative Commons. + </para> + <note> + For the latest version of this manual associated with this + Yocto Project release, see the + <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink> + from the Yocto Project website. + </note> + + </legalnotice> + + </bookinfo> + + <xi:include href="sdk-intro.xml"/> + + <xi:include href="sdk-using.xml"/> + + <xi:include href="sdk-extensible.xml"/> + + <xi:include href="sdk-appendix-obtain.xml"/> + + <xi:include href="sdk-appendix-customizing.xml"/> + +<!-- <index id='index'> + <title>Index</title> + </index> +--> + +</book> +<!-- +vim: expandtab tw=80 ts=4 +--> diff --git a/yocto-poky/documentation/sdk-manual/sdk-style.css b/yocto-poky/documentation/sdk-manual/sdk-style.css new file mode 100644 index 000000000..52518964c --- /dev/null +++ b/yocto-poky/documentation/sdk-manual/sdk-style.css @@ -0,0 +1,988 @@ +/* + Generic XHTML / DocBook XHTML CSS Stylesheet. + + Browser wrangling and typographic design by + Oyvind Kolas / pippin@gimp.org + + Customised for Poky by + Matthew Allum / mallum@o-hand.com + + Thanks to: + Liam R. E. Quin + William Skaggs + Jakub Steiner + + Structure + --------- + + The stylesheet is divided into the following sections: + + Positioning + Margins, paddings, width, font-size, clearing. + Decorations + Borders, style + Colors + Colors + Graphics + Graphical backgrounds + Nasty IE tweaks + Workarounds needed to make it work in internet explorer, + currently makes the stylesheet non validating, but up until + this point it is validating. + Mozilla extensions + Transparency for footer + Rounded corners on boxes + +*/ + + + /*************** / + / Positioning / +/ ***************/ + +body { + font-family: Verdana, Sans, sans-serif; + + min-width: 640px; + width: 80%; + margin: 0em auto; + padding: 2em 5em 5em 5em; + color: #333; +} + +h1,h2,h3,h4,h5,h6,h7 { + font-family: Arial, Sans; + color: #00557D; + clear: both; +} + +h1 { + font-size: 2em; + text-align: left; + padding: 0em 0em 0em 0em; + margin: 2em 0em 0em 0em; +} + +h2.subtitle { + margin: 0.10em 0em 3.0em 0em; + padding: 0em 0em 0em 0em; + font-size: 1.8em; + padding-left: 20%; + font-weight: normal; + font-style: italic; +} + +h2 { + margin: 2em 0em 0.66em 0em; + padding: 0.5em 0em 0em 0em; + font-size: 1.5em; + font-weight: bold; +} + +h3.subtitle { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; + font-size: 142.14%; + text-align: right; +} + +h3 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 140%; + font-weight: bold; +} + +h4 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 120%; + font-weight: bold; +} + +h5 { + margin: 1em 0em 0.5em 0em; + padding: 1em 0em 0em 0em; + font-size: 110%; + font-weight: bold; +} + +h6 { + margin: 1em 0em 0em 0em; + padding: 1em 0em 0em 0em; + font-size: 110%; + font-weight: bold; +} + +.authorgroup { + background-color: transparent; + background-repeat: no-repeat; + padding-top: 256px; + background-image: url("figures/sdk-title.png"); + background-position: left top; + margin-top: -256px; + padding-right: 50px; + margin-left: 0px; + text-align: right; + width: 740px; +} + +h3.author { + margin: 0em 0me 0em 0em; + padding: 0em 0em 0em 0em; + font-weight: normal; + font-size: 100%; + color: #333; + clear: both; +} + +.author tt.email { + font-size: 66%; +} + +.titlepage hr { + width: 0em; + clear: both; +} + +.revhistory { + padding-top: 2em; + clear: both; +} + +.toc, +.list-of-tables, +.list-of-examples, +.list-of-figures { + padding: 1.33em 0em 2.5em 0em; + color: #00557D; +} + +.toc p, +.list-of-tables p, +.list-of-figures p, +.list-of-examples p { + padding: 0em 0em 0em 0em; + padding: 0em 0em 0.3em; + margin: 1.5em 0em 0em 0em; +} + +.toc p b, +.list-of-tables p b, +.list-of-figures p b, +.list-of-examples p b{ + font-size: 100.0%; + font-weight: bold; +} + +.toc dl, +.list-of-tables dl, +.list-of-figures dl, +.list-of-examples dl { + margin: 0em 0em 0.5em 0em; + padding: 0em 0em 0em 0em; +} + +.toc dt { + margin: 0em 0em 0em 0em; + padding: 0em 0em 0em 0em; +} + +.toc dd { + margin: 0em 0em 0em 2.6em; + padding: 0em 0em 0em 0em; +} + +div.glossary dl, +div.variablelist dl { +} + +.glossary dl dt, +.variablelist dl dt, +.variablelist dl dt span.term { + font-weight: normal; + width: 20em; + text-align: right; +} + +.variablelist dl dt { + margin-top: 0.5em; +} + +.glossary dl dd, +.variablelist dl dd { + margin-top: -1em; + margin-left: 25.5em; +} + +.glossary dd p, +.variablelist dd p { + margin-top: 0em; + margin-bottom: 1em; +} + + +div.calloutlist table td { + padding: 0em 0em 0em 0em; + margin: 0em 0em 0em 0em; +} + +div.calloutlist table td p { + margin-top: 0em; + margin-bottom: 1em; +} + +div p.copyright { + text-align: left; +} + +div.legalnotice p.legalnotice-title { + margin-bottom: 0em; +} + +p { + line-height: 1.5em; + margin-top: 0em; + +} + +dl { + padding-top: 0em; +} + +hr { + border: solid 1px; +} + + +.mediaobject, +.mediaobjectco { + text-align: center; +} + +img { + border: none; +} + +ul { + padding: 0em 0em 0em 1.5em; +} + +ul li { + padding: 0em 0em 0em 0em; +} + +ul li p { + text-align: left; +} + +table { + width :100%; +} + +th { + padding: 0.25em; + text-align: left; + font-weight: normal; + vertical-align: top; +} + +td { + padding: 0.25em; + vertical-align: top; +} + +p a[id] { + margin: 0px; + padding: 0px; + display: inline; + background-image: none; +} + +a { + text-decoration: underline; + color: #444; +} + +pre { + overflow: auto; +} + +a:hover { + text-decoration: underline; + /*font-weight: bold;*/ +} + +/* This style defines how the permalink character + appears by itself and when hovered over with + the mouse. */ + +[alt='Permalink'] { color: #eee; } +[alt='Permalink']:hover { color: black; } + + +div.informalfigure, +div.informalexample, +div.informaltable, +div.figure, +div.table, +div.example { + margin: 1em 0em; + padding: 1em; + page-break-inside: avoid; +} + + +div.informalfigure p.title b, +div.informalexample p.title b, +div.informaltable p.title b, +div.figure p.title b, +div.example p.title b, +div.table p.title b{ + padding-top: 0em; + margin-top: 0em; + font-size: 100%; + font-weight: normal; +} + +.mediaobject .caption, +.mediaobject .caption p { + text-align: center; + font-size: 80%; + padding-top: 0.5em; + padding-bottom: 0.5em; +} + +.epigraph { + padding-left: 55%; + margin-bottom: 1em; +} + +.epigraph p { + text-align: left; +} + +.epigraph .quote { + font-style: italic; +} +.epigraph .attribution { + font-style: normal; + text-align: right; +} + +span.application { + font-style: italic; +} + +.programlisting { + font-family: monospace; + font-size: 80%; + white-space: pre; + margin: 1.33em 0em; + padding: 1.33em; +} + +.tip, +.warning, +.caution, +.note { + margin-top: 1em; + margin-bottom: 1em; + +} + +/* force full width of table within div */ +.tip table, +.warning table, +.caution table, +.note table { + border: none; + width: 100%; +} + + +.tip table th, +.warning table th, +.caution table th, +.note table th { + padding: 0.8em 0.0em 0.0em 0.0em; + margin : 0em 0em 0em 0em; +} + +.tip p, +.warning p, +.caution p, +.note p { + margin-top: 0.5em; + margin-bottom: 0.5em; + padding-right: 1em; + text-align: left; +} + +.acronym { + text-transform: uppercase; +} + +b.keycap, +.keycap { + padding: 0.09em 0.3em; + margin: 0em; +} + +.itemizedlist li { + clear: none; +} + +.filename { + font-size: medium; + font-family: Courier, monospace; +} + + +div.navheader, div.heading{ + position: absolute; + left: 0em; + top: 0em; + width: 100%; + background-color: #cdf; + width: 100%; +} + +div.navfooter, div.footing{ + position: fixed; + left: 0em; + bottom: 0em; + background-color: #eee; + width: 100%; +} + + +div.navheader td, +div.navfooter td { + font-size: 66%; +} + +div.navheader table th { + /*font-family: Georgia, Times, serif;*/ + /*font-size: x-large;*/ + font-size: 80%; +} + +div.navheader table { + border-left: 0em; + border-right: 0em; + border-top: 0em; + width: 100%; +} + +div.navfooter table { + border-left: 0em; + border-right: 0em; + border-bottom: 0em; + width: 100%; +} + +div.navheader table td a, +div.navfooter table td a { + color: #777; + text-decoration: none; +} + +/* normal text in the footer */ +div.navfooter table td { + color: black; +} + +div.navheader table td a:visited, +div.navfooter table td a:visited { + color: #444; +} + + +/* links in header and footer */ +div.navheader table td a:hover, +div.navfooter table td a:hover { + text-decoration: underline; + background-color: transparent; + color: #33a; +} + +div.navheader hr, +div.navfooter hr { + display: none; +} + + +.qandaset tr.question td p { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; +} + +.qandaset tr.answer td p { + margin: 0em 0em 1em 0em; + padding: 0em 0em 0em 0em; +} +.answer td { + padding-bottom: 1.5em; +} + +.emphasis { + font-weight: bold; +} + + + /************* / + / decorations / +/ *************/ + +.titlepage { +} + +.part .title { +} + +.subtitle { + border: none; +} + +/* +h1 { + border: none; +} + +h2 { + border-top: solid 0.2em; + border-bottom: solid 0.06em; +} + +h3 { + border-top: 0em; + border-bottom: solid 0.06em; +} + +h4 { + border: 0em; + border-bottom: solid 0.06em; +} + +h5 { + border: 0em; +} +*/ + +.programlisting { + border: solid 1px; +} + +div.figure, +div.table, +div.informalfigure, +div.informaltable, +div.informalexample, +div.example { + border: 1px solid; +} + + + +.tip, +.warning, +.caution, +.note { + border: 1px solid; +} + +.tip table th, +.warning table th, +.caution table th, +.note table th { + border-bottom: 1px solid; +} + +.question td { + border-top: 1px solid black; +} + +.answer { +} + + +b.keycap, +.keycap { + border: 1px solid; +} + + +div.navheader, div.heading{ + border-bottom: 1px solid; +} + + +div.navfooter, div.footing{ + border-top: 1px solid; +} + + /********* / + / colors / +/ *********/ + +body { + color: #333; + background: white; +} + +a { + background: transparent; +} + +a:hover { + background-color: #dedede; +} + + +h1, +h2, +h3, +h4, +h5, +h6, +h7, +h8 { + background-color: transparent; +} + +hr { + border-color: #aaa; +} + + +.tip, .warning, .caution, .note { + border-color: #fff; +} + + +.tip table th, +.warning table th, +.caution table th, +.note table th { + border-bottom-color: #fff; +} + + +.warning { + background-color: #f0f0f2; +} + +.caution { + background-color: #f0f0f2; +} + +.tip { + background-color: #f0f0f2; +} + +.note { + background-color: #f0f0f2; +} + +.writernotes { + color: #ff0000; +} + +.glossary dl dt, +.variablelist dl dt, +.variablelist dl dt span.term { + color: #044; +} + +div.figure, +div.table, +div.example, +div.informalfigure, +div.informaltable, +div.informalexample { + border-color: #aaa; +} + +pre.programlisting { + color: black; + background-color: #fff; + border-color: #aaa; + border-width: 2px; +} + +.guimenu, +.guilabel, +.guimenuitem { + background-color: #eee; +} + + +b.keycap, +.keycap { + background-color: #eee; + border-color: #999; +} + + +div.navheader { + border-color: black; +} + + +div.navfooter { + border-color: black; +} + + + /*********** / + / graphics / +/ ***********/ + +/* +body { + background-image: url("images/body_bg.jpg"); + background-attachment: fixed; +} + +.navheader, +.note, +.tip { + background-image: url("images/note_bg.jpg"); + background-attachment: fixed; +} + +.warning, +.caution { + background-image: url("images/warning_bg.jpg"); + background-attachment: fixed; +} + +.figure, +.informalfigure, +.example, +.informalexample, +.table, +.informaltable { + background-image: url("images/figure_bg.jpg"); + background-attachment: fixed; +} + +*/ +h1, +h2, +h3, +h4, +h5, +h6, +h7{ +} + +/* +Example of how to stick an image as part of the title. + +div.article .titlepage .title +{ + background-image: url("figures/white-on-black.png"); + background-position: center; + background-repeat: repeat-x; +} +*/ + +div.preface .titlepage .title, +div.colophon .title, +div.chapter .titlepage .title, +div.article .titlepage .title +{ +} + +div.section div.section .titlepage .title, +div.sect2 .titlepage .title { + background: none; +} + + +h1.title { + background-color: transparent; + background-repeat: no-repeat; + height: 256px; + text-indent: -9000px; + overflow:hidden; +} + +h2.subtitle { + background-color: transparent; + text-indent: -9000px; + overflow:hidden; + width: 0px; + display: none; +} + + /*************************************** / + / pippin.gimp.org specific alterations / +/ ***************************************/ + +/* +div.heading, div.navheader { + color: #777; + font-size: 80%; + padding: 0; + margin: 0; + text-align: left; + position: absolute; + top: 0px; + left: 0px; + width: 100%; + height: 50px; + background: url('/gfx/heading_bg.png') transparent; + background-repeat: repeat-x; + background-attachment: fixed; + border: none; +} + +div.heading a { + color: #444; +} + +div.footing, div.navfooter { + border: none; + color: #ddd; + font-size: 80%; + text-align:right; + + width: 100%; + padding-top: 10px; + position: absolute; + bottom: 0px; + left: 0px; + + background: url('/gfx/footing_bg.png') transparent; +} +*/ + + + + /****************** / + / nasty ie tweaks / +/ ******************/ + +/* +div.heading, div.navheader { + width:expression(document.body.clientWidth + "px"); +} + +div.footing, div.navfooter { + width:expression(document.body.clientWidth + "px"); + margin-left:expression("-5em"); +} +body { + padding:expression("4em 5em 0em 5em"); +} +*/ + + /**************************************** / + / mozilla vendor specific css extensions / +/ ****************************************/ +/* +div.navfooter, div.footing{ + -moz-opacity: 0.8em; +} + +div.figure, +div.table, +div.informalfigure, +div.informaltable, +div.informalexample, +div.example, +.tip, +.warning, +.caution, +.note { + -moz-border-radius: 0.5em; +} + +b.keycap, +.keycap { + -moz-border-radius: 0.3em; +} +*/ + +table tr td table tr td { + display: none; +} + + +hr { + display: none; +} + +table { + border: 0em; +} + + .photo { + float: right; + margin-left: 1.5em; + margin-bottom: 1.5em; + margin-top: 0em; + max-width: 17em; + border: 1px solid gray; + padding: 3px; + background: white; +} + .seperator { + padding-top: 2em; + clear: both; + } + + #validators { + margin-top: 5em; + text-align: right; + color: #777; + } + @media print { + body { + font-size: 8pt; + } + .noprint { + display: none; + } + } + + +.tip, +.note { + background: #f0f0f2; + color: #333; + padding: 20px; + margin: 20px; +} + +.tip h3, +.note h3 { + padding: 0em; + margin: 0em; + font-size: 2em; + font-weight: bold; + color: #333; +} + +.tip a, +.note a { + color: #333; + text-decoration: underline; +} + +.footnote { + font-size: small; + color: #333; +} + +/* Changes the announcement text */ +.tip h3, +.warning h3, +.caution h3, +.note h3 { + font-size:large; + color: #00557D; +} diff --git a/yocto-poky/documentation/sdk-manual/sdk-using.xml b/yocto-poky/documentation/sdk-manual/sdk-using.xml new file mode 100644 index 000000000..1ea47d3bb --- /dev/null +++ b/yocto-poky/documentation/sdk-manual/sdk-using.xml @@ -0,0 +1,1466 @@ +<!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-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> + + <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. + </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> + +<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: + <replaceable>host_system</replaceable> is a string representing your development system: + + i686 or x86_64. + + <replaceable>image_type</replaceable> is the image for which the SDK was built. + + <replaceable>arch</replaceable> is a string representing the tuned target architecture: + + i586, x86_64, powerpc, mips, armv7a or armv5te + + <replaceable>release_version</replaceable> is a string representing the release number of the + 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: + <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_NATIVE_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/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: + <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> + <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> + </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. + <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> + </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. + </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/yocto-poky/documentation/toaster-manual/figures/compatible-layers.png b/yocto-poky/documentation/toaster-manual/figures/compatible-layers.png Binary files differnew file mode 100644 index 000000000..38436b075 --- /dev/null +++ b/yocto-poky/documentation/toaster-manual/figures/compatible-layers.png diff --git a/yocto-poky/documentation/toaster-manual/figures/import-layer.png b/yocto-poky/documentation/toaster-manual/figures/import-layer.png Binary files differnew file mode 100644 index 000000000..436ec7af4 --- /dev/null +++ b/yocto-poky/documentation/toaster-manual/figures/import-layer.png diff --git a/yocto-poky/documentation/toaster-manual/figures/new-project.png b/yocto-poky/documentation/toaster-manual/figures/new-project.png Binary files differnew file mode 100644 index 000000000..dbc50b991 --- /dev/null +++ b/yocto-poky/documentation/toaster-manual/figures/new-project.png diff --git a/yocto-poky/documentation/toaster-manual/toaster-manual-intro.xml b/yocto-poky/documentation/toaster-manual/toaster-manual-intro.xml index 9f4c38b2d..ee1dcbaba 100644 --- a/yocto-poky/documentation/toaster-manual/toaster-manual-intro.xml +++ b/yocto-poky/documentation/toaster-manual/toaster-manual-intro.xml @@ -14,111 +14,98 @@ remote build servers. </para> - <note> - <para> - This release of Toaster does allow you to configure and initiate - builds. - However, you cannot use Toaster to customize image recipes, which - still must either be done by hand or through - <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink>. - As Toaster matures, it eventually will equal and surpass Hob - functionality, at which time Hob will be deprecated. - </para> + <section id='intro-features'> + <title>Toaster Features</title> <para> - For more information on Hob, - see the - "<ulink url='&YOCTO_DOCS_DEV_URL;#image-development-using-hob'>Image Development Using Hob</ulink>" - section in the Yocto Project Development Manual. - </para> - </note> - - <section id='intro-modes'> - <title>Toaster Operational Modes</title> - - <para> - You can use Toaster in Analysis Mode or Build Mode: + Toaster allows you to configure and run builds, and it + provides extensive information about the build process. <itemizedlist> - <listitem><para id='toaster-analysis-mode'><emphasis>Analysis Mode:</emphasis> - In Analysis Mode, you can record builds and statistics. - In this Mode, you directly access the - <filename>bitbake</filename> command, which you then use to - build images.</para> - <para>Analysis Mode requires you to have first started - Toaster and then to initiate your build using the - <filename>bitbake</filename> command from the shell. - Toaster must be started before the build or it will not - collect build data.</para> - <para>Toaster has the following capabilities in - Analysis Mode: + <listitem><para id='toaster-build-features'> + <emphasis>Configure and Run Builds:</emphasis> + You can use the Toaster web interface to configure and + start your builds. + Builds started using the Toaster web interface are + organized into projects. + When you create a project, you are asked to select a + release, or version of the build system you want to + use for the project builds. + As shipped, Toaster supports Yocto Project releases 1.8 + and beyond. + With the Toaster web interface, you can: <itemizedlist> <listitem><para> - See what was built (recipes and packages) and what - packages were installed into your final image. + Browse layers listed in the various + <link linkend='layer-source'>layer sources</link> + that are available in your project (e.g. the + OpenEmbedded Metadata Index at + <ulink url='http://layers.openembedded.org/layerindex/'></ulink>). </para></listitem> <listitem><para> - Browse the directory structure of your image. + Browse images, recipes, and machines provided by + those layers. </para></listitem> <listitem><para> - See the value of all variables in your build - configuration, and which files set each value. + Import your own layers for building. </para></listitem> <listitem><para> - Examine error, warning and trace messages to aid - in debugging. + Add and remove layers from your configuration. </para></listitem> <listitem><para> - See information about the BitBake tasks executed - and reused during your build, including those that - used shared state. + Set configuration variables. </para></listitem> <listitem><para> - See dependency relationships between recipes, - packages and tasks + Select a target or multiple targets to build. </para></listitem> <listitem><para> - See performance information such as build time, - task time, CPU usage, and disk I/O. + Start your builds. </para></listitem> </itemizedlist> + Toaster also allows you to configure and run your builds + from the command line, and switch between the command line and + the web interface at any time. + Builds started from the command line appear within a special + Toaster project called "Command line builds". </para></listitem> - <listitem><para id='toaster-build-mode'><emphasis>Build Mode:</emphasis> - In Build Mode, Toaster handles the build configuration, - scheduling and execution. - In this mode, all your interaction with the build system - happens through the web interface. - You do not have direct access to the - <filename>bitbake</filename> command.</para> - <para>Using this mode, you configure and start your builds - within Toaster's GUI. - Each project can be configured for a specific version - of the build system. - As shipped, Toaster supports Yocto Project Releases 1.7 and - beyond.</para> - <para>Toaster has all the same capabilities in Build Mode - as it does in Analysis Mode plus the following: + <listitem><para id='toaster-analysis-features'> + <emphasis>Information About the Build Process:</emphasis> + Toaster also records extensive information about your builds. + Toaster collects data for builds you start from the web + interface and from the command line as long as Toaster + is running. + <note> + You must start Toaster before the build or it will not + collect build data. + </note></para> + <para>With Toaster you can: <itemizedlist> <listitem><para> - Browse layers listed in the various - <link linkend='layer-source'>layer sources</link> - that are available in your project (e.g. the - OpenEmbedded Metadata Index at - <ulink url='http://layers.openembedded.org/layerindex/'></ulink>). + See what was built (recipes and packages) and what + packages were installed into your final image. </para></listitem> <listitem><para> - Import your own layers for building. + Browse the directory structure of your image. </para></listitem> <listitem><para> - Add and remove layers from your configuration. + See the value of all variables in your build + configuration, and which files set each value. </para></listitem> <listitem><para> - Set configuration variables. + Examine error, warning, and trace messages to aid + in debugging. </para></listitem> <listitem><para> - Select a target or multiple targets to build. + See information about the BitBake tasks executed + and reused during your build, including those that + used shared state. </para></listitem> <listitem><para> - Start your builds. + See dependency relationships between recipes, + packages, and tasks. + </para></listitem> + <listitem><para> + See performance information such as build time, + task time, CPU usage, and disk I/O. </para></listitem> </itemizedlist> </para></listitem> @@ -132,8 +119,6 @@ <para> You can set Toaster up to run as a local instance or as a shared hosted service. - Regardless of how you set up Toaster, both Analysis and Build - Modes are available. </para> <para> diff --git a/yocto-poky/documentation/toaster-manual/toaster-manual-reference.xml b/yocto-poky/documentation/toaster-manual/toaster-manual-reference.xml index faca4ca73..3a46b61b7 100644 --- a/yocto-poky/documentation/toaster-manual/toaster-manual-reference.xml +++ b/yocto-poky/documentation/toaster-manual/toaster-manual-reference.xml @@ -159,25 +159,24 @@ </para> <para> - When you set up Toaster in Build Mode, you are prompted - to select a Toaster configuration file. + The Toaster startup script in + <filename>/bitbake/bin/toaster</filename> specifies + the location of a Toaster configuration file + <filename>toasterconf.json</filename> as the value of + the <filename>TOASTER_CONF</filename> variable. This configuration file is used to set up the initial configuration values within the Toaster database including the layer sources. - Three versions of the configuration file exist: + Two versions of the configuration file exist: <itemizedlist> <listitem><para> The first version of the file is found in the <filename>conf</filename> directory of the - <filename>meta-yocto</filename> layer + <filename>meta-poky</filename> layer (i.e. - <filename>meta-yocto/conf/toasterconf.json</filename>). + <filename>meta-poky/conf/toasterconf.json</filename>). This version contains the default Yocto Project configuration for Toaster. - You are prompted to select this file during the - Toaster set up process if you had cloned the - <filename>poky</filename> repository (i.e. - <filename>git://git.yoctoproject.org/poky</filename>). </para></listitem> <listitem><para> The second version of the file is in the @@ -186,19 +185,6 @@ (i.e. <filename>meta/conf/toasterconf.json</filename>). This version contains the default OpenEmbedded configuration for Toaster. - You are prompted to select this file during the - Toaster set up process if you had cloned the - <filename>openembedded-core</filename> repository - (i.e. - <filename>git://git.openembedded.org/openembedded-core</filename>). - </para></listitem> - <listitem><para> - The third version is a sample configuration - useful for when you want to set up a hosted - service in Build Mode. - You can find this version on the - <ulink url='https://wiki.yoctoproject.org/wiki/File:Toasterconf.json.txt.patch'>File:Toasterconf.json.txt.patch</ulink> - wiki page. </para></listitem> </itemizedlist> </para> @@ -228,10 +214,10 @@ "dirpath": "meta" }, { - "name": "meta-yocto", - "local_path": "meta-yocto", + "name": "meta-poky", + "local_path": "meta-poky", "vcs_url": "remote:origin", - "dirpath": "meta-yocto" + "dirpath": "meta-poky" }, { "name": "meta-yocto-bsp", @@ -307,10 +293,10 @@ <filename>toasterconf.json</filename> file you just edited. For example, if you cloned the <filename>poky</filename> repository and you edited the - <filename>meta-yocto/conf/toasterconf.json</filename> file, + <filename>meta-poky/conf/toasterconf.json</filename> file, you would type something like the following: <literallayout class='monospaced'> - $ bitbake/lib/toaster/manage.py loadconf /home/scottrif/poky/meta-yocto/conf/toasterconf.json + $ bitbake/lib/toaster/manage.py loadconf /home/scottrif/poky/meta-poky/conf/toasterconf.json </literallayout> After entering this command, you need to update the Toaster database with the information coming from your @@ -550,8 +536,7 @@ <title>JSON Files</title> <para> - If you are going to be using Toaster in Build Mode, it must - be initially configured before use. + You must configure Toaster before using it. Configuration customizes layer source settings and Toaster defaults for all users and is performed by the person responsible for Toaster Configuration (i.e the Toaster Administrator). @@ -577,23 +562,22 @@ <filename>toasterconf.json</filename>. The Toaster Administrator can customize the file prior to loading it into Toaster. - When you set up Toaster locally to run in Build Mode, the system - startup script actively looks for compatible configuration files - and prompts you to select a file to load if it detects that the - database has not been configured. + The <filename>TOASTER_CONF</filename> variable in the + Toaster startup script at <filename>bitbake/bin/toaster</filename> + specifies the location of the <filename>toasterconf.json</filename> file. </para> <section id='json-file-choices'> <title>Configuration File Choices</title> <para> - Three versions of the configuration file exist: + Two versions of the configuration file exist: <itemizedlist> <listitem><para> The - <filename>meta-yocto/conf/toasterconf.json</filename> + <filename>meta-poky/conf/toasterconf.json</filename> in the <filename>conf</filename> directory of the - Yocto Project's <filename>meta-yocto</filename> layer. + Yocto Project's <filename>meta-poky</filename> layer. This version contains the default Yocto Project configuration for Toaster. You are prompted to select this file during the Toaster @@ -613,15 +597,6 @@ <filename>openembedded-core</filename> repository (i.e. <filename>git://git.openembedded.org/openembedded-core</filename>). </para></listitem> - <listitem><para> - The <filename>Toasterconf.json.txt.patch</filename> - located on the - <ulink url='https://wiki.yoctoproject.org/wiki/File:Toasterconf.json.txt.patch'>File:Toasterconf.json.txt.patch</ulink> - wiki page. - This version of the file is useful as a sample - configuration for when you want to set up Toaster as a - hosted service in Build Mode. - </para></listitem> </itemizedlist> </para> </section> @@ -723,10 +698,10 @@ "dirpath": "meta" }, { - "name": "meta-yocto", - "local_path": "meta-yocto", + "name": "meta-poky", + "local_path": "meta-poky", "vcs_url": "remote:origin", - "dirpath": "meta-yocto" + "dirpath": "meta-poky" }, { "name": "meta-yocto-bsp", @@ -842,7 +817,7 @@ "description": "Yocto Project master", "bitbake": "master", "branch": "master", - "defaultlayers": [ "openembedded-core", "meta-yocto", "meta-yocto-bsp"], + "defaultlayers": [ "openembedded-core", "meta-poky", "meta-yocto-bsp"], "layersourcepriority": { "Imported layers": 99, "Local Yocto Project" : 10, "OpenEmbedded" : 0 }, "helptext": "Toaster will run your builds using the tip of the <a href=\"http://git.yoctoproject.org/cgit/cgit.cgi/poky/log/\">Yocto Project master branch</a>, where active development takes place. This is not a stable branch, so your builds might not work as expected." }, @@ -851,7 +826,7 @@ "description": "Yocto Project 2.0 Jethro", "bitbake": "jethro", "branch": "jethro", - "defaultlayers": [ "openembedded-core", "meta-yocto", "meta-yocto-bsp"], + "defaultlayers": [ "openembedded-core", "meta-poky", "meta-yocto-bsp"], "layersourcepriority": { "Imported layers": 99, "Local Yocto Project" : 10, "OpenEmbedded" : 0 }, "helptext": "Toaster will run your builds with the tip of the <a href=\"http://git.yoctoproject.org/cgit/cgit.cgi/poky/log/?h=jethro\">Yocto Project 2.0 \"Jethro\"</a> branch." }, @@ -860,7 +835,7 @@ "description": "Yocto Project 1.8 Fido", "bitbake": "fido", "branch": "fido", - "defaultlayers": [ "openembedded-core", "meta-yocto", "meta-yocto-bsp"], + "defaultlayers": [ "openembedded-core", "meta-poky", "meta-yocto-bsp"], "layersourcepriority": { "Imported layers": 99, "Local Yocto Project" : 10, "OpenEmbedded" : 0 }, "helptext": "Toaster will run your builds with the tip of the <a href=\"http://git.yoctoproject.org/cgit/cgit.cgi/poky/log/?h=fido\">Yocto Project 1.8 \"Fido\"</a> branch." }, @@ -869,7 +844,7 @@ "description": "Local Yocto Project", "bitbake": "HEAD", "branch": "HEAD", - "defaultlayers": [ "openembedded-core", "meta-yocto", "meta-yocto-bsp"], + "defaultlayers": [ "openembedded-core", "meta-poky", "meta-yocto-bsp"], "layersourcepriority": { "Imported layers": 99, "Local Yocto Project" : 10, "OpenEmbedded" : 0 }, "helptext": "Toaster will run your builds with the version of the Yocto Project you have cloned or downloaded to your computer." } @@ -1008,7 +983,7 @@ <literallayout class='monospaced'> $ bitbake/lib/toaster/manage.py checksettings </literallayout> - In Build Mode, Toaster uses settings that are based on the + Toaster uses settings that are based on the database to configure the building tasks. The <filename>checksettings</filename> command verifies that the database settings are valid in the sense that they have diff --git a/yocto-poky/documentation/toaster-manual/toaster-manual-setup-and-use.xml b/yocto-poky/documentation/toaster-manual/toaster-manual-setup-and-use.xml index 269356990..963b21122 100644 --- a/yocto-poky/documentation/toaster-manual/toaster-manual-setup-and-use.xml +++ b/yocto-poky/documentation/toaster-manual/toaster-manual-setup-and-use.xml @@ -17,32 +17,12 @@ </para> <para> - If you want to configure and start your builds using the - Toaster web interface - (i.e. "<link linkend='toaster-build-mode'>Build Mode</link>"), - navigate to the root of your + Navigate to the root of your <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> (e.g. <filename>poky</filename>): <literallayout class='monospaced'> $ cd poky </literallayout> - Next, start Toaster: - <literallayout class='monospaced'> - $ bitbake/bin/toaster - </literallayout> - Open your favourite browser and enter the following: - <literallayout class='monospaced'> - http://127.0.0.1:8000 - </literallayout> - If you would rather configure and start your builds - using the command line - (i.e. <link linkend='toaster-analysis-mode'>Analysis Mode</link>), - you can get Toaster to "listen" - to your builds and collect information about them. - To do that, navigate to the root of your Source Directory: - <literallayout class='monospaced'> - $ cd poky - </literallayout> Once in that directory, source the build environment script: <literallayout class='monospaced'> $ source oe-init-build-env @@ -53,12 +33,14 @@ <literallayout class='monospaced'> $ source ../bitbake/bin/toaster </literallayout> - You can now run builds normally. + You can now run your builds from the command line, or with + Toaster as explained in section + "<link linkend='using-the-toaster-web-interface'>Using the Toaster Web Interface</link>". </para> <para> - To see the build information provided by Toaster, open your - favorite browser and enter the following: + To access the Toaster web interface, open your favorite + browser and enter the following: <literallayout class='monospaced'> http://127.0.0.1:8000 </literallayout> @@ -72,12 +54,7 @@ By default, Toaster starts on port 8000. You can use the <filename>WEBPORT</filename> parameter to set a different port. - For example, either of the following commands sets the - port to "8400": - <literallayout class='monospaced'> - $ bitbake/bin/toaster webport=8400 - </literallayout> - or + For example, the following command sets the port to "8400": <literallayout class='monospaced'> $ source ../bitbake/bin/toaster webport=8400 </literallayout> @@ -88,18 +65,10 @@ <title>The Directory for Cloning Layers</title> <para> - If you are running Toaster in - <link linkend='toaster-build-mode'>Build Mode</link>, Toaster creates a <filename>_toaster_clones</filename> directory inside your Source Directory - (i.e. <filename>poky</filename>). - For example, suppose you use this command to start Toaster: - <literallayout class='monospaced'> - poky/bitbake/bin/toaster - </literallayout> - In this example, Toaster creates and uses the - <filename>poky/_toaster_clones</filename> - directory to clone any layers needed for your builds. + (i.e. <filename>poky</filename>) to clone any layers + needed for your builds. </para> <para> @@ -117,17 +86,9 @@ <title>The Build Directory</title> <para> - If you are running Toaster in - <link linkend='toaster-build-mode'>Build Mode</link>, Toaster creates a build directory within your Source - Directory (e.g. <filename>poky</filename>). - For example, suppose you use this command to start Toaster: - <literallayout class='monospaced'> - poky/bitbake/bin/toaster - </literallayout> - In this example, Toaster creates and uses the - <filename>poky/build</filename> - directory to execute the builds. + Directory (e.g. <filename>poky</filename>) to execute + the builds. </para> <para> @@ -136,7 +97,7 @@ the <filename>TOASTER_DIR</filename> environment variable, which takes precedence over your current working directory. Setting this environment variable causes Toaster to use - <filename>$TOASTER_DIR./build</filename> as the build directory. + <filename>$TOASTER_DIR/build</filename> as the build directory. </para> </section> @@ -154,1267 +115,519 @@ To access the Django administration interface, you must create a superuser by following these steps: <orderedlist> - <listitem><para> - If you used <filename>virtualenv</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: - <literallayout class='monospaced'> - $ source venv/bin/activate - </literallayout> - </para></listitem> - <listitem><para> - From the root of your checkout directory, invoke the - following command from <filename>manage.py</filename>: - <literallayout class='monospaced'> - $ ./bitbake/lib/toaster/manage.py createsuperuser - </literallayout> - </para></listitem> - <listitem><para> - Django prompts you for the username, which you need to - provide. - </para></listitem> - <listitem><para> - Django prompts you for an email address, which is - optional. - </para></listitem> - <listitem><para> - Django prompts you for a password, which you must provide. - </para></listitem> - <listitem><para> - Django prompts you to re-enter your password for verification. - </para></listitem> - </orderedlist> - After completing these steps, the following confirmation message - appears: - <literallayout class='monospaced'> - Superuser created successfully. - </literallayout> - </para> - - <para> - Creating a superuser allows you to access the Django administration - interface through a browser. - The URL for this interface is the same as the URL used for the - Toaster instance with "/admin" on the end. - For example, if you are running Toaster locally, use the - following URL: - <literallayout class='monospaced'> - http://127.0.0.1:8000/admin - </literallayout> - You can use the Django administration interface to set Toaster - configuration parameters such as the build directory, layer sources, - default variable values, and BitBake versions. - </para> - </section> - - <section id='toaster-setting-up-a-production-instance-of-toaster'> - <title>Setting Up a Production Instance of Toaster</title> - - <para> - You can use a production instance of Toaster to share the - Toaster instance with remote users, multiple users, or both. - The production instance is also the setup that can cope with - heavier loads on the web service. - Use the instructions in the following sections to set up - Toaster in - <link linkend='toaster-build-mode'>Build Mode</link> - where builds and projects are run, - viewed, and defined through the Toaster web interface. - </para> - - <section id='toaster-production-instance-requirements'> - <title>Requirements</title> - - <para> - Be sure you meet the following requirements: - <note> - You must comply with all Apache, - <filename>mod-wsgi</filename>, and Mysql requirements. - </note> - <itemizedlist> - <listitem><para> - Have all the build requirements as described in - "<link linkend='toaster-setting-up-the-basic-system-requirements'>Setting Up the Basic System Requirements</link>" - chapter. - </para></listitem> - <listitem><para> - Have an Apache webserver. - </para></listitem> - <listitem><para> - Have <filename>mod-wsgi</filename> for the Apache - webserver. - </para></listitem> - <listitem><para> - Use the Mysql database server. - </para></listitem> - <listitem><para> - If you are using Ubuntu 14.04.3, run the following: - <literallayout class='monospaced'> - $ sudo apt-get install apache2 libapache2-mod-wsgi mysql-server virtualenv libmysqlclient-dev - </literallayout> - </para></listitem> - <listitem><para> - If you are using Fedora 22 or a RedHat distribution, run - the following: - <literallayout class='monospaced'> - $ sudo dnf install httpd mod_wsgi python-virtualenv gcc mysql-devel - </literallayout> - </para></listitem> - </itemizedlist> - </para> - </section> - - <section id='toaster-installation-steps'> - <title>Installation</title> - - <para> - Perform the following steps to install Toaster: - <orderedlist> - <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; - </literallayout> - </para></listitem> - <listitem><para> - Initialize a virtual environment and install Toaster - dependencies. - Using a virtual environment 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 - </literallayout> - <note> - Isolating these packages is not required but is - recommended. - Alternatively, you can use your operating system's - package manager to install the packages. - </note> - </para></listitem> - <listitem><para> - Configure Toaster by editing - <filename>/var/www/toaster/poky/bitbake/lib/toaster/toastermain/settings.py</filename> - as follows: - <itemizedlist> - <listitem><para> - Edit the <filename>DATABASE</filename> settings: - <literallayout class='monospaced'> - DATABASES = { - 'default': { - 'ENGINE': 'django.db.backends.mysql', - 'NAME': 'toaster_data', - 'USER': 'toaster', - 'PASSWORD': 'yourpasswordhere', - 'HOST': 'localhost', - 'PORT': '3306', - } - } - </literallayout> - </para></listitem> - <listitem><para> - Edit the <filename>SECRET_KEY</filename>: - <literallayout class='monospaced'> - SECRET_KEY = '<replaceable>your_secret_key</replaceable>' - </literallayout> - </para></listitem> - <listitem><para> - Edit the <filename>STATIC_ROOT</filename>: - <literallayout class='monospaced'> - STATIC_ROOT = '/var/www/toaster/static_files/' - </literallayout> - </para></listitem> - <listitem><para> - Enable Build Mode by adding the following - line to <filename>settings.py</filename>: - <literallayout class='monospaced'> - BUILD_MODE=True - </literallayout> - </para></listitem> - </itemizedlist> - </para></listitem> - <listitem><para> - Add the database and user to the <filename>mysql</filename> - server defined earlier: - <literallayout class='monospaced'> - $ mysql -u root -p - mysql> CREATE DATABASE toaster_data; - mysql> CREATE USER 'toaster'@'localhost' identified by 'yourpasswordhere'; - mysql> GRANT all on toaster_data.* to 'toaster'@'localhost'; - mysql> quit - </literallayout> - </para></listitem> - <listitem><para> - Get Toaster to create the database schema, - 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-yocto/conf/toasterconf.json ./bitbake/lib/toaster/manage.py checksettings - $ ./bitbake/lib/toaster/manage.py collectstatic - </literallayout> - </para> - - <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 - schema has had changes propagated correctly (i.e. - migrations). - </para> - - <para> - The next line sets the Toaster root directory - <filename>TOASTER_DIR</filename> and the location of - the Toaster configuration file - <filename>TOASTER_CONF</filename>, which is - relative to the Toaster root directory - <filename>TOASTER_DIR</filename>. - For more information on the Toaster configuration file - <filename>TOASTER_CONF</filename>, see the - <link linkend='toaster-json-files'>JSON Files</link> - section of this manual. - </para> - - <para> - This line also runs the <filename>checksettings</filename> - command, which configures the location of the Toaster - <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build directory</ulink>. - The Toaster root directory <filename>TOASTER_DIR</filename> - determines where the Toaster build directory - is created on the file system. - In the example above, - <filename>TOASTER_DIR</filename> is set as follows: - <literallayout class="monospaced"> - /var/www/toaster/poky - </literallayout> - This setting causes the Toaster build directory to be: - <literallayout class="monospaced"> - /var/www/toaster/poky/build - </literallayout> - </para> - - <para> - 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. - </para></listitem> - <listitem><para> - Add an Apache configuration file for Toaster to your Apache web - server's configuration directory. - If you are using Ubuntu or Debian, put the file here: - <literallayout class='monospaced'> - /etc/apache2/conf-available/toaster.conf - </literallayout> - If you are using Fedora or RedHat, put it here: - <literallayout class='monospaced'> - /etc/httpd/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 - </Directory> - - WSGIDaemonProcess toaster_wsgi python-path=/var/www/toaster/poky/bitbake/lib/toaster:/var/www/toaster/venv/lib/python2.7/site-packages - - WSGIScriptAlias / "/var/www/toaster/poky/bitbake/lib/toaster/toastermain/wsgi.py" - <Location /> - WSGIProcessGroup toastern_wsgi - </Location> - </literallayout> - If you are using Ubuntu or Debian, - you will need to enable the config and module for Apache: - <literallayout class='monospaced'> - $ sudo a2enmod wsgi - $ sudo a2enconf toaster - $ chmod +x bitbake/lib/toaster/toastermain/wsgi.py - </literallayout> - Finally, restart Apache to make sure all new configuration - is loaded. - For Ubuntu and Debian use: - <literallayout class='monospaced'> - $ sudo service apache2 restart - </literallayout> - For Fedora and RedHat use: - <literallayout class='monospaced'> - $ sudo service httpd restart - </literallayout> - </para></listitem> - <listitem><para> - Install the build runner service. - This service needs to be running in order to dispatch - builds. - Use this command: - <literallayout class='monospaced'> - /var/www/toaster/poky/bitbake/lib/toaster/manage.py runbuilds - </literallayout> - Here is an example: - <literallayout class='monospaced'> - #!/bin/sh - # toaster run builds dispatcher - cd /var/www/toaster/ - source ./venv/bin/activate - ./bitbake/lib/toaster/manage.py runbuilds - </literallayout> - </para></listitem> - </orderedlist> - You can now open up a browser and start using Toaster. - </para> - </section> - </section> - - - - -<!-- <section id='using-toaster-in-analysis-mode'> - <title>Using Toaster in Analysis Mode</title> - - - <para> - This section describes how to use Toaster in Analysis Mode - after setting Toaster up as a local instance or as a hosted - service. - </para> - - <section id='setting-up-locally-and-running-in-analysis-mode'> - <title>Setting Up Locally and Running in Analysis Mode</title> - - <para> - Follow these steps to set up a local instance of Toaster and - then run in Analysis Mode: - <orderedlist> - <listitem><para><emphasis>Prepare your Build System:</emphasis> - Be sure your system has the Toaster requirements - by following the steps in the - "<link linkend='toaster-establishing-toaster-system-dependencies'>Establishing Toaster System Dependencies</link>" - section. - </para></listitem> - <listitem><para><emphasis>Get Set Up to Use the Yocto Project:</emphasis> - Get the requirements set up so that you can use the - Yocto Project to build images. - See the - "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>Setting Up to Use the Yocto Project</ulink>" - section in the Yocto Project Quick Start for information. - </para></listitem> - <listitem><para><emphasis>Source your Build Environment Setup Script:</emphasis> - From your - <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> - (e.g. <filename>poky/build</filename>), source the build - environment setup script - <ulink url="&YOCTO_DOCS_REF_URL;#structure-core-script"><filename>&OE_INIT_FILE;</filename></ulink> - or - <ulink url="&YOCTO_DOCS_REF_URL;#structure-memres-core-script"><filename>oe-init-build-env-memres</filename></ulink>. - </para></listitem> - <listitem><para><emphasis>Start Toaster:</emphasis> - From the - <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>, - start Toaster: - <literallayout class='monospaced'> - $ source toaster start - </literallayout> - </para></listitem> - <listitem><para><emphasis>Start Your Build Using BitBake:</emphasis> - Use the <filename>bitbake</filename> command to start your - build. - Here is an example that builds the - <filename>core-image-minimal</filename> image: - <literallayout class='monospaced'> - $ bitbake core-image-minimal - </literallayout> - </para></listitem> - <listitem><para><emphasis>Open Your Browser:</emphasis> - Open your browser and visit - <filename>http://host:port/toastergui</filename>. - For host and port values, see the output of the - <filename>source toaster start</filename> command. - For information on how to use Toaster, see the - "<link linkend='using-the-toaster-web-interface'>Using the Toaster Web Interface</link>" - section. - </para></listitem> - </orderedlist> - </para> - - <para> - - </para> - </section> - - <section id='setting-up-a-hosted-service-and-running-in-analysis-mode'> - <title>Setting Up a Hosted Service and Running in Analysis Mode</title> - - <para> - A hosted service resides on a shared server and allows - multiple users to take advantage of Toaster. - </para> - - <para> - In a production environment, you might want to have multiple - local instances of the Toaster Logging Interface running on - various remote build machines, and have those local instances - access and use a single web server. - To do this, you need to do the following: - <itemizedlist> - <listitem><para> - Maintain a common SQL database. - </para></listitem> - <listitem><para> - Set up separate instances of BitBake servers - and Toaster Logging Interfaces for each of those - separate BitBake servers. - </para></listitem> - </itemizedlist> - </para> - - <para> - The common SQL database allows the Web server to show data from - all the various BitBake builds. - Setting the SQL database outside of any - <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> - maintains a separation between the various builds. - The BitBake servers, the SQL server, and the Web server or - servers can be run on separate machines. - </para> - - <para> - Follow these steps to set up and run a hosted service and run - Toaster in Analysis Mode: - <note> - The steps assume a Toaster installation path of - <filename>/opt/bitbake/</filename>. - </note> - <orderedlist> - <listitem><para><emphasis>Prepare your Build System:</emphasis> - Be sure your system has the Toaster requirements - by following the steps in the - "<link linkend='toaster-establishing-toaster-system-dependencies'>Establishing Toaster System Dependencies</link>" - section. - </para></listitem> - <listitem><para><emphasis>Get Set Up to Use the Yocto Project:</emphasis> - Get the requirements set up so that you can use the - Yocto Project to build images. - See the - "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>Setting Up to Use the Yocto Project</ulink>" - section in the Yocto Project Quick Start for information. - </para></listitem> - <listitem><para><emphasis>Install and Set up the Database Server:</emphasis> - You can use any SQL server out of the box. - It is recommended that you use - <filename>mysql-server</filename> because it has - the advantages of advanced SQL features along with a - fast and reliable database. - However, setting up <filename>mysql-server</filename> - is more complex and might require a Database - Administrator to tune it.</para> - <para>Another supported database backend is - <filename>sqlite3</filename>. - With <filename>sqlite3</filename>, you have the - advantage of no configuration and an easy installation. - However, Toaster still requires direct access to the - backend. - The <filename>sqlite</filename> backend is also slower - as compared to <filename>mysql-server</filename>, and - has no transactional support.</para> - <para>You should set up proper username and password - access on the shared database for everyone that will - be using Toaster. - You need administrator rights for the root account, - which is not the same thing as root access on the - machine. - Here is an example that installs - <filename>mysql-server</filename> and sets up - some user accounts and the database. - <literallayout class='monospaced'> - $ apt-get install mysql-server - $ mysql -u root - mysql> CREATE USER 'newuser'@'localhost' IDENTIFIED BY 'password'; - mysql> GRANT ALL PRIVILEGES ON * . * TO 'newuser'@'localhost'; - mysql> GRANT ALL PRIVILEGES ON * . * TO 'newuser'@'localhost'; - mysql> CREATE DATABASE 'toaster'; - </literallayout> - You need a separate clone of the - <ulink url='&YOCTO_DOCS_DEV_URL;#source-repositories'>Source Repositories</ulink> - for the Database Server. - This clone is only used for getting the latest Toaster - files. - You can set this up using the following Git command. - Be sure to set up the directory outside of any - Build Directories. - <literallayout class='monospaced'> - $ git clone git://git.yoctoproject.org/poky - </literallayout> - In the separately cloned tree for the Database Server, - edit the - <filename>bitbake/lib/toaster/toastermain/settings.py</filename> - file so that the <filename>DATABASES</filename> value - points to the previously created database server. - Use the username and password established - earlier. - Here is an example: - <literallayout class='monospaced'> - $ cat /opt/bitbake/lib/toaster/toastermain/settings.py - ... - DATABASES = { - 'default': { - 'ENGINE': 'django.db.backends.mysql', - 'NAME': 'toaster', - 'USER': 'newuser', - 'PASSWORD': 'password', - 'HOST': '192.168.0.25', - 'PORT': '3306', - } - ... - </literallayout> - </para></listitem> - <listitem><para><emphasis>Install and Set Up the Web Server:</emphasis> - For a production environment, it is recommended that - you install and set up a front-end web server. - This server allows for load balancing and - multi-threading over Toaster and - <ulink url='https://docs.djangoproject.com/en/1.7/howto/deployment/wsgi/'><filename>django</filename> WSGI</ulink>. - Here is an example that uses Apache web server. - <literallayout class='monospaced'> - $ apt-get install apache2 libapache2-mod-wsgi - $ a2enmod wsgi - $ cat /etc/apache2/sites-available/000-default.conf - - ... - - # the WSGIPythonPath is global - WSGIPythonPath /opt/bitbake/lib/toaster/ - - ... - - #snip - in VirtualHost - WSGIScriptAlias / /opt/bitbake/lib/toaster/toastermain/wsgi.py - - <Directory //opt/bitbake/lib/toaster/toastermain/> - <Files wsgi.py> - Require all granted - </Files> - </Directory> - - ... - </literallayout> - You need to collect static media from Toaster and - continue configuring Apache to serve that static - media: - <literallayout class='monospaced'> - $ mkdir /var/www.html/static && cd /var/www.html/static - $ /opt/bitbake/lib/toaster/manage.py collectstatic - $ cat /etc/apache2/sites-available/000-default.conf - - ... - - # in VirtualHost, AHEAD of the WSGIScriptAlias definition - Alias /static/ /var/www.html/static/ - - <Directory /var/www.html/static/> - Require all granted - </Directory> - - ... - - WSGIScript Alias / /opt/bitbake/lib/toaster/toastermain/wsgi.py - - ... - </literallayout> - </para></listitem> - <listitem><para><emphasis>Start Toaster:</emphasis> - Synchronize the databases for toaster, and then start - up the web server. - Here is an example that continues with the assumed - components from the previous steps: - <literallayout class='monospaced'> - $ /opt/bitbake/lib/toaster/manage.py syncdb - $ /opt/bitbake/lib/toaster/manage.py migrate orm - $ /opt/bitbake/lib/toaster/manage.py migrate bldcontrol - - $ service apache2 restart - </literallayout> - You can find general documentation on - <filename>manage.py</filename> at the - <ulink url='https://docs.djangoproject.com/en/1.7/ref/django-admin/'>Django</ulink> - site. - For reference information on Toaster-specific - <filename>manage.py</filename> commands, - see the - "<link linkend='toaster-useful-commands'>Useful Commands</link>" - section. - </para></listitem> - <listitem><para><emphasis>Enable Build Logging to the Common SQL Server for Each Build Directory you are Using:</emphasis> - You need to make sure that the - <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-toaster'><filename>toaster</filename></ulink> - class and build history are enabled. - This is done in a - <filename>toaster.conf</filename> file that is - created automatically by the toaster - <filename>start</filename> command, - and that lives inside the - <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> - in <filename>/conf/toaster.conf</filename>.</para> - <para>That file should include the following line: - <literallayout class='monospaced'> - INHERIT += "toaster buildhistory" - </literallayout> - For information on build history, see the - "<ulink url='&YOCTO_DOCS_REF_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>" - section in the Yocto Project Development - Manual.</para> - <para>You also need to point to the database that you set - up in step 3. - You can do this by exporting the <filename>DATABASE_URL</filename> - variable as follows: - <literallayout class='monospaced'> - export DATABASE_URL=mysql://newuser:password@192.168.0.25:3306/toaster - </literallayout> - This example assumes that you are using - <filename>mysql-server</filename>. - The IP address should be the IP address of your - database server. - </para></listitem> - <listitem><para><emphasis>Source your Build Environment Setup Script:</emphasis> - From your - <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> - on each of the build systems, - (e.g. <filename>poky/build</filename>), source the - build environment setup script (i.e. - <ulink url="&YOCTO_DOCS_REF_URL;#structure-core-script"><filename>&OE_INIT_FILE;</filename></ulink> - or - <ulink url="&YOCTO_DOCS_REF_URL;#structure-memres-core-script"><filename>oe-init-build-env-memres</filename></ulink>). - </para></listitem> - <listitem><para><emphasis>Start the BitBake Server:</emphasis> - Start the BitBake server using the following command: - <literallayout class='monospaced'> - $ bitbake ‐‐postread conf/toaster.conf ‐‐server-only -t xmlrpc -B localhost:0 && export BBSERVER=localhost:-1 - </literallayout> - </para></listitem> - <listitem><para><emphasis>Start the Logging Server:</emphasis> - Start the Toaster Logging Interface using the following - command: - <literallayout class='monospaced'> - $ nohup bitbake ‐‐observe-only -u toasterui >toaster_ui.log & - </literallayout> - <note> - No hard-coded ports are used in the BitBake options - as there is enough code to run - <filename>autodiscovery</filename> for BitBake - ports. - Doing so prevents collisions. - </note> - </para></listitem> - <listitem><para><emphasis>Start Builds Using BitBake:</emphasis> - Use the <filename>bitbake</filename> command to start a - build on a build system. - Here is an example that builds the - <filename>core-image-minimal</filename> image: - <literallayout class='monospaced'> - $ bitbake core-image-minimal - </literallayout> - When you are finished with a build in a given - Build Directory, be sure to <filename>kill</filename> - the BitBake server for that build area: - <literallayout class='monospaced'> - $ bitbake -m - </literallayout> - </para></listitem> - </orderedlist> - </para> - - <para> - For information on how to use the Toaster web interface, - see the - "<link linkend='using-the-toaster-web-interface'>Using the Toaster Web Interface</link>" - section. - </para> - </section> - </section> - - <section id='using-toaster-in-build-mode'> - <title>Using Toaster in Build Mode</title> - - <para> - This section describes how to use Toaster in Build Mode - after setting Toaster up as a local instance or as a hosted - service. - </para> - - <section id='setting-up-locally-and-running-in-build-mode'> - <title>Setting Up Locally and Running in Build Mode</title> - - <para> - Follow these steps to set up a local instance of Toaster and - then run in Build Mode: - <orderedlist> - <listitem><para><emphasis>Prepare your Build System:</emphasis> - Be sure your system has the Toaster requirements - by following the steps in the - "<link linkend='toaster-establishing-toaster-system-dependencies'>Establishing Toaster System Dependencies</link>" - section. - </para></listitem> - <listitem><para><emphasis>Get Set Up to Use the Yocto Project:</emphasis> - Get the requirements set up so that you can use the - Yocto Project to build images. - See the - "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>Setting Up to Use the Yocto Project</ulink>" - section in the Yocto Project Quick Start for information. - </para></listitem> - <listitem><para><emphasis>Start Toaster:</emphasis> - From the root of the source directory (e.g - <filename>poky/</filename>), run the following command: - <literallayout class='monospaced'> - $ bitbake/bin/toaster - </literallayout> - </para></listitem> - <listitem><para><emphasis>Create a Superuser:</emphasis> - Django will ask you if you want to create a superuser. - You can skip this step, but it is recommended that you - create a superuser. - You can use the superuser to access the Django - administration interface and make changes to the - Toaster configuration. - </para></listitem> - <listitem><para><emphasis>Select the Build Log Directory:</emphasis> - Toaster asks you to specify the directory where you - want to store the build log files. - Choosing a directory for these files makes sure they - are always available to you. - If you do not choose a directory, the logs can - disappear (e.g. deleting the Build Directory).</para> - <para>When Toaster prompts you for the Build Log - directory, you can select the suggested default - or provide a path to a different directory. - </para></listitem> - <listitem><para><emphasis>Specify the Layer Checkout Directory:</emphasis> - Toaster asks you to specify the directory into which - layers are checked out. - Toaster clones any layers needed for your builds - inside this directory.</para> - <para>When Toaster prompts you for the Layer - checkout directory, you can select the suggested - default or provide a path to a different directory. - </para></listitem> - <listitem><para><emphasis>Specify the Build Directory Path:</emphasis> - Toaster asks you to specify the path to the - Build Directory. - You can select the suggested default or provide a - path to a different directory. - </para></listitem> - <listitem><para><emphasis>Choose Whether or not to Import a Default Toaster Configuration File:</emphasis> - Toaster asks you if you want to import a default - Toaster configuration file. - Toaster configurations are stored in - JSON files called - <filename>toasterconf.json</filename>. - For information on JSON files, see the - "<link linkend='toaster-json-files'>JSON Files</link>" - section.</para> - <para>You can skip importing a configuration file - by entering "0" at the prompt. - However, it is recommended that you import one of the - configuration files listed during this step. - You can always amend the imported configuration during - a later stage through the Django administration - interface.</para> - <para>For general information on Django, see the - available - <ulink url='https://docs.djangoproject.com/en/1.7/'>documentation</ulink>. - You can also find information on Toaster-specific - <filename>manage.py</filename> commands in the - "<link linkend='toaster-useful-commands'>Useful Commands</link>" - section. - </para></listitem> - <listitem><para><emphasis>Open the Browser:</emphasis> - If no browser window appears, open your favorite - browser and enter the following: - <literallayout class='monospaced'> - http://localhost:8000/toastergui - </literallayout> - You can now use the Toaster web interface. - </para></listitem> - </orderedlist> - </para> - </section> - - <section id='setting-up-a-hosted-service-and-running-in-build-mode'> - <title>Setting Up a Hosted Service and Running in Build Mode</title> - - <para> - Follow these steps to set up a hosted service and run Toaster - in Build Mode: - <orderedlist> - <listitem><para><emphasis>Prepare your Build System:</emphasis> - Be sure your system has the Toaster requirements - by following the steps in the - "<link linkend='toaster-establishing-toaster-system-dependencies'>Establishing Toaster System Dependencies</link>" - section. - </para></listitem> - <listitem><para><emphasis>Get Set Up to Use the Yocto Project:</emphasis> - Get the requirements set up so that you can use the - Yocto Project to build images. - See the - "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>Setting Up to Use the Yocto Project</ulink>" - section in the Yocto Project Quick Start for information. - </para></listitem> - <listitem><para><emphasis>Be Sure Management is Enabled:</emphasis> - If you are running Toaster under Apache, you need to - be sure management is enabled. - To enable management, set - <filename>MANAGED</filename> to "True" by adding - the following to the - <filename>bitbake/lib/toaster/settings.py</filename> - file: - <literallayout class='monospaced'> - MANAGED="True" - </literallayout> - </para></listitem> - <listitem><para><emphasis>Set Up Toaster for Normal Usage:</emphasis> - You need to configure each build environment, layer - sources, and BitBake versions.</para> - <para>Verify that your releases have been loaded correctly by - using the Toaster web interface to create a new - project. - Check the "Releases" dropdown menu to be sure your - newly specified releases exist.</para> - <para>If you want to use the administration interface - for this step, here is a set of example commands - with some descriptions as an example: - <literallayout class='monospaced'> - # Create the user under which the builds will run - $ adduser poky - - # Bring up the administration interface - $xdg-open http://<replaceable>server-address</replaceable>/admin/ - - # Login with the admin user previously created - - # Go to the BuildEnvironment object in Build Environments and - # set address to local host, sourcedir to /home/poky, and - # builddir to /home/pokybuild. - # - # Save your changes and exit - - # Go to Home, Layer Sources and select add Layer Source - # Name: OpenEmbedded, Sourcetype: layerindex, - # Apiurl: http://layers openembedded.org/layerindex/api/ - # Save your changes and exit - - # Go to Home, Bitbake Versions, Add bitbake version; - # Take version information from: http://git.openembedded.org/bitbake/refs/heads, - # This example assumes "master" version. - # set Name: master, Giturl git://git.openembedded.org/bitbake - # branch master, dirpath / - # Save your changes and exit - </literallayout> - You also need to configure the project releases, the - default variables, and update information from the - layer index. - Continuing with the example: - <literallayout class='monospaced'> - # Go to Home, Releases, Add release - # set Name: master, Description: Current master release, select Bitbake Version, - # and Branch: master - # Save your changes and exit - - # Go to Home, Toaster Settings, select the Setting for DEFAULT_RELEASE - # set Helptext: This selects the default release., Value: master - # Save your changes and exit - - # Go to Home, Bitbake Versions, Add bitbake version; - # take version information from : http://git.openembedded.org/bitbake/refs/heads, - # this manual assumes the master version - # set Name: master, Giturl git://git.openembedded.org/bitbake - # branch master, dirpath / - # Save your changes and exit - - # Update the information - # bitbake/lib/toaster/manage.py lsupdates - </literallayout> - For reference information on Toaster-specific - <filename>manage.py</filename> commands, see the - "<link linkend='toaster-useful-commands'>Useful Commands</link>" - section. - </para></listitem> - <listitem><para><emphasis>Install and Set up the Database Server:</emphasis> - You can use any SQL server out of the box. - It is recommended that you use - <filename>mysql-server</filename> because it has - the advantages of advanced SQL features along with a - fast and reliable database. - However, setting up <filename>mysql-server</filename> - is more complex and might require a Database - Administrator to tune it.</para> - <para>Another supported database backend is - <filename>sqlite3</filename>. - With <filename>sqlite3</filename>, you have the - advantage of no configuration and an easy installation. - However, Toaster still requires direct access to the - backend. - The <filename>sqlite</filename> backend is also slower - as compared to <filename>mysql-server</filename>, and - has no transactional support.</para> - <para>You should set up proper username and password - access on the shared database for everyone that will - be using Toaster. - You need administrator rights for the root account, - which is not the same thing as root access on the - machine. - Here is an example that installs - <filename>mysql-server</filename> and sets up - some user accounts and the database. - <literallayout class='monospaced'> - $ apt-get install mysql-server - $ mysql -u root - mysql> CREATE USER 'newuser'@'localhost' IDENTIFIED BY 'password'; - mysql> GRANT ALL PRIVILEGES ON * . * TO 'newuser'@'localhost'; - mysql> GRANT ALL PRIVILEGES ON * . * TO 'newuser'@'localhost'; - mysql> CREATE DATABASE 'toaster'; - </literallayout> - You need a separate clone of the - <ulink url='&YOCTO_DOCS_DEV_URL;#source-repositories'>Source Repositories</ulink> - for the Database Server. - This clone is only used for getting the latest Toaster - files. - You can set this up using the following Git command. - Be sure to set up the directory outside of any - Build Directories. - <literallayout class='monospaced'> - $ git clone git://git.yoctoproject.org/poky - </literallayout> - In the separately cloned tree for the Database Server, - edit the - <filename>bitbake/lib/toaster/toastermain/settings.py</filename> - file so that the <filename>DATABASES</filename> value - points to the previously created database server. - Use the username and password established - earlier. - Here is an example: - <literallayout class='monospaced'> - $ cat /opt/bitbake/lib/toaster/toastermain/settings.py - ... - DATABASES = { - 'default': { - 'ENGINE': 'django.db.backends.mysql', - 'NAME': 'toaster', - 'USER': 'newuser', - 'PASSWORD': 'password', - 'HOST': '192.168.0.25', - 'PORT': '3306', - } - ... - </literallayout> - </para></listitem> - <listitem><para><emphasis>Create the Database</emphasis> - Use the following commands to create the default - database structure: - <literallayout class='monospaced'> - $ bitbake/lib/toaster/manage.py syncdb - $ bitbake/lib/toaster/manage.py migrate orm - $ bitbake/lib/toaster/manage.py migrate bldcontrol - </literallayout> - The interface asks you if you want to create a - superuser. - Do not skip this step. - You will use the superuser account to access the - administration interface and make changes to the - Toaster configuration. - </para></listitem> - <listitem><para><emphasis>Select Where the Build Process Takes Place:</emphasis> - You need to create three directories for storing - build artifacts, downloading sources, and running - builds. - All three directories need to be writable by - the user, which is "poky" in this example. - The build artifacts directory needs to readable by the - apache user. - You also need free disk space in the range of - 100 Gbytes. - Following are three suggested directories: - <literallayout class='monospaced'> - /home/poky/buildartifacts/ - /home/poky/build/ - /home/poky/sources/ - </literallayout> - </para></listitem> - <listitem><para><emphasis>Set Up the <filename>toasterconf.json</filename> File:</emphasis> - <ulink url='https://wiki.yoctoproject.org/wiki/File:Toasterconf.json.txt.patch'>Download the hosted <filename>toasterconf.json</filename> file</ulink> - from the Yocto Project wiki and edit it to suit your - environment. - For information on the relevant sections of the file, - see the - "<link linkend='toaster-json-files'>JSON Files</link>" - section.</para> - <para>After editing the file, load it by running - the following: - <literallayout class='monospaced'> - $ bitbake/lib/toaster/manage.py loadconf path-to-toasterconf.json-file - </literallayout> - For reference information on Toaster-specific - <filename>manage.py</filename>, see the - "<link linkend='toaster-useful-commands'>Useful Commands</link>" - section. - </para></listitem> - <listitem><para><emphasis>Check the Toaster Settings:</emphasis> - Configure the build environment by running the - following: - <literallayout class='monospaced'> - $ bitbake/lib/toaster/manage.py checksettings - </literallayout> - When prompted, paste in the directory paths created - previously during Step 7. - For reference information on Toaster-specific - <filename>manage.py</filename>, see the - "<link linkend='toaster-useful-commands'>Useful Commands</link>" - section. - </para></listitem> - <listitem><para><emphasis>Install and Set Up the Web Server:</emphasis> - For a production environment, it is recommended that - you install and set up a front-end web server. - This server allows for load balancing and - multi-threading over Toaster and - <ulink url='https://docs.djangoproject.com/en/1.7/howto/deployment/wsgi/'><filename>django</filename> WSGI</ulink>. - Here is an example that uses Apache web server: - <literallayout class='monospaced'> - $ apt-get install apache2 libapache2-mod-wsgi - $ a2enmod wsgi - $ cat /etc/apache2/sites-available/000-default.conf - - ... - - # the WSGIPythonPath is global - WSGIPythonPath /opt/bitbake/lib/toaster/ - - ... - - #snip - in VirtualHost - WSGIScriptAlias / /opt/bitbake/lib/toaster/toastermain/wsgi.py - - <Directory //opt/bitbake/lib/toaster/toastermain/> - <Files wsgi.py> - Require all granted - </Files> - </Directory> - - ... - </literallayout> - You need to collect static media from Toaster and - continue configuring Apache to serve that static - media: - <literallayout class='monospaced'> - $ mkdir /var/www.html/static && cd /var/www.html/static - $ /opt bitbake/lib/toaster/manage.py collectstatic - $ cat /etc/apache2/sites-available/000-default.conf - - ... - - # in VirtualHost, AHEAD of the WSGIScriptAlias definition - Alias /static/ /var/www.html/static/ - - <Directory /var/www.html/static/> - Require all granted - </Directory> - - ... - - WSGIScript Alias / /opt/bitbake/lib/toaster/toastermain/wsgi.py - - ... - </literallayout> - </para></listitem> - <listitem><para><emphasis>Start Toaster:</emphasis> - Synchronize the databases for Toaster, and then start - up the web server. - Here is an example that continues with the assumed - components from the previous steps: - <literallayout class='monospaced'> - $ /opt/bitbake/lib/toaster/manage.py syncdb - $ /opt/bitbake/lib/toaster/manage.py migrate orm - $ /opt/bitbake/lib/toaster/manage.py migrate bldcontrol - - $ service apache2 restart - </literallayout> - For reference information on the - <filename>manage.py</filename> commands used here, - see the - "<link linkend='toaster-useful-commands'>Useful Commands</link>" - section. - </para></listitem> - <listitem><para><emphasis>Set up Build Control and Open the Web Interface:</emphasis> - You need to run the build control manager. - You can do this as shown in the following example: - <literallayout class='monospaced'> - # as the "poky" user, start the runbuilds command in a loop (or put it in crontab!) - $ sudo -i -u poky - $ while true; do /opt/bitbake/lib/toaster/manage.py runbuilds; sleep 10; done - - # open up the web interface - $ xdg-open http://[server-address]/toastergui/ - </literallayout> - It is suggested that you enable build control by - setting <filename>runbuilds</filename> in the - <filename>crontab</filename> as follows: - <literallayout class='monospaced'> - $ crontab -l - * * * * * /opt/bitbake/lit/toaster/manage.py runbuilds - </literallayout> - </para></listitem> - <listitem><para><emphasis>Open the Browser:</emphasis> - Once the Apache server is running, connect to it with - your favorite browser and verify that the Toaster - interface comes up: - <literallayout class='monospaced'> - http://localhost:8000/toastergui - </literallayout> - You can track accesses and errors in the Apache - service logs. - </para></listitem> - </orderedlist> - </para> - </section> - </section> ---> - - <section id='using-the-toaster-web-interface'> - <title>Using the Toaster Web Interface</title> - - <para> - The Toaster web interface allows you to do the following: - <itemizedlist> - <listitem><para> - Browse published layers in the - <ulink url='http://layers.openembedded.org'>OpenEmbedded Metadata Index</ulink> - that are available for your selected version of the build - system. - </para></listitem> - <listitem><para> - Import your own layers for building. - </para></listitem> - <listitem><para> - Add and remove layers from your configuration. - </para></listitem> - <listitem><para> - Set configuration variables. - </para></listitem> - <listitem><para> - Select a target or multiple targets to build. - </para></listitem> - <listitem><para> - Start your builds. - </para></listitem> - <listitem><para> - See what was built (recipes and packages) and what - packages were installed into your final image. - </para></listitem> - <listitem><para> - Browse the directory structure of your image. - </para></listitem> - <listitem><para> - See the value of all variables in your build configuration, - and which files set each value. - </para></listitem> - <listitem><para> - Examine error, warning and trace messages to aid in - debugging. - </para></listitem> - <listitem><para> - See information about the BitBake tasks executed and - reused during your build, including those that used - shared state. - </para></listitem> - <listitem><para> - See dependency relationships between recipes, packages - and tasks. - </para></listitem> - <listitem><para> - See performance information such as build time, task time, - CPU usage, and disk I/O. - </para></listitem> - </itemizedlist> - </para> - - <section id='web-interface-videos'> - <title>Toaster Web Interface Videos</title> - - <para> - Following are several videos that show how to use the Toaster GUI: - <itemizedlist> - <listitem><para><emphasis>Build Configuration:</emphasis> - This - <ulink url='https://www.youtube.com/watch?v=qYgDZ8YzV6w'>video</ulink> - overviews and demonstrates build configuration for Toaster. - </para></listitem> - <listitem><para><emphasis>Build Custom Layers:</emphasis> - This - <ulink url='https://www.youtube.com/watch?v=QJzaE_XjX5c'>video</ulink> - shows you how to build custom layers that are used with - Toaster. - </para></listitem> - <listitem><para><emphasis>Toaster Homepage and Table Controls:</emphasis> - This - <ulink url='https://www.youtube.com/watch?v=QEARDnrR1Xw'>video</ulink> - goes over the Toaster entry page, and provides - an overview of the data manipulation capabilities of - Toaster, which include search, sorting and filtering by - different criteria. - </para></listitem> - <listitem><para><emphasis>Build Dashboard:</emphasis> - This - <ulink url='https://www.youtube.com/watch?v=KKqHYcnp2gE'>video</ulink> - shows you the build dashboard, a page providing an - overview of the information available for a selected build. - </para></listitem> - <listitem><para><emphasis>Image Information:</emphasis> - This - <ulink url='https://www.youtube.com/watch?v=XqYGFsmA0Rw'>video</ulink> - walks through the information Toaster provides - about images: packages installed and root file system. - </para></listitem> - <listitem><para><emphasis>Configuration:</emphasis> - This - <ulink url='https://www.youtube.com/watch?v=UW-j-T2TzIg'>video</ulink> - provides Toaster build configuration information. - </para></listitem> - <listitem><para><emphasis>Tasks:</emphasis> - This - <ulink url='https://www.youtube.com/watch?v=D4-9vGSxQtw'>video</ulink> - shows the information Toaster provides about the - tasks run by the build system. - </para></listitem> - <listitem><para><emphasis>Recipes and Packages Built:</emphasis> - This - <ulink url='https://www.youtube.com/watch?v=x-6dx4huNnw'>video</ulink> - shows the information Toaster provides about recipes - and packages built. - </para></listitem> - <listitem><para><emphasis>Performance Data:</emphasis> - This - <ulink url='https://www.youtube.com/watch?v=qWGMrJoqusQ'>video</ulink> - shows the build performance data provided by - Toaster. - </para></listitem> - </itemizedlist> - </para> - </section> - - <section id='toaster-web-interface-preferred-version'> - <title>Building a Specific Recipe Given Multiple Versions</title> + <listitem><para> + If you used <filename>virtualenv</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: + <literallayout class='monospaced'> + $ source venv/bin/activate + </literallayout> + </para></listitem> + <listitem><para> + From the directory containing the Toaster database, + which by default is the + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>, + invoke the <filename>createsuperuser</filename> command + from <filename>manage.py</filename>: + <literallayout class='monospaced'> + $ cd ~/poky/build + $ ../bitbake/lib/toaster/manage.py createsuperuser + </literallayout> + </para></listitem> + <listitem><para> + Django prompts you for the username, which you need to + provide. + </para></listitem> + <listitem><para> + Django prompts you for an email address, which is + optional. + </para></listitem> + <listitem><para> + Django prompts you for a password, which you must provide. + </para></listitem> + <listitem><para> + Django prompts you to re-enter your password for verification. + </para></listitem> + </orderedlist> + After completing these steps, the following confirmation message + appears: + <literallayout class='monospaced'> + Superuser created successfully. + </literallayout> + </para> + + <para> + Creating a superuser allows you to access the Django administration + interface through a browser. + The URL for this interface is the same as the URL used for the + Toaster instance with "/admin" on the end. + For example, if you are running Toaster locally, use the + following URL: + <literallayout class='monospaced'> + http://127.0.0.1:8000/admin + </literallayout> + You can use the Django administration interface to set Toaster + configuration parameters such as the build directory, layer sources, + default variable values, and BitBake versions. + </para> + </section> + + <section id='toaster-setting-up-a-production-instance-of-toaster'> + <title>Setting Up a Production Instance of Toaster</title> + + <para> + You can use a production instance of Toaster to share the + Toaster instance with remote users, multiple users, or both. + The production instance is also the setup that can handle + heavier loads on the web service. + Use the instructions in the following sections to set up + Toaster to run builds through the Toaster web interface. + </para> + + <section id='toaster-production-instance-requirements'> + <title>Requirements</title> + + <para> + Be sure you meet the following requirements: + <note> + You must comply with all Apache, + <filename>mod-wsgi</filename>, and Mysql requirements. + </note> + <itemizedlist> + <listitem><para> + Have all the build requirements as described in + "<link linkend='toaster-setting-up-the-basic-system-requirements'>Setting Up the Basic System Requirements</link>" + chapter. + </para></listitem> + <listitem><para> + Have an Apache webserver. + </para></listitem> + <listitem><para> + Have <filename>mod-wsgi</filename> for the Apache + webserver. + </para></listitem> + <listitem><para> + Use the Mysql database server. + </para></listitem> + <listitem><para> + If you are using Ubuntu 14.04.3, run the following: + <literallayout class='monospaced'> + $ sudo apt-get install apache2 libapache2-mod-wsgi mysql-server virtualenv libmysqlclient-dev + </literallayout> + </para></listitem> + <listitem><para> + If you are using Fedora 22 or a RedHat distribution, run + the following: + <literallayout class='monospaced'> + $ sudo dnf install httpd mod_wsgi python-virtualenv gcc mysql-devel + </literallayout> + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='toaster-installation-steps'> + <title>Installation</title> + + <para> + Perform the following steps to install Toaster: + <orderedlist> + <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 + 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 + </literallayout> + <note> + Isolating these packages is not required but is + recommended. + Alternatively, you can use your operating system's + package manager to install the packages. + </note> + </para></listitem> + <listitem><para> + Configure Toaster by editing + <filename>/var/www/toaster/poky/bitbake/lib/toaster/toastermain/settings.py</filename> + as follows: + <itemizedlist> + <listitem><para> + Edit the <filename>DATABASE</filename> settings: + <literallayout class='monospaced'> + DATABASES = { + 'default': { + 'ENGINE': 'django.db.backends.mysql', + 'NAME': 'toaster_data', + 'USER': 'toaster', + 'PASSWORD': 'yourpasswordhere', + 'HOST': 'localhost', + 'PORT': '3306', + } + } + </literallayout> + </para></listitem> + <listitem><para> + Edit the <filename>SECRET_KEY</filename>: + <literallayout class='monospaced'> + SECRET_KEY = '<replaceable>your_secret_key</replaceable>' + </literallayout> + </para></listitem> + <listitem><para> + Edit the <filename>STATIC_ROOT</filename>: + <literallayout class='monospaced'> + STATIC_ROOT = '/var/www/toaster/static_files/' + </literallayout> + </para></listitem> + </itemizedlist> + </para></listitem> + <listitem><para> + Add the database and user to the <filename>mysql</filename> + server defined earlier: + <literallayout class='monospaced'> + $ mysql -u root -p + mysql> CREATE DATABASE toaster_data; + mysql> CREATE USER 'toaster'@'localhost' identified by 'yourpasswordhere'; + mysql> GRANT all on toaster_data.* to 'toaster'@'localhost'; + mysql> quit + </literallayout> + </para></listitem> + <listitem><para> + Get Toaster to create the database schema, + 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 + $ ./bitbake/lib/toaster/manage.py collectstatic + </literallayout> + </para> + + <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 + schema has had changes propagated correctly (i.e. + migrations). + </para> + + <para> + The next line sets the Toaster root directory + <filename>TOASTER_DIR</filename> and the location of + the Toaster configuration file + <filename>TOASTER_CONF</filename>, which is + relative to the Toaster root directory + <filename>TOASTER_DIR</filename>. + For more information on the Toaster configuration file + <filename>TOASTER_CONF</filename>, see the + <link linkend='toaster-json-files'>JSON Files</link> + section of this manual. + </para> + + <para> + This line also runs the <filename>checksettings</filename> + command, which configures the location of the Toaster + <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build directory</ulink>. + The Toaster root directory <filename>TOASTER_DIR</filename> + determines where the Toaster build directory + is created on the file system. + In the example above, + <filename>TOASTER_DIR</filename> is set as follows: + <literallayout class="monospaced"> + /var/www/toaster/poky + </literallayout> + This setting causes the Toaster build directory to be: + <literallayout class="monospaced"> + /var/www/toaster/poky/build + </literallayout> + </para> + + <para> + 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. + </para></listitem> + <listitem><para> + Add an Apache configuration file for Toaster to your Apache web + server's configuration directory. + If you are using Ubuntu or Debian, put the file here: + <literallayout class='monospaced'> + /etc/apache2/conf-available/toaster.conf + </literallayout> + If you are using Fedora or RedHat, put it here: + <literallayout class='monospaced'> + /etc/httpd/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 + </Directory> + + WSGIDaemonProcess toaster_wsgi python-path=/var/www/toaster/poky/bitbake/lib/toaster:/var/www/toaster/venv/lib/python2.7/site-packages + + WSGIScriptAlias / "/var/www/toaster/poky/bitbake/lib/toaster/toastermain/wsgi.py" + <Location /> + WSGIProcessGroup toastern_wsgi + </Location> + </literallayout> + If you are using Ubuntu or Debian, + you will need to enable the config and module for Apache: + <literallayout class='monospaced'> + $ sudo a2enmod wsgi + $ sudo a2enconf toaster + $ chmod +x bitbake/lib/toaster/toastermain/wsgi.py + </literallayout> + Finally, restart Apache to make sure all new configuration + is loaded. + For Ubuntu and Debian use: + <literallayout class='monospaced'> + $ sudo service apache2 restart + </literallayout> + For Fedora and RedHat use: + <literallayout class='monospaced'> + $ sudo service httpd restart + </literallayout> + </para></listitem> + <listitem><para> + Install the build runner service. + This service needs to be running in order to dispatch + builds. + Use this command: + <literallayout class='monospaced'> + /var/www/toaster/poky/bitbake/lib/toaster/manage.py runbuilds + </literallayout> + Here is an example: + <literallayout class='monospaced'> + #!/bin/sh + # toaster run builds dispatcher + cd /var/www/toaster/ + source ./venv/bin/activate + ./bitbake/lib/toaster/manage.py runbuilds + </literallayout> + </para></listitem> + </orderedlist> + You can now open up a browser and start using Toaster. + </para> + </section> + </section> + + <section id='using-the-toaster-web-interface'> + <title>Using the Toaster Web Interface</title> + + <para> + The Toaster web interface allows you to do the following: + <itemizedlist> + <listitem><para> + Browse published layers in the + <ulink url='http://layers.openembedded.org'>OpenEmbedded Metadata Index</ulink> + that are available for your selected version of the build + system. + </para></listitem> + <listitem><para> + Import your own layers for building. + </para></listitem> + <listitem><para> + Add and remove layers from your configuration. + </para></listitem> + <listitem><para> + Set configuration variables. + </para></listitem> + <listitem><para> + Select a target or multiple targets to build. + </para></listitem> + <listitem><para> + Start your builds. + </para></listitem> + <listitem><para> + See what was built (recipes and packages) and what + packages were installed into your final image. + </para></listitem> + <listitem><para> + Browse the directory structure of your image. + </para></listitem> + <listitem><para> + See the value of all variables in your build configuration, + and which files set each value. + </para></listitem> + <listitem><para> + Examine error, warning and trace messages to aid in + debugging. + </para></listitem> + <listitem><para> + See information about the BitBake tasks executed and + reused during your build, including those that used + shared state. + </para></listitem> + <listitem><para> + See dependency relationships between recipes, packages + and tasks. + </para></listitem> + <listitem><para> + See performance information such as build time, task time, + CPU usage, and disk I/O. + </para></listitem> + </itemizedlist> + </para> + + <section id='web-interface-videos'> + <title>Toaster Web Interface Videos</title> + + <para> + Following are several videos that show how to use the Toaster GUI: + <itemizedlist> + <listitem><para><emphasis>Build Configuration:</emphasis> + This + <ulink url='https://www.youtube.com/watch?v=qYgDZ8YzV6w'>video</ulink> + overviews and demonstrates build configuration for Toaster. + </para></listitem> + <listitem><para><emphasis>Build Custom Layers:</emphasis> + This + <ulink url='https://www.youtube.com/watch?v=QJzaE_XjX5c'>video</ulink> + shows you how to build custom layers that are used with + Toaster. + </para></listitem> + <listitem><para><emphasis>Toaster Homepage and Table Controls:</emphasis> + This + <ulink url='https://www.youtube.com/watch?v=QEARDnrR1Xw'>video</ulink> + goes over the Toaster entry page, and provides + an overview of the data manipulation capabilities of + Toaster, which include search, sorting and filtering by + different criteria. + </para></listitem> + <listitem><para><emphasis>Build Dashboard:</emphasis> + This + <ulink url='https://www.youtube.com/watch?v=KKqHYcnp2gE'>video</ulink> + shows you the build dashboard, a page providing an + overview of the information available for a selected build. + </para></listitem> + <listitem><para><emphasis>Image Information:</emphasis> + This + <ulink url='https://www.youtube.com/watch?v=XqYGFsmA0Rw'>video</ulink> + walks through the information Toaster provides + about images: packages installed and root file system. + </para></listitem> + <listitem><para><emphasis>Configuration:</emphasis> + This + <ulink url='https://www.youtube.com/watch?v=UW-j-T2TzIg'>video</ulink> + provides Toaster build configuration information. + </para></listitem> + <listitem><para><emphasis>Tasks:</emphasis> + This + <ulink url='https://www.youtube.com/watch?v=D4-9vGSxQtw'>video</ulink> + shows the information Toaster provides about the + tasks run by the build system. + </para></listitem> + <listitem><para><emphasis>Recipes and Packages Built:</emphasis> + This + <ulink url='https://www.youtube.com/watch?v=x-6dx4huNnw'>video</ulink> + shows the information Toaster provides about recipes + and packages built. + </para></listitem> + <listitem><para><emphasis>Performance Data:</emphasis> + This + <ulink url='https://www.youtube.com/watch?v=qWGMrJoqusQ'>video</ulink> + shows the build performance data provided by + Toaster. + </para></listitem> + </itemizedlist> + </para> + </section> + + <section id='a-note-on-the-local-yocto-project-release'> + <title>Additional Information About the Local Yocto Project Release</title> + + <para> + This section only applies if you have set up Toaster + for local development, as explained in the + "<link linkend='starting-toaster-for-local-development'>Starting Toaster for Local Development</link>" + section. + </para> + + <para> + When you create a project in Toaster, you will be asked to + provide a name and to select a Yocto Project release. + One of the release options you will find is called + "Local Yocto Project". + <imagedata fileref="figures/new-project.png" align="center" width="9in" /> + </para> + + <para> + When you select the "Local Yocto Project" release, Toaster + will run your builds using the local Yocto + Project clone you have in your computer: the same clone + you are using to run Toaster. + Unless you manually update + this clone, your builds will always use the same Git revision. + </para> + + <para> + If you select any of the other release options, Toaster + will fetch the tip of your selected release from the upstream + <ulink url='https://git.yoctoproject.org'>Yocto Project repository</ulink> + every time you run a build. + Fetching this tip effectively + means that if your selected release is updated upstream, the + Git revision you are using for your builds will change. + If you are doing development locally, you might not want this + change to happen. + In that case, the "Local Yocto Project" + release might be the right choice. + </para> + + <para> + However, the "Local Yocto Project" release + will not provide you with any compatible layers, other than the + three core layers that come with the Yocto Project: + <itemizedlist> + <listitem><para> + <ulink url='http://layers.openembedded.org/layerindex/branch/master/layer/openembedded-core/'>openembedded-core</ulink> + </para></listitem> + <listitem><para> + <ulink url='http://layers.openembedded.org/layerindex/branch/master/layer/meta-poky/'>meta-poky</ulink> + </para></listitem> + <listitem><para> + <ulink url='http://layers.openembedded.org/layerindex/branch/master/layer/meta-yocto-bsp/'>meta-yocto-bsp</ulink> + </para></listitem> + </itemizedlist> + <imagedata fileref="figures/compatible-layers.png" align="center" width="9in" /> + </para> + + <para> + If you want to build any other layers, you will need to + manually import them into your Toaster project, using the + "Import layer" page. + <imagedata fileref="figures/import-layer.png" align="center" width="9in" /> + </para> + + </section> + + <section id='toaster-web-interface-preferred-version'> + <title>Building a Specific Recipe Given Multiple Versions</title> <para> Occasionally, a layer might provide more than one version of @@ -1461,105 +674,4 @@ </para> </section> </section> - -<!-- - <section id='toaster-gui-vids-1'> - <title>Toaster Homepage and Table Controls</title> - - <para> - This video goes over the Toaster entry page, and provides - an overview of the data manipulation capabilities of Toaster, - which include search, sorting and filtering by different - criteria. - <mediaobject> - <videoobject> - <videodata width="640" height="480" fileref="http://www.youtube.com/v/QEARDnrR1Xw"></videodata> - </videoobject> - </mediaobject> - </para> - </section> - - <section id='toaster-gui-vids-2'> - <title>Build Dashboard</title> - - <para> - This video shows you the build dashboard, a page providing an - overview of the information available for a selected build. - <mediaobject> - <videoobject> - <videodata width="640px" height="480px" fileref="http://www.youtube.com/v/KKqHYcnp2gE"></videodata> - </videoobject> - </mediaobject> - </para> - </section> - - <section id='toaster-gui-vids-3'> - <title>Image Information</title> - - <para> - This video walks through the information Toaster provides - about images: packages installed and root file system. - <mediaobject> - <videoobject> - <videodata width="640px" height="480px" fileref="http://www.youtube.com/v/XqYGFsmA0Rw"></videodata> - </videoobject> - </mediaobject> - </para> - </section> - - <section id='toaster-gui-vids-4'> - <title>Configuration</title> - - <para> - This video shows the information Toaster provides about build - configuration. - <mediaobject> - <videoobject> - <videodata width="640px" height="480px" fileref="http://www.youtube.com/v/UW-j-T2TzIg"></videodata> - </videoobject> - </mediaobject> - </para> - </section> - - <section id='toaster-gui-vids-5'> - <title>Tasks</title> - - <para> - This video shows the information Toaster provides about the - tasks run by the build system. - <mediaobject> - <videoobject> - <videodata width="640px" height="480px" fileref="http://www.youtube.com/v/D4-9vGSxQtw"></videodata> - </videoobject> - </mediaobject> - </para> - </section> - - <section id='toaster-gui-vids-6'> - <title>Recipes and Packages Built</title> - - <para> - This video shows the information Toaster provides about recipes - and packages built. - <mediaobject> - <videoobject> - <videodata width="640px" height="480px" fileref="http://www.youtube.com/v/x-6dx4huNnw"></videodata> - </videoobject> - </mediaobject>qYgDZ8YzV6w - </para> - </section> - <section id='toaster-gui-vids-7'> - <title>Performance Data</title> - - <para> - This video shows the build performance data provided by - Toaster. - <mediaobject> - <videoobject> - <videodata width="640px" height="480px" fileref="http://www.youtube.com/v/qWGMrJoqusQ"></videodata> - </videoobject> - </mediaobject> - </para> - </section> ---> </chapter> diff --git a/yocto-poky/documentation/toaster-manual/toaster-manual.xml b/yocto-poky/documentation/toaster-manual/toaster-manual.xml index 59dca8f62..7a8912a6e 100644 --- a/yocto-poky/documentation/toaster-manual/toaster-manual.xml +++ b/yocto-poky/documentation/toaster-manual/toaster-manual.xml @@ -41,6 +41,11 @@ <date>October 2015</date> <revremark>Released with the Yocto Project 2.0 Release.</revremark> </revision> + <revision> + <revnumber>2.1</revnumber> + <date>April 2016</date> + <revremark>Released with the Yocto Project 2.1 Release.</revremark> + </revision> </revhistory> <copyright> diff --git a/yocto-poky/documentation/tools/mega-manual.sed b/yocto-poky/documentation/tools/mega-manual.sed index 088a99b34..5a3bdf9fb 100644 --- a/yocto-poky/documentation/tools/mega-manual.sed +++ b/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.0\/[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.0\/yocto-project-qs\/yocto-project-qs.html#/\"link\" href=\"#/g -s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.0\/poky-ref-manual\/poky-ref-manual.html#/\"link\" href=\"#/g +# 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 # 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.0\/[a-z]*-[a-z]*\/[a-z]*-[a-z]*.html#/\"link\" href=\"#/g +# 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.0\/adt-manual\/adt-manual.html#/\"link\" href=\"#/g -s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.0\/bsp-guide\/bsp-guide.html#/\"link\" href=\"#/g -s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.0\/dev-manual\/dev-manual.html#/\"link\" href=\"#/g -s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.0\/kernel-dev\/kernel-dev.html#/\"link\" href=\"#/g -s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.0\/profile-manual\/profile-manual.html#/\"link\" href=\"#/g -s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.0\/ref-manual\/ref-manual.html#/\"link\" href=\"#/g -s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.0\/toaster-manual\/toaster-manual.html#/\"link\" href=\"#/g -s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.0\/yocto-project-qs\/yocto-project-qs.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 # Process cases where just an external manual is referenced without an id anchor -s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.0\/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.0\/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.0\/adt-manual\/adt-manual.html\" target=\"_top\">Yocto Project Application Developer's Guide<\/a>/Yocto Project Application Developer's Guide/g -s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/2.0\/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.0\/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.0\/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.0\/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.0\/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.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 diff --git a/yocto-poky/documentation/yocto-project-qs/yocto-project-qs.xml b/yocto-poky/documentation/yocto-project-qs/yocto-project-qs.xml index 5315dfec6..c09e971d6 100644 --- a/yocto-poky/documentation/yocto-project-qs/yocto-project-qs.xml +++ b/yocto-poky/documentation/yocto-project-qs/yocto-project-qs.xml @@ -60,7 +60,7 @@ </para> <para> - This quick start is written so that you can quickly get a host + This quick start is written so that you can quickly get a build host set up to use the Yocto Project and then build some Linux images. Rather than go into great detail about the Yocto Project and its @@ -71,7 +71,7 @@ basic understanding of what the Yocto Project is and how to use some of its core components. You will also have worked through steps to produce two images: - one suitable for emulation and one that can be used on actual + one that is suitable for emulation and one that boots on actual hardware. The examples highlight the ease with which you can use the Yocto Project to create images for multiple types of hardware. @@ -249,7 +249,7 @@ Git, tar, and Python. <itemizedlist> <listitem><para> - Git 1.7.8 or greater + Git 1.8.3.1 or greater </para></listitem> <listitem><para> tar 1.24 or greater @@ -360,7 +360,7 @@ remote: Total 226790 (delta 165212), reused 225887 (delta 164327) Receiving objects: 100% (226790/226790), 100.98 MiB | 263 KiB/s, done. Resolving deltas: 100% (165212/165212), done. - $ git checkout &DISTRO_NAME; + $ git checkout &DISTRO_NAME_NO_CAP; </literallayout> You can also get the Yocto Project Files by downloading Yocto Project releases from the @@ -381,8 +381,19 @@ <para> Now that you have your system requirements in order, you can give - the Yocto Project a try. - This section presents steps that let you do the following: + Yocto Project a try. + You can try out Yocto Project using either the command-line + interface or using Toaster, which uses a graphical user + interface. + If you want to try out the Yocto Project using a GUI, see the + <ulink url='&YOCTO_DOCS_TOAST_URL;'>Toaster User Manual</ulink> + for information on how to install and set up Toaster. + </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 + do the following: <itemizedlist> <listitem><para> Build a <filename>qemux86</filename> reference image @@ -453,12 +464,12 @@ Release: <literallayout class='monospaced'> $ cd ~/poky - $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME; + $ 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;</filename>). + <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 @@ -539,7 +550,7 @@ 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>" + "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-package'><filename>package.bbclass</filename></ulink>" section in the Yocto Project Reference Manual. </para></listitem> </itemizedlist> @@ -587,7 +598,7 @@ </orderedlist> </para> - <para> + <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 @@ -610,17 +621,36 @@ 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: + 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'... - remote: Counting objects: 10824, done. - remote: Compressing objects: 100% (3508/3508), done. - remote: Total 10824 (delta 6219), reused 10580 (delta 5975) - Receiving objects: 100% (10824/10824), 2.72 MiB | 482.00 KiB/s, done. - Resolving deltas: 100% (6219/6219), done. + remote: Counting objects: 11988, done. + remote: Compressing objects: 100% (3884/3884), done. + Receiving objects: 100% (11988/11988), 2.93 MiB | 2.51 MiB/s, done. + 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'> + $ 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 @@ -639,7 +669,8 @@ <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> variable. <literallayout class='monospaced'> - $ bitbake-layers add-layer "$HOME/source/poky/meta-intel" + $ 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> @@ -725,7 +756,7 @@ <para> If you completed all the steps in the previous section then - congratulations to you! + congratulations! What now? </para> @@ -740,37 +771,42 @@ Visiting this site is a good way to familiarize yourself with the overall project. </para></listitem> - <listitem><para><emphasis>Explore Development Models:</emphasis> - You can see the - "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-model'>Common Development Models</ulink>" - section in the Yocto Project Development Manual - to get an overview of the various ways by which - you can use the Yocto Project to develop projects. - </para></listitem> - <listitem><para><emphasis>Learn Some Open Source Basics:</emphasis> - If you are new to the open source environment, you might - read the - "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-newbie'>The Yocto Project Open Source Development Environment</ulink>" - chapter of the Yocto Project Development Manual. - This chapter presents overview material for open source - development in the context of the Yocto Project. + <listitem><para><emphasis>Look Through the Yocto Project Development Manual:</emphasis> + The + <ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-intro'>Yocto Project Development Manual</ulink> + is a great place to get a feel for how to use the Yocto + Project. + The manual contains conceptual and procedural information + that covers + <ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-model'>common development models</ulink> + and introduces + <ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-newbie'>the Yocto Project open source development environment</ulink>. + The manual also contains several targeted sections that + cover specific + <ulink url='&YOCTO_DOCS_DEV_URL;#extendpoky'>common tasks</ulink> + such as understanding and creating layers, customizing + images, writing new recipes, working with libraries, and + configuring and patching the kernel. </para></listitem> - <listitem><para><emphasis>Learn About Application Development:</emphasis> - If your primary interests lie in developing applications, - you can reference the - <ulink url='&YOCTO_DOCS_ADT_URL;#adt-manual-intro'>Yocto Project Application Developer's Guide</ulink>. + <listitem><para><emphasis>Look Through the Yocto Project Software Development Kit (SDK) Developer's Guide:</emphasis> + The + <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-intro'>Yocto Project Software Development Kit (SDK) Developer's Guide</ulink> + describes how to use both the + <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-using-the-standard-sdk'>standard SDK</ulink> + and the + <ulink url='&YOCTO_DOCS_SDK_URL;#sdk-extensible'>extensible SDK</ulink>, + which are used primarily for application development. + This manual also provides an example workflow that uses + the popular <trademark class='trade'>Eclipse</trademark> + development environment. + See the + "<ulink url='&YOCTO_DOCS_SDK_URL;#workflow-using-eclipse'>Workflow using Eclipse™</ulink>" + section. </para></listitem> <listitem><para><emphasis>Learn About Board Support Packages (BSPs):</emphasis> If you want to learn about BSPs, see the <ulink url='&YOCTO_DOCS_BSP_URL;#bsp'>Yocto Project Board Support Packages (BSP) Developer's Guide</ulink>. </para></listitem> - <listitem><para><emphasis>Learn About Using Eclipse With the Yocto Project:</emphasis> - If you are an Eclipse user, you can learn about using the - Yocto Project in that development environment by reading - the - "<ulink url='&YOCTO_DOCS_DEV_URL;#workflow-using-the-adt-and-eclipse'>Workflow Using the ADT and Eclipse™</ulink>" - section in the Yocto Project Development Manual. - </para></listitem> <listitem><para><emphasis>Learn About Toaster:</emphasis> Toaster is a web interface to the Yocto Project's OpenEmbedded build system. @@ -778,13 +814,30 @@ create images, see the <ulink url='&YOCTO_DOCS_TOAST_URL;#toaster-manual-intro'>Toaster User Manual</ulink>. </para></listitem> - <listitem><para><emphasis>Explore Yocto Project Common Tasks and Technical Details:</emphasis> - If you are interested in a mix of common tasks that have to - do with project develop using the Yocto Project, see the - "<ulink url='&YOCTO_DOCS_DEV_URL;#extendpoky'>Common Tasks</ulink>" - section of the Yocto Project Development Manual. - If you want more detail, see the - <ulink url='&YOCTO_DOCS_REF_URL;#ref-manual-intro'>Yocto Project Reference Manual</ulink>. + <listitem><para><emphasis>Have Available the Yocto Project Reference Manual</emphasis> + The + <ulink url='&YOCTO_DOCS_REF_URL;#ref-manual-intro'>Yocto Project Reference Manual</ulink>, + unlike the rest of the Yocto Project manual set, is + comprised of material suited for reference rather than + procedures. + You can get + <ulink url='&YOCTO_DOCS_REF_URL;#usingpoky'>build details</ulink>, + a + <ulink url='&YOCTO_DOCS_REF_URL;#closer-look'>closer look</ulink> + at how the pieces of the Yocto Project development + environment work together, information on various + <ulink url='&YOCTO_DOCS_REF_URL;#technical-details'>technical details</ulink>, + guidance on + <ulink url='&YOCTO_DOCS_REF_URL;#migration'>migrating to a newer Yocto Project release</ulink>, + reference material on the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-structure'>directory structure</ulink>, + <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes'>classes</ulink>, + and + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks'>tasks</ulink>. + The Yocto Project Reference Manual also contains a fairly + comprehensive + <ulink url='&YOCTO_DOCS_REF_URL;#ref-variables-glossary'>glossary of variables</ulink> + used within the Yocto Project. </para></listitem> </itemizedlist> </para> |
